z-image

Z-Image - ModelScope Tongyi Wanxiang Image Generation

Unified Z-Image-Turbo text-to-image capability, with 24+ built-in visual style templates and support for automatic style detection.

Quick Start

# 基础文生图
python ~/.claude/skills/z-image/scripts/generate.py "一个程序员在深夜写代码"

# 指定风格
python ~/.claude/skills/z-image/scripts/generate.py "武侠少年仗剑天涯" --style anime_shonen

# 自动检测风格
python ~/.claude/skills/z-image/scripts/generate.py "纳瓦尔的智慧哲学" --auto-style

# 批量生成
python ~/.claude/skills/z-image/scripts/generate.py prompts.txt --batch --style neon_wisdom

List all styles

python ~/.claude/skills/z-image/scripts/generate.py --list-styles

## Triggers

- `生成图片` / `生图` / `做图`
- `z-image generate`
- `用万相生成`
- `text to image`
- `generate image with style`

## Quick Reference

| Feature | Detail |
|---------|--------|
| API | ModelScope `api-inference.modelscope.cn` |
| Model | `Tongyi-MAI/Z-Image-Turbo` |
| Cost | ~$0.01/image |
| Styles | 24+ presets in 7 categories |
| Auto-detect | Keyword chain + LLM fallback |
| Output | PNG, 1024x1024 default |
| Async | Submit + poll pattern |

## How It Works

User input (prompt + style) │ ▼ ┌─────────────────────────────┐ │ 1. Style Resolution │ │ • Specified style → use directly │ │ • --auto-style → detection chain │ │ Keyword → LLM fallback │ │ • Default → anime_japanese │ ├─────────────────────────────┤ │ 2. Prompt Enhancement │ │ • base_style + colors │ │ • lighting + modifiers │ │ • negative prompt │ ├─────────────────────────────┤ │ 3. API Call (Async) │ │ • POST /v1/images/gen │ │ • Poll task status │ │ • Download result │ ├─────────────────────────────┤ │ 4. Post-processing │ │ • Resize to target │ │ • Save to output dir │ └─────────────────────────────┘

## Style Categories

| Category | Styles | Best For |
|----------|--------|----------|
| **Anime** (5) | anime_japanese, anime_chibi, anime_shonen, anime_iyashikei, anime_cyberpunk | 故事/角色/动漫内容 |
| **Neon** (6) | neon_wisdom, neon_tech, neon_wealth, neon_contrast, neon_timeline, neon_mindmap | 知识/商业/哲理内容 |
| **Tech** (2) | tech_dark, tech_light | 科技/产品展示 |
| **Documentary** (3) | documentary, vintage_50s, vintage_80s | 传记/历史/纪录片 |
| **Art** (3) | watercolor, ink_chinese, comic_style | 艺术/文化内容 |
| **Minimal** (2) | minimal_white, flat_design | 简约/解释类内容 |
| **Mood** (2) | warm_cozy, dark_dramatic | 氛围/情感内容 |

## Commands

| Command | Description |
|---------|-------------|
| `generate.py "prompt"` | 生成单张图片 |
| `generate.py "prompt" --style X` | 指定风格生成 |
| `generate.py "prompt" --auto-style` | 自动检测风格 |
| `generate.py prompts.txt --batch` | 批量生成 |
| `generate.py --list-styles` | 列出所有风格 |
| `generate.py --list-styles --category anime` | 按分类列出 |
| `generate.py "prompt" --size 1920x1080` | 指定尺寸 |
| `generate.py "prompt" --output ./my-images/` | 指定输出目录 |

## Configuration

API Key 配置优先级：
1. `--api-key` 命令行参数
2. `MODELSCOPE_API_KEY` 环境变量
3. `~/.claude/skills/z-image/config/secrets.md` 文件

```bash
# 方式1: 环境变量
export MODELSCOPE_API_KEY="ms-xxxxx"

# 方式2: 配置文件
echo "API_KEY=ms-xxxxx" > ~/.claude/skills/z-image/config/secrets.md

Scripts

scripts/generate.py - CLI entry point

The main image generation script, supporting single and batch modes.

# 单张生成
python scripts/generate.py "赛博朋克城市夜景" --style anime_cyberpunk --output ./output/

# 批量生成（从文件读取 prompt）
python scripts/generate.py prompts.txt --batch --style neon_tech

# 自动风格检测
python scripts/generate.py "纳瓦尔谈财富自由" --auto-style

Exit codes: 0=success, 1=failure, 10=API error, 11=style not found

scripts/style_templates.py - Style template library

24+ visual style definitions and automatic detection logic. Can be imported and used independently:

from style_templates import get_style_prompt, auto_detect_style, STYLES

# 获取增强后的 prompt
enhanced = get_style_prompt("一个少年在山顶", "anime_shonen")

# 自动检测风格
style = auto_detect_style("纳瓦尔的智慧与幸福哲学")  # → "neon_wisdom"

# 列出所有风格
for sid, s in STYLES.items():
    print(f"{sid}: {s.name} - {s.description}")

Integration

Other skills can directly call z-image:

import sys
sys.path.insert(0, str(Path.home() / ".claude/skills/z-image/scripts"))
from generate import ZImageClient

client = ZImageClient(api_key="ms-xxx")
result = await client.generate("prompt", style="neon_wisdom")
print(result)  # 图片路径

Dependent Skills

The following skills depend on z-image capabilities:

Skill	Usage
video-skill	Video cover and frame image generation
image-fenjing	Storyboard image generation
videofree	Profile-based video images
voice-first-video	Voice video illustrations
novel-to-video	Web novel to video illustrations
hunhe-video	Mixed video image generation

Anti-Patterns

Avoid	Why	Instead
Hardcoded API Key	Security risk	Use environment variables or secrets.md
Skip style enhancement	Poor generation quality	Always use style template
Synchronously wait for API	Block process	Use async + polling
Ignore negative prompt	Artifacts appear	Each style has its own dedicated negative

Verification

• python scripts/generate.py --list-styles Output 24+ styles
• python scripts/generate.py "test" --dry-run Output the enhanced prompt
• API Key configured correctly (environment variables or secrets.md)
• Generated images saved to the specified directory