qwencloud-image-generation

What this skill does

> **Agent setup**: If your agent doesn't auto-load skills (e.g. Claude Code),
> see [agent-compatibility.md](references/agent-compatibility.md) once per session.

# Qwen Image Generation

Generate and edit images using Wan and Qwen Image models. Supports text-to-image, reference-image editing (style
transfer, subject consistency, multi-image composition, text rendering), and interleaved text-image output.
This skill is part of **qwencloud/qwencloud-ai**.

## Skill directory

Use this skill's internal files to execute and learn. Load reference files on demand when the default path fails or you need details.

| Location | Purpose |
|----------|---------|
| `scripts/image.py` | Default execution — sync/async, upload, download |
| `references/execution-guide.md` | Fallback: curl (sync/async), code generation |
| `references/prompt-guide.md` | Prompt formulas, style keywords, negative_prompt, prompt_extend decision |
| `references/api-guide.md` | API supplement |
| `references/sources.md` | Official documentation URLs |
| `references/agent-compatibility.md` | Agent self-check: register skills in project config for agents that don't auto-load |

## Security

**NEVER output any API key or credential in plaintext.** Always use variable references (`$DASHSCOPE_API_KEY` in shell, `os.environ["DASHSCOPE_API_KEY"]` in Python). Any check or detection of credentials must be **non-plaintext**: report only status (e.g. "set" / "not set", "valid" / "invalid"), never the value. Never display contents of `.env` or config files that may contain secrets.

**When the API key is not configured, NEVER ask the user to provide it directly.** Instead, help create a `.env` file with a placeholder (`DASHSCOPE_API_KEY=sk-your-key-here`) and instruct the user to replace it with their actual key from the [QwenCloud Console](https://home.qwencloud.com/api-keys). Only write the actual key value if the user explicitly requests it.

## Key Compatibility

Scripts require a **standard QwenCloud API key** (`sk-...`). Coding Plan keys (`sk-sp-...`) cannot be used — image generation models are not available on Coding Plan, and Coding Plan does not support the native QwenCloud API. The script detects `sk-sp-` keys at startup and prints a warning. If qwencloud-ops-auth is installed, see its `references/codingplan.md` for full details.

## Mode Selection Guide

| User Want | Mode | Model |
|-----------|------|-------|
| Generate image from text only | **t2i** | `wan2.6-t2i` (default), or `wan2.7-image` / `wan2.7-image-pro` |
| Edit image / apply style transfer based on 1–4 reference images | **image-edit** | `wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image` |
| Subject consistency: generate new images maintaining subject from references | **image-edit** | `wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image` |
| Multi-image composition: combine style from one image, background from another | **image-edit** | `wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image` |
| Single-image editing preserving subject consistency | **i2i** | `wan2.5-i2i-preview` |
| Multi-image fusion: place object from one image into another scene | **i2i** | `wan2.5-i2i-preview` |
| Interleaved text-image output (e.g., tutorials, step-by-step guides) | **interleave** | `wan2.6-image` |
| Fast text-to-image drafts | **t2i** | `wan2.2-t2i-flash` |
| Edit text within images, precise element manipulation | **image-edit** | `qwen-image-2.0-pro` |
| Multi-image fusion with realistic textures | **image-edit** | `qwen-image-2.0-pro` |
| Posters / complex Chinese+English text rendering | **t2i** | `qwen-image-2.0-pro` |
| Text-to-image with fixed aspect ratios (batch) | **t2i** | `qwen-image-plus` / `qwen-image-max` |

## Model Selection

### Wan Series (default)

| Model | Use Case |
|-------|----------|
| **wan2.6-t2i** | **Recommended for text-to-image** — sync + async, best quality |
| **wan2.7-image-pro** | **Multi-function** (4K support) — text-to-image, image editing (0–9 images), sequential multi-image, interactive editing (bbox), thinking mode, color palette. Max 4K for t2i, 2K for editing |
| **wan2.7-image** | **Multi-function** (faster) — same as pro but max 2K, no 4K support |
| **wan2.6-image** | **Image editing** (NOT for pure text-to-image) — requires `reference_images` or `enable_interleave: true`. Style transfer, subject consistency (1–4 images), interleaved text-image output, 2K |
| **wan2.5-i2i-preview** | **Image editing** — single-image editing with subject consistency, multi-image fusion (up to 3 images), async-only |
| **wan2.5-t2i-preview** | Preview — free size within constraints |
| **wan2.2-t2i-flash** | Fast — lower latency |
| **wan2.2-t2i-plus** | Professional — improved stability |

### Qwen Image Series

| Model | Use Case |
|-------|----------|
| **qwen-image-2.0-pro** | Fused generation + editing — text rendering, realistic textures, multi-image (1–3 input, 1–6 output) |
| **qwen-image-2.0** | Accelerated generation + editing |
| **qwen-image-edit-max** | Image editing — 1–6 output images |
| **qwen-image-edit-plus** | Image editing — 1–6 output images |
| **qwen-image-edit** | Image editing — 1 output image only |
| **qwen-image-plus** | Text-to-image — fixed resolutions only (async) |
| **qwen-image-max** | Text-to-image — fixed resolutions only |

Qwen Image editing models (`qwen-image-2.0-pro`, `qwen-image-2.0`, `qwen-image-edit-max/plus/edit`) use the same sync endpoint as `wan2.6-image` (`/multimodal-generation/generation`) with `messages` format. They support text editing in images, element add/delete/replace, style transfer, and multi-image fusion (1–3 input images). Size range: 512x512 to 2048x2048. `qwen-image-2.0-pro` and `qwen-image-2.0` also support pure text-to-image (no reference images needed).

Qwen Image text-to-image models (`qwen-image-plus`, `qwen-image-max`) use a different endpoint (`/text2image/image-synthesis`) with `input.prompt` format (async-only). They support only 5 fixed resolutions: 1664\*928, 1472\*1104, 1328\*1328, 1104\*1472, 928\*1664.

**Choosing between `wan2.6-image` and `wan2.5-i2i-preview` for image editing:**
- `wan2.6-image` supports up to 4 images, higher resolution (2K), interleaved text-image output, and sync mode. Use for multi-image style composition, interleaved tutorials.
- `wan2.5-i2i-preview` uses a simpler prompt-only editing interface (no messages format), supports up to 3 images, async-only. Use for straightforward single-image edits and multi-image object fusion.

1. **User specified a model** → use directly.
2. **Consult the qwencloud-model-selector skill** when model choice depends on requirement, scenario, or pricing.
3. **Text-to-image (prompt only, no reference images)** → use `wan2.6-t2i` (default) or `wan2.7-image` / `wan2.7-image-pro` (multi-function, higher quality). **NEVER use `wan2.6-image` for pure text-to-image** — it will error without reference images or `enable_interleave: true`.
4. **Reference images / image editing / interleaved output** → `wan2.7-image-pro` (recommended), `wan2.7-image`, or `wan2.6-image`.

> **⚠️ Important**: The model list above is a **point-in-time snapshot** and may be outdated. Model availability
> changes frequently. **Always check the [official model list](https://www.qwencloud.com/models)
> for the authoritative, up-to-date catalog before making model decisions.**

> **Model details**: For more information about a specific model, direct the user to its detail page: `https://www.qwencloud.com/models/<model-name>` (replace `<model-name>` with the exact model ID, e.g. `wan2.7-image-pro` → https://www.qwencloud.com/models/wan2.7-image-pro). NEVER modify or guess the model name in the URL.

> **Dynamic model queries**: If the **qwencloud-model-selector** skill or **QwenCloud CLI** (`qwencloud models info <model>`) is available, use it for real-time model data. CLI requires authentication — see the **qwencloud-usage** skill for login flow.

## Execution

> **⚠️ Multiple artifacts**: When generating