Back to Details

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.
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
提示词公式、风格关键词、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 WantModeModel
Generate image from text onlyt2i
wan2.6-t2i
(default), or 
wan2.7-image
/ 
wan2.7-image-pro
Open-source / lowest-cost text-to-imaget2i
z-image-turbo
(sync-only; no 
n
; no reference images)
Edit image / apply style transfer based on 1–4 reference imagesimage-edit
wan2.7-image-pro
/ 
wan2.7-image
/ 
wan2.6-image
Subject consistency: generate new images maintaining subject from referencesimage-edit
wan2.7-image-pro
/ 
wan2.7-image
/ 
wan2.6-image
Multi-image composition: combine style from one image, background from anotherimage-edit
wan2.7-image-pro
/ 
wan2.7-image
/ 
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
（默认），或
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系列（默认）

ModelUse Case
wan2.6-t2iRecommended for text-to-image — sync + async, best quality
wan2.7-image-proMulti-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-imageMulti-function (faster) — same as pro but max 2K, no 4K support
wan2.6-imageImage 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-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.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

其他模型

ModelUse Case
z-image-turboOpen-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系列

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 qianwen-model-selector skill when model choice depends on requirement, scenario, or pricing.
  3. Text-to-image (prompt only, no reference images) → use 
    wan2.6-t2i
    (default) or 
    wan2.7-image
    / 
    wan2.7-image-pro
    (multi-function, higher quality). NEVER use 
    wan2.6-image
    for pure text-to-image     — it will error without reference images or 
    enable_interleave: true
    .
  4. Reference images / image editing / interleaved output → 
    wan2.7-image-pro
    (recommended), 
    wan2.7-image
    , or 
    wan2.6-image
    .
⚠️ Important: The model list above is a point-in-time snapshot and may be outdated. Model availability changes frequently. Always check the official model list 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张图像，仅支持异步。适用于简单的单图像编辑和多图像物体融合场景。
  1. 用户指定模型 → 直接使用指定模型。
  2. 当模型选择依赖于需求、场景或定价时 → 咨询qianwen-model-selector技能。
  3. 文本转图像（仅提示词，无参考图像） → 使用
    wan2.6-t2i
    （默认）或
    wan2.7-image
    /
    wan2.7-image-pro
    （多功能、更高画质）。绝对不要使用
    wan2.6-image
    进行纯文本转图像     — 若无参考图像或
    enable_interleave: true
    ，会报错。
  4. 参考图像/图像编辑/交错输出 → 
    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+
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 <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
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 |
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

**更多示例**（交错输出、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 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+
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found
Missing API keyObtain 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 keyRun 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 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
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)

通用请求字段

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
或
width*height
（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 — 多功能模型请求字段

FieldTypeDescription
reference_images
string[]0–9 image URLs or local paths
reference_image
stringSingle 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
intImages to generate. Sequential mode: 1–12 (default 12). Non-sequential: 1–4 (default 4). Billed per image.
thinking_mode
boolEnable 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
arrayCustom color theme (3–10 colors). Each: 
{"hex":"#C2D1E6","ratio":"23.51%"}
. Sum of ratios = 100%. Non-sequential mode only
watermark
boolAdd "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 — 图像编辑模型请求字段

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 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)
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 qianwen-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
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状态码含义操作
401API密钥无效或缺失若可用则运行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.
  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 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. 立即安装 — 我将为你运行安装命令
  2. 暂时跳过 — 本次不执行任何操作
  3. 永不提醒 — 永久禁用此提示
用户响应后：
  • 用户选择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"):
  1. Look for 
    qianwen-update-check/SKILL.md
    in sibling skill directories.
  2. If found — run: 
    python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response
    and report the result.
  3. If not found — present the install options above.
当用户明确要求检查更新（例如“检查更新”、“查看版本”）时：
  1. 在同级技能目录中查找
    qianwen-update-check/SKILL.md
    。
  2. 若找到 — 运行：
    python3 <qianwen-update-check-dir>/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 — 官方文档URL