qianwen-image-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Agent设置：如果你的Agent不会自动加载技能（例如Claude Code），请在每个会话中查看agent-compatibility.md。

Qwen Image Generation

Qwen图像生成

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 QianWen-AI/qianwen-ai.

使用Wan和Qwen Image模型生成和编辑图像。支持文本转图像、参考图像编辑（风格迁移、主体一致性、多图像合成、文本渲染）以及文本-图像交错输出。此技能属于QianWen-AI/qianwen-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

使用此技能的内部文件来执行操作和学习。当默认路径失效或需要详细信息时，按需加载参考文件。

位置	用途
`scripts/image.py`	默认执行脚本 — 同步/异步、上传、下载
`references/execution-guide.md`	备选方案：curl（同步/异步）、代码生成
`references/prompt-guide.md`	提示词公式、风格关键词、negative_prompt、prompt_extend决策规则
`references/api-guide.md`	API补充说明
`references/sources.md`	官方文档URL
`references/agent-compatibility.md`	Agent自检：针对不会自动加载技能的Agent，在项目配置中注册技能

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 QianWen Console. Only write the actual key value if the user explicitly requests it.

绝对不要明文输出任何API密钥或凭证。请始终使用变量引用（Shell中使用

$DASHSCOPE_API_KEY

，Python中使用

os.environ["DASHSCOPE_API_KEY"]

）。任何对凭证的检查或检测必须以非明文方式进行：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不能泄露密钥值。永远不要显示

.env

或可能包含机密信息的配置文件内容。

当API密钥未配置时，绝对不要直接要求用户提供密钥。而是帮助用户创建一个带有占位符的

.env

文件（

DASHSCOPE_API_KEY=sk-your-key-here

），并指导用户从QianWen控制台获取实际密钥后替换占位符。仅当用户明确要求时，才写入实际密钥值。

Key Compatibility

密钥兼容性

Scripts require a standard QianWen API key (

sk-...

). Token Plan 团队版 keys (

sk-sp-...

) target a different endpoint (

token-plan.cn-beijing.maas.aliyuncs.com

) and cannot be used by these scripts. Token Plan does include 4 image generation models (qwen-image-2.0, qwen-image-2.0-pro, wan2.7-image, wan2.7-image-pro), but they are accessed only through interactive AI tools' Skill / Slash Command / Agent mechanism against a dedicated multimodal-generation endpoint — not via this skill's standard DashScope flow. Standard

sk-

key required for this skill. The script detects

sk-sp-

keys at startup and prints a warning. If qianwen-ops-auth is installed, see its

references/tokenplan.md

for full details.

脚本需要标准QianWen API密钥（格式为

sk-...

）。Token Plan团队版密钥（格式为

sk-sp-...

）指向不同的端点（

token-plan.cn-beijing.maas.aliyuncs.com

），无法用于这些脚本。Token Plan确实包含4个图像生成模型（qwen-image-2.0、qwen-image-2.0-pro、wan2.7-image、wan2.7-image-pro），但这些模型只能通过交互式AI工具的Skill/斜杠命令/Agent机制访问专用的多模态生成端点，而非通过此技能的标准DashScope流程。使用此技能必须使用标准的

sk-

格式密钥。脚本启动时会检测

sk-sp-

格式密钥并打印警告。如果已安装qianwen-ops-auth，请查看其

references/tokenplan.md

获取详细信息。

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`
Open-source / lowest-cost text-to-image	t2i	`z-image-turbo` (sync-only; no `n` ; no reference images)
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`

用户需求	模式	模型
仅通过文本生成图像	t2i	`wan2.6-t2i` （默认），或 `wan2.7-image` / `wan2.7-image-pro`
开源/低成本文本转图像	t2i	`z-image-turbo` （仅支持同步；不支持 `n` 参数；不支持参考图像）
基于1-4张参考图像编辑图像/应用风格迁移	image-edit	`wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image`
主体一致性：基于参考图像生成保留主体的新图像	image-edit	`wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image`
多图像合成：融合一张图像的风格与另一张图像的背景	image-edit	`wan2.7-image-pro` / `wan2.7-image` / `wan2.6-image`
保留主体一致性的单图像编辑	i2i	`wan2.5-i2i-preview`
多图像融合：将一张图像中的物体放入另一张图像的场景中	i2i	`wan2.5-i2i-preview`
文本-图像交错输出（例如教程、分步指南）	interleave	`wan2.6-image`
快速生成文本转图像草稿	t2i	`wan2.2-t2i-flash`
编辑图像中的文本、精确元素操作	image-edit	`qwen-image-2.0-pro`
具有真实纹理的多图像融合	image-edit	`qwen-image-2.0-pro`
海报/复杂中英文文本渲染	t2i	`qwen-image-2.0-pro`
固定宽高比的批量文本转图像	t2i	`qwen-image-plus` / `qwen-image-max`

Model Selection

模型选择

Wan Series (default)

Wan系列（默认）

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

模型	使用场景
wan2.6-t2i	文本转图像推荐模型 — 支持同步+异步，画质最优
wan2.7-image-pro	多功能模型（支持4K）— 文本转图像、图像编辑（0-9张图像）、序列多图像、交互式编辑（bbox）、思维模式、调色板。文本转图像最大支持4K，编辑模式最大支持2K
wan2.7-image	多功能模型（速度更快）— 功能与pro版一致，但最大仅支持2K，无4K功能
wan2.6-image	图像编辑专用（不支持纯文本转图像）— 需要 `reference_images` 或 `enable_interleave: true` 。支持风格迁移、主体一致性（1-4张图像）、文本-图像交错输出，最大支持2K
wan2.5-i2i-preview	图像编辑专用 — 支持保留主体一致性的单图像编辑、多图像融合（最多3张图像），仅支持异步
wan2.5-t2i-preview	预览版 — 在限制范围内支持自定义尺寸
wan2.2-t2i-flash	快速版 — 延迟更低
wan2.2-t2i-plus	专业版 — 稳定性提升

Other

其他模型

Model	Use Case
z-image-turbo	Open-source SOTA T2I — sync-only; single text content per message; no `n` parameter (server returns 400 if provided); no reference images. Parameters: `size` , `prompt_extend` , `seed` .

模型	使用场景
z-image-turbo	开源SOTA文本转图像模型 — 仅支持同步；每条消息仅支持单文本内容；不支持 `n` 参数（若提供，服务器会返回400错误）；不支持参考图像。支持参数： `size` 、 `prompt_extend` 、 `seed` 。

Qwen Image Series

Qwen Image系列

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.

User specified a model → use directly.
Consult the qianwen-model-selector skill when model choice depends on requirement, scenario, or pricing.
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
```
.
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 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.qianwenai.com/models/<model-name>
(replace
<model-name>
with the exact model ID, e.g.
wan2.7-image-pro
→ https://www.qianwenai.com/models/wan2.7-image-pro). NEVER modify or guess the model name in the URL.

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

模型	使用场景
qwen-image-2.0-pro	融合生成+编辑 — 文本渲染、真实纹理、多图像（1-3张输入，1-6张输出）
qwen-image-2.0	加速生成+编辑
qwen-image-edit-max	图像编辑 — 支持1-6张输出图像
qwen-image-edit-plus	图像编辑 — 支持1-6张输出图像
qwen-image-edit	图像编辑 — 仅支持1张输出图像
qwen-image-plus	文本转图像 — 仅支持固定分辨率（仅异步）
qwen-image-max	文本转图像 — 仅支持固定分辨率

Qwen Image编辑模型（

qwen-image-2.0-pro

、

qwen-image-2.0

、

qwen-image-edit-max/plus/edit

）使用与

wan2.6-image

相同的同步端点（

/multimodal-generation/generation

），采用

messages

格式。它们支持图像中文本编辑、元素添加/删除/替换、风格迁移以及多图像融合（1-3张输入图像）。尺寸范围：512x512至2048x2048。

qwen-image-2.0-pro

和

qwen-image-2.0

也支持纯文本转图像（无需参考图像）。

Qwen Image文本转图像模型（

qwen-image-plus

、

qwen-image-max

）使用不同的端点（

/text2image/image-synthesis

），采用

input.prompt

格式（仅支持异步）。它们仅支持5种固定分辨率：1664928、14721104、13281328、11041472、928*1664。

图像编辑场景下
wan2.6-image
与
wan2.5-i2i-preview
的选择：

```
wan2.6-image
```
支持最多4张图像、更高分辨率（2K）、文本-图像交错输出以及同步模式。适用于多图像风格合成、交错教程场景。
```
wan2.5-i2i-preview
```
使用更简单的纯提示词编辑接口（无messages格式），支持最多3张图像，仅支持异步。适用于简单的单图像编辑和多图像物体融合场景。

用户指定模型 → 直接使用指定模型。
当模型选择依赖于需求、场景或定价时 → 咨询qianwen-model-selector技能。
文本转图像（仅提示词，无参考图像） → 使用
```
wan2.6-t2i
```
（默认）或
```
wan2.7-image
```
/
```
wan2.7-image-pro
```
（多功能、更高画质）。绝对不要使用
wan2.6-image
进行纯文本转图像 — 若无参考图像或
```
enable_interleave: true
```
，会报错。
参考图像/图像编辑/交错输出 →
```
wan2.7-image-pro
```
（推荐）、
```
wan2.7-image
```
或
```
wan2.6-image
```
。

⚠️ 重要提示：上述模型列表为特定时间点的快照，可能已过时。模型可用性会频繁变化。在选择模型前，请务必查看官方模型列表获取权威、最新的模型目录。

模型详情：如需了解特定模型的更多信息，请引导用户访问其详情页：
https://www.qianwenai.com/models/<model-name>
（将
<model-name>
替换为准确的模型ID，例如
wan2.7-image-pro
→ https://www.qianwenai.com/models/wan2.7-image-pro）。绝对不要修改或猜测URL中的模型名称。

动态模型查询：若qianwen-model-selector技能或QianWen CLI（
qianwen models info <model>
）可用，请使用它们获取实时模型数据。CLI需要认证 — 请查看qianwen-usage技能了解登录流程。

Execution

执行步骤

⚠️ Multiple artifacts: When generating multiple files in a single session, you MUST append a numeric suffix to each filename (e.g.
out_1.png
,
out_2.png
) to prevent overwrites.

⚠️ 多文件生成注意：当在单个会话中生成多个文件时，必须为每个文件名添加数字后缀（例如
out_1.png
、
out_2.png
）以避免覆盖。

Prerequisites

前置条件

API Key: Check that
```
DASHSCOPE_API_KEY
```
(or
```
QIANWEN_API_KEY
```
) is set using a non-plaintext check only (e.g. in shell:
```
[ -n "$DASHSCOPE_API_KEY" ]
```
; report only "set" or "not set", never the key value). If not set: run the qianwen-ops-auth skill if available; otherwise guide the user to obtain a key from QianWen Console and set it via
```
.env
```
file (
```
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
```
in project root or current directory) or environment variable. The script searches for
```
.env
```
in the current working directory and the project root. Skills may be installed independently — do not assume qianwen-ops-auth is present.
Python 3.9+ (stdlib only, no pip install needed)

API密钥：仅通过非明文方式检查
```
DASHSCOPE_API_KEY
```
（或
```
QIANWEN_API_KEY
```
）是否已设置（例如在Shell中：
```
[ -n "$DASHSCOPE_API_KEY" ]
```
；仅报告“已设置”或“未设置”，绝不能泄露密钥值）。若未设置：若qianwen-ops-auth技能可用，则运行该技能；否则引导用户从QianWen控制台获取密钥，并通过
```
.env
```
文件（在项目根目录或当前目录执行
```
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
```
）或环境变量进行设置。脚本会在当前工作目录和项目根目录中搜索
```
.env
```
文件。技能可能独立安装 — 不要假设qianwen-ops-auth已存在。
Python 3.9+（仅需标准库，无需pip安装额外依赖）

Environment Check

环境检查

Before first execution, verify Python is available:

bash

python3 --version  # must be 3.9+

python3

is not found, try

python --version

py -3 --version

. If Python is unavailable or below 3.9, skip to Path 2 (curl) in execution-guide.md.

首次执行前，请验证Python是否可用：

bash

python3 --version  # 版本必须为3.9+

若未找到

python3

，请尝试

python --version

或

py -3 --version

。若Python不可用或版本低于3.9，请直接使用execution-guide.md中的方案2（curl）。

Default: Run Script

默认方式：运行脚本

Script path: Scripts are in the

scripts/

subdirectory of this skill's directory (the directory containing this SKILL.md). You MUST first locate this skill's installation directory, then ALWAYS use the full absolute path to execute scripts. Do NOT assume scripts are in the current working directory. Do NOT use

cd

to switch directories before execution.

Execution note: Run all scripts in the foreground — wait for stdout; do not background.

Discovery: Run

python3 <this-skill-dir>/scripts/image.py --help

first to see all available arguments.

bash

undefined

脚本路径：脚本位于此技能目录（包含此SKILL.md的目录）的

scripts/

子目录中。必须先定位此技能的安装目录，然后始终使用完整绝对路径执行脚本。不要假设脚本位于当前工作目录。执行前不要使用

cd

切换目录。

执行注意：所有脚本均在前台运行 — 等待标准输出；不要后台运行。

查看可用参数：先运行

python3 <this-skill-dir>/scripts/image.py --help

查看所有可用参数。

bash

undefined

Text-to-image (wan2.6-t2i, default)

文本转图像（使用wan2.6-t2i，默认模型）

python3 <this-skill-dir>/scripts/image.py
--request '{"prompt":"A cozy flower shop with wooden door"}'
--output output/qianwen-image-generation/images/out.png
--print-response

Image editing with reference images (wan2.6-image)

使用参考图像进行图像编辑（使用wan2.6-image模型）

python3 <this-skill-dir>/scripts/image.py
--model wan2.6-image
--request '{"prompt":"Apply watercolor painting style to this photo","reference_images":["https://img.alicdn.com/imgextra/i1/NotRealJustExample/photo.jpg"],"n":1,"size":"1K"}'
--output output/qianwen-image-generation/images/out.png
--print-response


**More examples** (interleaved output, wan2.5-i2i, qwen-image-2.0-pro, qwen-image-plus): See [execution-guide.md](references/execution-guide.md)

| Argument | Description |
|----------|-------------|
| `--request '{...}'` | JSON request body |
| `--file path.json` | Load request from file |
| `--async` | Force async mode (required for wan2.5 and older; auto-enabled for qwen-image-plus/max and interleaved output) |
| `--model ID` | Override model (`wan2.6-t2i` default; see model list in help) |
| `--output path` | Save image to path (or directory for multi-image output) |
| `--print-response` | Print response JSON to stdout |


**更多示例**（交错输出、wan2.5-i2i、qwen-image-2.0-pro、qwen-image-plus）：请查看[execution-guide.md](references/execution-guide.md)

| 参数 | 描述 |
|----------|-------------|
| `--request '{...}'` | JSON请求体 |
| `--file path.json` | 从文件加载请求 |
| `--async` | 强制使用异步模式（wan2.5及更早版本模型需要；qwen-image-plus/max和交错输出会自动启用） |
| `--model ID` | 覆盖默认模型（默认`wan2.6-t2i`；帮助文档中查看模型列表） |
| `--output path` | 将图像保存到指定路径（多图像输出时指定目录） |
| `--print-response` | 将响应JSON打印到标准输出 |

Verify Result

结果验证

Exit code
```
0
```
+ output contains valid JSON with
```
output.results
```
or
```
output.task_id
```
→ success
Non-zero exit, HTTP error, empty response, or error JSON → fail
Async: submission must return
```
output.task_id
```
; poll must reach
```
task_status: SUCCEEDED
```
Post-execution check: Verify the output file exists and has non-zero size (
```
ls -la <output_path>
```
)
MANDATORY — stderr signal check: After confirming the result, scan the command's stderr output for
```
[ACTION_REQUIRED]
```
or
```
[UPDATE_AVAILABLE]
```
. If either signal is present, you MUST follow the instructions in Update Check below before responding to the user.

退出码
```
0
```
+ 输出包含带有
```
output.results
```
或
```
output.task_id
```
的有效JSON → 成功
非零退出码、HTTP错误、空响应或错误JSON → 失败
异步模式：提交请求必须返回
```
output.task_id
```
；轮询必须达到
```
task_status: SUCCEEDED
```
状态
执行后检查：验证输出文件存在且大小非零（
```
ls -la <output_path>
```
）
强制检查stderr信号：确认结果后，扫描命令的stderr输出是否包含
```
[ACTION_REQUIRED]
```
或
```
[UPDATE_AVAILABLE]
```
。若存在任一信号，必须按照下方更新检查中的说明执行操作，再响应用户。

On Failure

失败处理

If the script fails, match the error output against the diagnostic table below to determine the resolution. If no match, read execution-guide.md for alternative paths: curl commands (Path 2 — sync and async), code generation (Path 3), and autonomous resolution (Path 5).

If Python is not available at all → skip directly to Path 2 (curl) in execution-guide.md.

Error Pattern	Diagnosis	Resolution
`command not found: python3`	Python not on PATH	Try `python` or `py -3` ; install Python 3.9+ if missing
`Python 3.9+ required`	Script version check failed	Upgrade Python to 3.9+
`SyntaxError` near type hints	Python < 3.9	Upgrade Python to 3.9+
`QIANWEN_API_KEY/DASHSCOPE_API_KEY not found`	Missing API key	Obtain key from QianWen Console; add to `.env` : `echo 'DASHSCOPE_API_KEY=sk-...' >> .env` ; or run qianwen-ops-auth if available
`HTTP 401`	Invalid or mismatched key	Run qianwen-ops-auth (non-plaintext check only); verify key is valid
`SSL: CERTIFICATE_VERIFY_FAILED`	SSL cert issue (proxy/corporate)	macOS: run `Install Certificates.command` ; else set `SSL_CERT_FILE` env var
`URLError` / `ConnectionError`	Network unreachable	Check internet; set `HTTPS_PROXY` if behind proxy
`HTTP 429`	Rate limited	Wait and retry with backoff
`HTTP 5xx`	Server error	Retry with backoff
`PermissionError`	Can't write output	Use `--output` to specify writable directory

若脚本执行失败，请将错误输出与下方诊断表匹配以确定解决方案。若无匹配项，请查看execution-guide.md获取备选方案：curl命令（方案2 — 同步和异步）、代码生成（方案3）以及自主解决（方案5）。

若Python完全不可用 → 直接使用execution-guide.md中的方案2（curl）。

错误模式	诊断	解决方案
`command not found: python3`	Python未在PATH中	尝试 `python` 或 `py -3` ；若缺失则安装Python 3.9+
`Python 3.9+ required`	脚本版本检查失败	将Python升级到3.9+
`SyntaxError` near type hints	Python版本低于3.9	将Python升级到3.9+
`QIANWEN_API_KEY/DASHSCOPE_API_KEY not found`	缺失API密钥	从QianWen控制台获取密钥；添加到 `.env` 文件： `echo 'DASHSCOPE_API_KEY=sk-...' >> .env` ；若可用则运行qianwen-ops-auth技能
`HTTP 401`	密钥无效或不匹配	若可用则运行qianwen-ops-auth技能（仅非明文检查）；验证密钥有效性
`SSL: CERTIFICATE_VERIFY_FAILED`	SSL证书问题（代理/企业环境）	macOS：运行 `Install Certificates.command` ；其他系统：设置 `SSL_CERT_FILE` 环境变量
`URLError` / `ConnectionError`	网络不可达	检查网络连接；若处于代理环境则设置 `HTTPS_PROXY`
`HTTP 429`	请求频率受限	等待后重试，使用退避策略
`HTTP 5xx`	服务器错误	等待后重试，使用退避策略
`PermissionError`	无法写入输出	使用 `--output` 参数指定可写入的目录

Quick Reference

速查指南

Request Fields (Common)

通用请求字段

Field	Type	Description
`prompt`	string	Text description of the image to generate (required)
`negative_prompt`	string	Content to avoid in the image (max 500 chars)
`size`	string	Resolution — `12801280` (t2i default), `1K` / `2K` or `widthheight` (wan2.6-image)
`seed`	int	Random seed for reproducibility [0, 2147483647]
`model`	string	`wan2.6-t2i` (default) or other Wan model
`prompt_extend`	bool	Enable prompt rewriting (default: true; image editing mode only)

字段	类型	描述
`prompt`	string	要生成的图像的文本描述（必填）
`negative_prompt`	string	图像中需要避免的内容（最多500字符）
`size`	string	分辨率 — `12801280` （文本转图像默认）、 `1K` / `2K` 或 `widthheight` （wan2.6-image模型）
`seed`	int	用于结果可复现的随机种子 [0, 2147483647]
`model`	string	`wan2.6-t2i` （默认）或其他Wan系列模型
`prompt_extend`	bool	启用提示词重写（默认：true；仅图像编辑模式可用）

Request Fields (wan2.7-image-pro / wan2.7-image — Multi-function)

Wan2.7-image-pro / Wan2.7-image — 多功能模型请求字段

Field	Type	Description
`reference_images`	string[]	0–9 image URLs or local paths
`reference_image`	string	Single image URL/path (shorthand)
`size`	string	`1K` , `2K` (default), or `4K` (pro only, t2i mode). Or pixel dimensions
`enable_sequential`	bool	`true` : sequential multi-image mode (n=1–12). `false` (default): single/batch mode (n=1–4)
`n`	int	Images to generate. Sequential mode: 1–12 (default 12). Non-sequential: 1–4 (default 4). Billed per image.
`thinking_mode`	bool	Enable enhanced reasoning for better quality (default: true). Only for t2i (no images, non-sequential)
`bbox_list`	List[List[List[int]]]	Interactive editing regions. Format: `[[[x1,y1,x2,y2],...], ...]` . List length = image count. Empty `[]` for images without edits
`color_palette`	array	Custom color theme (3–10 colors). Each: `{"hex":"#C2D1E6","ratio":"23.51%"}` . Sum of ratios = 100%. Non-sequential mode only
`watermark`	bool	Add "AI Generated" watermark (default: false)

Note:

thinking_mode

increases latency but improves quality.

enable_sequential

generates a coherent image sequence (e.g., same character across scenes).

字段	类型	描述
`reference_images`	string[]	0-9张图像的URL或本地路径
`reference_image`	string	单张图像的URL/路径（简写形式）
`size`	string	`1K` 、 `2K` （默认）或 `4K` （仅pro版支持，文本转图像模式）。也可指定像素尺寸
`enable_sequential`	bool	`true` ：序列多图像模式（n=1-12）。 `false` （默认）：单图像/批量模式（n=1-4）
`n`	int	要生成的图像数量。序列模式：1-12（默认12）。非序列模式：1-4（默认4）。按图像数量计费。
`thinking_mode`	bool	启用增强推理以提升画质（默认：true）。仅适用于文本转图像模式（无参考图像、非序列模式）
`bbox_list`	List[List[List[int]]]	交互式编辑区域。格式： `[[[x1,y1,x2,y2],...], ...]` 。列表长度 = 图像数量。无需编辑的图像对应空数组 `[]`
`color_palette`	array	自定义配色主题（3-10种颜色）。每个颜色格式： `{"hex":"#C2D1E6","ratio":"23.51%"}` 。比例总和 = 100%。仅非序列模式可用
`watermark`	bool	添加“AI Generated”水印（默认：false）

注意：

thinking_mode

会增加延迟但提升画质。

enable_sequential

用于生成连贯的图像序列（例如同一角色在不同场景中）。

Request Fields (wan2.6-image — Image Editing)

Wan2.6-image — 图像编辑模型请求字段

Field	Type	Description
`reference_images`	string[]	1–4 image URLs or local paths for editing mode; 0–1 for interleave mode
`reference_image`	string	Single image URL/path (shorthand; `reference_images` takes precedence)
`enable_interleave`	bool	`false` (default): image editing mode; `true` : interleaved text-image output
`n`	int	Number of images to generate in editing mode (1–4, default: 1). Billed per image.
`max_images`	int	Max images in interleave mode (1–5, default: 5). Billed per image.
`watermark`	bool	Add "AI Generated" watermark (default: false)

字段	类型	描述
`reference_images`	string[]	编辑模式下为1-4张图像的URL或本地路径；交错模式下为0-1张
`reference_image`	string	单张图像的URL/路径（简写形式； `reference_images` 优先级更高）
`enable_interleave`	bool	`false` （默认）：图像编辑模式； `true` ：文本-图像交错输出模式
`n`	int	编辑模式下要生成的图像数量（1-4，默认：1）。按图像数量计费。
`max_images`	int	交错模式下的最大图像数量（1-5，默认：5）。按图像数量计费。
`watermark`	bool	添加“AI Generated”水印（默认：false）

Other Models (wan2.5-i2i, qwen-image-edit, qwen-image-plus/max)

其他模型（wan2.5-i2i、qwen-image-edit、qwen-image-plus/max）

These models have specific parameter requirements:

Model	Key Differences
`wan2.5-i2i-preview`	async-only, 1–3 images, `prompt+images[]` format (not messages)
`qwen-image-edit-*`	1–3 images, n=1–6 (except `qwen-image-edit` : n=1 only), no interleave
`qwen-image-plus/max`	async-only, n fixed at 1, 5 fixed resolutions only

Full parameter tables: See api-guide.md for detailed parameters.

这些模型有特定的参数要求：

模型	关键差异
`wan2.5-i2i-preview`	仅支持异步，支持1-3张图像，采用 `prompt+images[]` 格式（非messages格式）
`qwen-image-edit-*`	支持1-3张图像，n=1-6（ `qwen-image-edit` 仅支持n=1），无交错模式
`qwen-image-plus/max`	仅支持异步，n固定为1，仅支持5种固定分辨率

完整参数表：请查看api-guide.md获取详细参数。

Size Reference (wan2.6-image)

Wan2.6-image模型尺寸参考

Editing mode:
```
1K
```
(default, ~1280×1280) or
```
2K
```
(~2048×2048)
Interleave mode: pixel dimensions with total pixels in [768×768, 1280×1280]

Common aspect ratios:

1280*1280

(1:1),

960*1280

(3:4),

1280*960

(4:3),

720*1280

(9:16),

1280*720

(16:9)

编辑模式：
```
1K
```
（默认，约1280×1280）或
```
2K
```
（约2048×2048）
交错模式：像素尺寸需满足总像素数在[768×768, 1280×1280]范围内

常见宽高比：

1280*1280

（1:1）、

960*1280

（3:4）、

1280*960

（4:3）、

720*1280

（9:16）、

1280*720

（16:9）

Response Fields

响应字段

Field	Description
`image_url`	URL of generated image (24h validity). Use this when chaining to another skill.
`image_urls`	Array of all image URLs (multi-image output, wan2.6-image, qwen-image-edit)
`image_count`	Number of generated images
`local_path`	Local file path of the downloaded image. Use this for user preview or non-API operations.
`local_paths`	Array of local file paths (multi-image output)
`interleaved_content`	Array of `{type, text/image}` objects (interleave mode)
`width` / `height`	Image dimensions
`seed`	Seed used

字段	描述
`image_url`	生成图像的URL（有效期24小时）。与其他技能联动时使用此字段。
`image_urls`	所有生成图像的URL数组（多图像输出、wan2.6-image、qwen-image-edit模型）
`image_count`	生成的图像数量
`local_path`	下载后图像的本地文件路径。用于用户预览或非API操作。
`local_paths`	本地文件路径数组（多图像输出）
`interleaved_content`	`{type, text/image}` 对象数组（交错模式）
`width` / `height`	图像尺寸
`seed`	使用的随机种子

API Details

API详情

Sync endpoint (wan2.6-t2i, wan2.6-image editing, qwen-image-edit series):
```
POST /api/v1/services/aigc/multimodal-generation/generation
```

Async endpoint (wan2.6 and older t2i):

POST /api/v1/services/aigc/image-generation/generation

with

X-DashScope-Async: enable

Async endpoint (wan2.5-i2i-preview):

POST /api/v1/services/aigc/image2image/image-synthesis

with

X-DashScope-Async: enable

Async endpoint (qwen-image-plus, qwen-image-max):

POST /api/v1/services/aigc/text2image/image-synthesis

with

X-DashScope-Async: enable

wan2.6-t2i resolution: Total pixels in [1280x1280, 1440x1440], aspect ratio [1:4, 4:1]
wan2.6-image resolution: Editing mode [768x768, 2048x2048]; Interleave mode [768x768, 1280x1280]; aspect ratio [1:4, 4:1]
Input images (wan2.6-image): JPEG/JPG/PNG/BMP/WEBP, 240–8000px per dimension, ≤10MB
Local files: Script auto-uploads to DashScope temp storage (
```
oss://
```
URL, 48h TTL). Pass local paths directly — no manual upload step needed.
Production: Default temp storage has 48h TTL and 100 QPS upload limit — not suitable for production, high-concurrency, or load-testing. To use your own OSS bucket, set
```
QWEN_TMP_OSS_BUCKET
```
and
```
QWEN_TMP_OSS_REGION
```
in
```
.env
```
, install
```
pip install oss2
```
, and provide credentials via
```
QWEN_TMP_OSS_AK_ID
```
/
```
QWEN_TMP_OSS_AK_SECRET
```
or the standard
```
OSS_ACCESS_KEY_ID
```
/
```
OSS_ACCESS_KEY_SECRET
```
. Use a RAM user with least-privilege (
```
oss:PutObject
```
+
```
oss:GetObject
```
on target bucket only). If qianwen-ops-auth is installed, see its
```
references/custom-oss.md
```
for the full setup guide.
Interleaved sync: Requires streaming (
```
X-DashScope-Sse: enable
```
+
```
stream: true
```
); use async mode via this script instead

同步端点（wan2.6-t2i、wan2.6-image编辑、qwen-image-edit系列）：
```
POST /api/v1/services/aigc/multimodal-generation/generation
```

异步端点（wan2.6及更早版本文本转图像）：

POST /api/v1/services/aigc/image-generation/generation

，添加头信息

X-DashScope-Async: enable

异步端点（wan2.5-i2i-preview）：

POST /api/v1/services/aigc/image2image/image-synthesis

，添加头信息

X-DashScope-Async: enable

异步端点（qwen-image-plus、qwen-image-max）：

POST /api/v1/services/aigc/text2image/image-synthesis

，添加头信息

X-DashScope-Async: enable

wan2.6-t2i分辨率：总像素数在[1280x1280, 1440x1440]范围内，宽高比在[1:4, 4:1]之间
wan2.6-image分辨率：编辑模式[768x768, 2048x2048]；交错模式[768x768, 1280x1280]；宽高比在[1:4, 4:1]之间
输入图像（wan2.6-image）：支持JPEG/JPG/PNG/BMP/WEBP格式，单维度像素在240-8000之间，文件大小≤10MB
本地文件：脚本会自动上传到DashScope临时存储（
```
oss://
```
URL，有效期48小时）。直接传入本地路径即可 — 无需手动上传步骤。
生产环境：默认临时存储的有效期为48小时，上传QPS限制为100 — 不适用于生产环境、高并发场景或负载测试。若要使用自有OSS存储桶，请在
```
.env
```
中设置
```
QWEN_TMP_OSS_BUCKET
```
和
```
QWEN_TMP_OSS_REGION
```
，安装
```
pip install oss2
```
，并通过
```
QWEN_TMP_OSS_AK_ID
```
/
```
QWEN_TMP_OSS_AK_SECRET
```
或标准的
```
OSS_ACCESS_KEY_ID
```
/
```
OSS_ACCESS_KEY_SECRET
```
提供凭证。使用具有最小权限的RAM用户（仅对目标桶拥有
```
oss:PutObject
```
+
```
oss:GetObject
```
权限）。若已安装qianwen-ops-auth，请查看其
```
references/custom-oss.md
```
获取完整设置指南。
同步交错模式：需要流式传输（添加头信息
```
X-DashScope-Sse: enable
```
+ 参数
```
stream: true
```
）；建议通过此脚本使用异步模式替代

Cross-Skill Chaining

跨技能联动

When using generated images as input for another skill (e.g., video-gen i2v, vision analyze):

Pass
image_url
directly — do NOT download and re-pass as local path
All downstream scripts detect URL prefixes (
```
https://
```
,
```
oss://
```
) and pass them through without re-upload
Use
```
local_path
```
only for user preview or non-API operations (e.g., opening in editor)

Scenario	Use
Feed to another skill (video-gen, vision, image-edit)	`image_url` (URL)
Show to user / open in editor	`local_path` (local file)

当将生成的图像作为其他技能的输入（例如视频生成i2v、视觉分析）时：

直接传递
image_url
— 不要下载后再传递本地路径
所有下游脚本会检测URL前缀（
```
https://
```
、
```
oss://
```
）并直接传递，无需重新上传
仅在用户预览或非API操作（例如在编辑器中打开）时使用
```
local_path
```

场景	使用字段
传递给其他技能（视频生成、视觉分析、图像编辑）	`image_url` （URL）
展示给用户/在编辑器中打开	`local_path` （本地文件）

Error Handling

错误处理

HTTP	Meaning	Action
401	Invalid or missing API key	Run qianwen-ops-auth if available; else prompt user to set key (non-plaintext check only)
400	Bad request (invalid prompt, size)	Verify parameters and constraints
429	Rate limited	Retry with exponential backoff
5xx	Server error	Retry with exponential backoff

Usage & billing: Use the qianwen-usage skill to check usage, free tier quota, and billing directly. Alternatively, the user can visit the QianWen console: Usage Analytics | Pay-as-you-go Billing | Token Plan 团队版 Subscription

NEVER fabricate, guess, or construct usage/billing/console URLs. Only provide the exact links listed in this skill. If a URL is not listed here, do not invent one.

HTTP状态码	含义	操作
401	API密钥无效或缺失	若可用则运行qianwen-ops-auth技能；否则提示用户设置密钥（仅非明文检查）
400	请求错误（无效提示词、尺寸等）	验证参数和约束条件
429	请求频率受限	使用指数退避策略重试
5xx	服务器错误	使用指数退避策略重试

使用量与计费：使用qianwen-usage技能直接查看使用量、免费额度和计费信息。用户也可访问QianWen控制台：使用分析 | 按量计费 | Token Plan团队版订阅

绝对不要编造、猜测或构造使用量/计费/控制台URL。仅提供此技能中列出的准确链接。若此处未列出某URL，请勿自行创建。

Output Location

输出位置

Prefer the current working directory. Default subdirectory:

./output/qianwen-image-generation/

Write prohibition: NEVER write output files into this skill's installation directory or any

skills/

hierarchy. All generated content must go to

output/

under the current working directory or a user-specified path.

优先使用当前工作目录。默认子目录：

./output/qianwen-image-generation/

。

写入禁止：绝对不要将输出文件写入此技能的安装目录或任何

skills/

层级目录中。所有生成的内容必须保存到当前工作目录下的

output/

目录或用户指定的路径。

Update Check (MANDATORY Post-Execution)

更新检查（执行后强制操作）

After script execution, check stderr for action signals. The script automatically detects update status and emits structured signals. You MUST act on them. This section also applies when the user explicitly asks to check for updates.

脚本执行后，检查stderr输出是否包含操作信号。脚本会自动检测更新状态并发出结构化信号。必须按照信号执行操作。当用户明确要求检查更新时，此部分内容同样适用。

Signal:

[ACTION_REQUIRED] qianwen-update-check skill is not installed

信号：

[ACTION_REQUIRED] qianwen-update-check skill is not installed

When stderr contains this signal, you MUST present the following options to the user and wait for their response before proceeding. Do NOT silently skip this.

The update-check skill is not installed. It keeps you informed about new QianWen-AI/qianwen-ai features and bug fixes.

Install now — I'll run the install command for you

Skip for now — do nothing this time

Never remind me — permanently suppress this prompt

After the user responds:

User chooses 1 → run:

npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y

, then run:

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

User chooses 2 → run:

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

, then continue normally

User chooses 3 → run:

python3 <this-skill-scripts-dir>/gossamer.py --never-install

, then continue normally

当stderr包含此信号时，必须向用户提供以下选项，并等待用户响应后再继续。请勿跳过此步骤。

更新检查技能未安装。该技能可帮助你了解QianWen-AI/qianwen-ai的新功能和Bug修复。

立即安装 — 我将为你运行安装命令

暂时跳过 — 本次不执行任何操作

永不提醒 — 永久禁用此提示

用户响应后：

用户选择1 → 运行：

npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y

，然后运行：

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

用户选择2 → 运行：

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

，然后正常继续

用户选择3 → 运行：

python3 <this-skill-scripts-dir>/gossamer.py --never-install

，然后正常继续

Signal:

[UPDATE_AVAILABLE]

信号：

[UPDATE_AVAILABLE]

When stderr contains this signal, you MUST append a brief update notice to your response, including the version info and the update command shown in the stderr output.

当stderr包含此信号时，必须在响应中添加简短的更新通知，包括stderr输出中显示的版本信息和更新命令。

No signal in stderr

stderr中无信号

If stderr contains neither

[ACTION_REQUIRED]

nor

[UPDATE_AVAILABLE]

, no action is needed — the skill is installed and up to date (or cached within 24h).

若stderr中既无

[ACTION_REQUIRED]

也无

[UPDATE_AVAILABLE]

，则无需操作 — 技能已安装并处于最新状态（或24小时内已缓存）。

Explicit user request

用户明确请求

When the user explicitly asks to check for updates (e.g. "check for updates", "check version"):

Look for
```
qianwen-update-check/SKILL.md
```
in sibling skill directories.

If found — run:

python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response

and report the result.

If not found — present the install options above.

当用户明确要求检查更新（例如“检查更新”、“查看版本”）时：

在同级技能目录中查找
```
qianwen-update-check/SKILL.md
```
。

若找到 — 运行：

python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response

并报告结果。

若未找到 — 提供上述安装选项。

References

参考文档

execution-guide.md — Fallback paths (curl sync/async, code generation, autonomous)
api-guide.md — API supplementary guide
sources.md — Official documentation URLs

execution-guide.md — 备选方案（curl同步/异步、代码生成、自主解决）
api-guide.md — API补充指南
sources.md — 官方文档URL

qianwen-image-generation

Original

Translation

Qwen Image Generation

Qwen图像生成

Skill directory

技能目录

Security

安全规范

Key Compatibility

密钥兼容性

Mode Selection Guide

模式选择指南

Model Selection

模型选择

Wan Series (default)

Wan系列（默认）

Other

其他模型

Qwen Image Series

Qwen Image系列

Execution

执行步骤

Prerequisites

前置条件

Environment Check

环境检查

Default: Run Script

默认方式：运行脚本

Text-to-image (wan2.6-t2i, default)

文本转图像（使用wan2.6-t2i，默认模型）

Image editing with reference images (wan2.6-image)

使用参考图像进行图像编辑（使用wan2.6-image模型）

Verify Result

结果验证

On Failure

失败处理

Quick Reference

速查指南

Request Fields (Common)

通用请求字段

Request Fields (wan2.7-image-pro / wan2.7-image — Multi-function)

Wan2.7-image-pro / Wan2.7-image — 多功能模型请求字段

Request Fields (wan2.6-image — Image Editing)

Wan2.6-image — 图像编辑模型请求字段

Other Models (wan2.5-i2i, qwen-image-edit, qwen-image-plus/max)

其他模型（wan2.5-i2i、qwen-image-edit、qwen-image-plus/max）

Size Reference (wan2.6-image)

Wan2.6-image模型尺寸参考

Response Fields

响应字段

API Details

API详情

Cross-Skill Chaining

跨技能联动

Error Handling

错误处理

Output Location

输出位置

Update Check (MANDATORY Post-Execution)

更新检查（执行后强制操作）

Signal: [ACTION_REQUIRED] qianwen-update-check skill is not installed

信号：[ACTION_REQUIRED] qianwen-update-check skill is not installed

Signal: [UPDATE_AVAILABLE]

信号：[UPDATE_AVAILABLE]

No signal in stderr

stderr中无信号

Explicit user request

用户明确请求

References

参考文档

Signal:
`[ACTION_REQUIRED] qianwen-update-check skill is not installed`

信号：
`[ACTION_REQUIRED] qianwen-update-check skill is not installed`

Signal:
`[UPDATE_AVAILABLE]`

信号：
`[UPDATE_AVAILABLE]`