Back to Details

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.
LocationPurpose
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 WantModeModel
Generate image from text onlyt2i
wan2.6-t2i
(default)
Edit image / apply style transfer based on 1–4 reference imagesimage-edit
wan2.6-image
Subject consistency: generate new images maintaining subject from referencesimage-edit
wan2.6-image
Multi-image composition: combine style from one image, background from anotherimage-edit
wan2.6-image
Single-image editing preserving subject consistencyi2i
wan2.5-i2i-preview
Multi-image fusion: place object from one image into another scenei2i
wan2.5-i2i-preview
Interleaved text-image output (e.g., tutorials, step-by-step guides)interleave
wan2.6-image
Fast text-to-image draftst2i
wan2.2-t2i-flash
Edit text within images, precise element manipulationimage-edit
qwen-image-2.0-pro
Multi-image fusion with realistic texturesimage-edit
qwen-image-2.0-pro
Posters / complex Chinese+English text renderingt2i
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系列（默认）

ModelUse Case
wan2.6-t2iRecommended for text-to-image — sync + async, best quality
wan2.6-imageImage 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-previewImage editing — single-image editing with subject consistency, multi-image fusion (up to 3 images), async-only
wan2.5-t2i-previewPreview — free size within constraints
wan2.2-t2i-flashFast — lower latency
wan2.2-t2i-plusProfessional — 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系列

ModelUse Case
qwen-image-2.0-proFused generation + editing — text rendering, realistic textures, multi-image (1–3 input, 1–6 output)
qwen-image-2.0Accelerated generation + editing
qwen-image-edit-maxImage editing — 1–6 output images
qwen-image-edit-plusImage editing — 1–6 output images
qwen-image-editImage editing — 1 output image only
qwen-image-plusText-to-image — fixed resolutions only (async)
qwen-image-maxText-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) → 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
    .
  4. 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张图，仅支持异步。适用于简单的单图编辑和多图物体融合场景。
  1. 用户指定了模型 → 直接使用指定模型。
  2. 当模型选择取决于需求、场景或定价时 → 咨询qwencloud-model-selector技能。
  3. 纯文生图（仅prompt，无参考图） → 始终使用
    wan2.6-t2i
    （默认）    。绝对不要使用
    wan2.6-image
    做纯文生图     — 没有参考图或未设置
    enable_interleave: true
    时会报错。
  4. 有参考图/图像编辑/图文混排输出 → 优先选
    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+
If 
python3
is not found, try 
python --version
or 
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 PatternDiagnosisResolution
command not found: python3
Python not on PATHTry 
python
or 
py -3
; install Python 3.9+ if missing
Python 3.9+ required
Script version check failedUpgrade Python to 3.9+
SyntaxError
near type hints		Python < 3.9Upgrade Python to 3.9+
QWEN_API_KEY/DASHSCOPE_API_KEY not found
Missing API keyObtain 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 keyRun 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 unreachableCheck internet; set 
HTTPS_PROXY
if behind proxy
HTTP 429
Rate limitedWait and retry with backoff
HTTP 5xx
Server errorRetry with backoff
PermissionError
Can't write outputUse 
--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)

通用请求字段

FieldTypeDescription
prompt
stringText description of the image to generate (required)
negative_prompt
stringContent to avoid in the image (max 500 chars)
size
stringResolution — 
1280*1280
(t2i default), 
1K
/
2K
or 
width*height
(wan2.6-image)
seed
intRandom seed for reproducibility [0, 2147483647]
model
string
wan2.6-t2i
(default) or other Wan model
prompt_extend
boolEnable prompt rewriting (default: true; image editing mode only)
字段类型说明
prompt
string待生成图像的文本描述（必填）
negative_prompt
string图像中要避免的内容（最多500字符）
size
string分辨率 — 
1280*1280
（文生图默认）、
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 — 图像编辑请求字段

FieldTypeDescription
reference_images
string[]1–4 image URLs or local paths for editing mode; 0–1 for interleave mode
reference_image
stringSingle image URL/path (shorthand; 
reference_images
takes precedence)
enable_interleave
bool
false
(default): image editing mode; 
true
: interleaved text-image output
n
intNumber of images to generate in editing mode (1–4, default: 1). Billed per image.
max_images
intMax images in interleave mode (1–5, default: 5). Billed per image.
watermark
boolAdd "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:
ModelKey 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

响应字段

FieldDescription
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)
ScenarioUse
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

错误处理

HTTPMeaningAction
401Invalid or missing API keyRun qwencloud-ops-auth if available; else prompt user to set key (non-plaintext check only)
400Bad request (invalid prompt, size)Verify parameters and constraints
429Rate limitedRetry with exponential backoff
5xxServer errorRetry with exponential backoff
HTTP状态码含义处理方式
401API密钥无效或缺失如果有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.
  1. Install now — I'll run the install command for you
  2. Skip for now — do nothing this time
  3. 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. 立即安装 — 我会为你运行安装命令
  2. 暂时跳过 — 本次不做任何操作
  3. 不再提醒 — 永久屏蔽该提示
用户响应后：
  • 用户选择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"):
  1. Look for 
    qwencloud-update-check/SKILL.md
    in sibling skill directories.
  2. If found — run: 
    python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response
    and report the result.
  3. If not found — present the install options above.
当用户明确要求检查更新时（例如“检查更新”、“查看版本”）：
  1. 在同级技能目录中查找
    qwencloud-update-check/SKILL.md
    。
  2. 如果存在 — 运行：
    python3 <qwencloud-update-check目录>/scripts/check_update.py --print-response
    并报告结果。
  3. 如果不存在 — 展示上述安装选项。

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 — 官方文档链接