qwencloud-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 qwencloud/qwencloud-ai.

利用Wan和Qwen Image模型生成和编辑图像，支持文生图、参考图编辑（风格迁移、主体一致性、多图合成、文字渲染）以及图文混排输出。本技能属于 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

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

位置	用途
`scripts/image.py`	默认执行入口 — 同步/异步、上传、下载
`references/execution-guide.md`	备用方案：curl（同步/异步）、代码生成
`references/prompt-guide.md`	Prompt编写公式、风格关键词、negative_prompt、prompt_extend决策说明
`references/api-guide.md`	API补充说明
`references/sources.md`	官方文档链接
`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 QwenCloud 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

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

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.

脚本需要标准QwenCloud API密钥（

sk-...

格式）。编码计划密钥（

sk-sp-...

）无法使用 — 编码计划不提供图像生成模型权限，也不支持原生QwenCloud API。脚本启动时会检测

sk-sp-

格式的密钥并输出警告。如果安装了qwencloud-ops-auth，可以查看其

references/codingplan.md

了解完整详情。

Mode Selection Guide

模式选择指南

User Want	Mode	Model
Generate image from text only	t2i	`wan2.6-t2i` (default)
Edit image / apply style transfer based on 1–4 reference images	image-edit	`wan2.6-image`
Subject consistency: generate new images maintaining subject from references	image-edit	`wan2.6-image`
Multi-image composition: combine style from one image, background from another	image-edit	`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` （默认）
基于1-4张参考图编辑图像/应用风格迁移	image-edit	`wan2.6-image`
主体一致性：保留参考图主体特征生成新图像	image-edit	`wan2.6-image`
多图合成：结合一张图的风格和另一张图的背景	image-edit	`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.6-image	Image editing ONLY (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.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	专业版 — 稳定性更高

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 qwencloud-model-selector skill when model choice depends on requirement, scenario, or pricing.
Text-to-image (prompt only, no reference images) → always use
wan2.6-t2i
(default). 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.6-image
```
(preferred) or
```
wan2.5-i2i-preview
```
.

⚠️ 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.

模型	适用场景
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种固定分辨率：1664*928、1472*1104、1328*1328、1104*1472、928*1664。

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

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

用户指定了模型 → 直接使用指定模型。
当模型选择取决于需求、场景或定价时 → 咨询qwencloud-model-selector技能。
纯文生图（仅prompt，无参考图） → 始终使用
wan2.6-t2i
（默认）。绝对不要使用
wan2.6-image
做纯文生图 — 没有参考图或未设置
```
enable_interleave: true
```
时会报错。
有参考图/图像编辑/图文混排输出 → 优先选
```
wan2.6-image
```
，也可选择
```
wan2.5-i2i-preview
```
。

⚠️ 重要提示: 上述模型列表是当前时间点的快照，可能会过时。模型可用性会频繁更新。在选择模型前，请务必查看官方模型列表获取权威、最新的目录信息。

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
```
QWEN_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 qwencloud-ops-auth skill if available; otherwise guide the user to obtain a key from QwenCloud 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 qwencloud-ops-auth is present.
Python 3.9+ (stdlib only, no pip install needed)

API密钥: 仅通过非明文方式检查
```
DASHSCOPE_API_KEY
```
（或
```
QWEN_API_KEY
```
）是否已设置（例如Shell中使用
```
[ -n "$DASHSCOPE_API_KEY" ]
```
；仅报告“已设置”或“未设置”，绝不输出密钥值）。如果未设置：如果有qwencloud-ops-auth技能则运行该技能；否则指导用户从QwenCloud控制台获取密钥，并通过
```
.env
```
文件（在项目根目录或当前目录执行
```
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
```
）或环境变量设置。脚本会在当前工作目录和项目根目录下搜索
```
.env
```
文件。技能可能独立安装 — 不要假设qwencloud-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 <本技能目录>/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/qwencloud-image-generation/images/out.png
--print-response

python3 <本技能目录>/scripts/image.py
--request '{"prompt":"A cozy flower shop with wooden door"}'
--output output/qwencloud-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://example.com/photo.jpg"],"n":1,"size":"1K"}'
--output output/qwencloud-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 |

python3 <本技能目录>/scripts/image.py
--model wan2.6-image
--request '{"prompt":"Apply watercolor painting style to this photo","reference_images":["https://example.com/photo.jpg"],"n":1,"size":"1K"}'
--output output/qwencloud-image-generation/images/out.png
--print-response


**更多示例**（图文混排输出、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 <输出路径>
```
）
强制要求 — 错误输出信号检查: 确认结果后，扫描命令的标准错误输出是否有
```
[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+
`QWEN_API_KEY/DASHSCOPE_API_KEY not found`	Missing API key	Obtain key from QwenCloud Console; add to `.env` : `echo 'DASHSCOPE_API_KEY=sk-...' >> .env` ; or run qwencloud-ops-auth if available
`HTTP 401`	Invalid or mismatched key	Run qwencloud-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`	Python版本低于3.9	将Python升级到3.9+
`QWEN_API_KEY/DASHSCOPE_API_KEY not found`	缺失API密钥	从QwenCloud控制台获取密钥；添加到 `.env` ： `echo 'DASHSCOPE_API_KEY=sk-...' >> .env` ；如果有qwencloud-ops-auth则运行该技能
`HTTP 401`	密钥无效或不匹配	运行qwencloud-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` 或 `宽高` （wan2.6-image支持）
`seed`	int	用于复现结果的随机种子，范围[0, 2147483647]
`model`	string	`wan2.6-t2i` （默认）或其他Wan系列模型
`prompt_extend`	bool	启用prompt重写（默认：true；仅图像编辑模式可用）

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 alibabacloud-oss-v2
```
, 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 qwencloud-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-8000px，大小≤10MB
本地文件: 脚本自动上传到DashScope临时存储（
```
oss://
```
URL，有效期48小时）。直接传入本地路径即可 — 无需手动上传。
生产环境: 默认临时存储有48小时有效期和100 QPS上传限制 — 不适合生产、高并发或压测场景。要使用自己的OSS存储桶，在
```
.env
```
中设置
```
QWEN_TMP_OSS_BUCKET
```
和
```
QWEN_TMP_OSS_REGION
```
，安装
```
pip install alibabacloud-oss-v2
```
，并通过
```
QWEN_TMP_OSS_AK_ID
```
/
```
QWEN_TMP_OSS_AK_SECRET
```
或标准的
```
OSS_ACCESS_KEY_ID
```
/
```
OSS_ACCESS_KEY_SECRET
```
提供凭证。使用仅拥有目标桶最低权限（
```
oss:PutObject
```
+
```
oss:GetObject
```
）的RAM用户。如果安装了qwencloud-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 qwencloud-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

HTTP状态码	含义	处理方式
401	API密钥无效或缺失	如果有qwencloud-ops-auth则运行该技能；否则提示用户设置密钥（仅做非明文检查）
400	请求错误（prompt无效、尺寸无效）	验证参数和约束是否符合要求
429	触发速率限制	按指数退避策略重试
5xx	服务端错误	按指数退避策略重试

Output Location

输出位置

Prefer the current working directory. Default subdirectory:

./output/qwencloud-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/qwencloud-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.

脚本执行完成后，检查标准错误输出中的行动信号。脚本会自动检测更新状态并输出结构化信号，你必须按信号要求执行操作。当用户明确要求检查更新时，本章节也适用。

Signal:

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

信号：

[ACTION_REQUIRED] qwencloud-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 qwencloud/qwencloud-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 QwenCloud/qwencloud-ai --skill qwencloud-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

当标准错误输出包含该信号时，你必须向用户提供以下选项，并等待用户响应后再继续操作。不要静默跳过该步骤。

更新检查技能未安装，该技能会通知你qwencloud/qwencloud-ai的新功能和bug修复信息。

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

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

不再提醒 — 永久屏蔽该提示

用户响应后：

用户选择1 → 运行：

npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y

，然后运行：

python3 <本技能脚本目录>/gossamer.py --dismiss

用户选择2 → 运行：

python3 <本技能脚本目录>/gossamer.py --dismiss

，然后继续正常操作

用户选择3 → 运行：

python3 <本技能脚本目录>/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.

当标准错误输出包含该信号时，你必须在响应末尾附加简短的更新通知，包含标准错误输出中展示的版本信息和更新命令。

No signal in 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).

如果标准错误输出既没有

[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
```
qwencloud-update-check/SKILL.md
```
in sibling skill directories.

If found — run:

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

and report the result.

If not found — present the install options above.

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

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

如果存在 — 运行：

python3 <qwencloud-update-check目录>/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 — 官方文档链接

qwencloud-image-generation

Original

Translation

Qwen Image Generation

Qwen图像生成

Skill directory

技能目录

Security

安全规范

Key Compatibility

密钥兼容性说明

Mode Selection Guide

模式选择指南

Model Selection

模型选择

Wan Series (default)

Wan系列（默认）

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.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] qwencloud-update-check skill is not installed

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

Signal: [UPDATE_AVAILABLE]

信号：[UPDATE_AVAILABLE]

No signal in stderr

标准错误输出无信号

Explicit user request

用户明确请求更新检查

References

参考文档

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

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

Signal:
`[UPDATE_AVAILABLE]`

信号：
`[UPDATE_AVAILABLE]`