qwencloud-image-generation

Qwen 图像生成

使用 Wan 和 Qwen Image 模型生成和编辑图像。支持文生图、参考图编辑（风格迁移、主体一致性、多图合成、文字渲染）以及文本与图像交错输出。 此技能是 qwencloud/qwencloud-ai 的一部分。

技能目录

使用此技能的内部文件来执行操作和了解详情。当默认路径无法使用或需要更多信息时，按需加载参考文件。

位置	用途
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

安全

绝不以明文形式输出任何 API 密钥或凭据。始终使用变量引用（Shell 中使用 $QWENCLOUD_API_KEY，Python 中使用 os.environ["QWENCLOUD_API_KEY"]）。脚本依次接受 QWENCLOUD_API_KEY、QWEN_API_KEY 和 DASHSCOPE_API_KEY。任何凭据检查或检测都必须以非明文方式进行：只报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不显示可能包含机密的 .env 或配置文件内容。

**未配置 API 密钥时，绝不要求用户直接提供密钥。**应帮助用户创建包含占位符（QWENCLOUD_API_KEY=sk-your-key-here）的 .env 文件，并指导用户从 QwenCloud 控制台获取实际密钥并替换占位符。仅当用户明确要求时，才写入实际密钥值。

密钥兼容性

脚本同时支持标准 QwenCloud API 密钥（sk-...）和 Token Plan 密钥（sk-sp-...）。对于受支持的图像模型，Token Plan 密钥会自动路由到 Token Plan 端点——参见 Token Plan 模型目录。如果 CDN 访问失败，请使用本地后备文件。

Token Plan：不要使用 curl；始终使用随附的 Python 脚本。

Coding Plan 密钥（前缀同样为 sk-sp-，但通过 Coding Plan 订阅购买）无法使用——Coding Plan 不提供图像生成模型。脚本会在启动时检测密钥类型并据此路由。如果已安装 qwencloud-ops-auth，请参阅其 references/codingplan.md 了解详情。

在不暴露密钥的情况下检测 API 密钥类型：

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qwencloud_lib import detect_api_key_type
print(detect_api_key_type('scripts/qwencloud_lib.py'))
"

输出	含义
token-plan	检测到 Token Plan 密钥（前缀为 sk-sp-）
payg	检测到标准 PAYG 密钥
not-set	环境中未找到 API 密钥

模式选择指南

选择模式前，请获取并阅读当前的 QwenCloud 图像生成模型目录。其中包含模式与模型的推荐搭配、模型列表、模型基本信息、兼容性说明以及默认模型。如果 CDN 访问失败，请使用本地后备文件。

模型选择

🚫 关键 — 切勿覆盖用户指定的参数。 如果用户明确指定了模型（在提示词或请求 JSON 中），则必须使用该模型。不要：

• 将其替换为“更适合”或更新的模型（例如，因为任务“看起来像多功能任务”而把用户指定的 wan2.6-t2i 换成 wan2.7-image）
• 添加用户未要求的参数（thinking_mode、color_palette、bbox_list、风格提示）
• “优化”用户明确指定的任何选项

以下模式／模型指南仅适用于用户未指定模型的情况。如果用户指定的模型无法实现其要求（例如，受 API 硬性限制），则在可行的情况下按用户指定的方式执行；否则，向用户说明限制并让用户决定——不要暗中切换模型。

使用上方链接的图像生成模型目录，了解当前模型系列、默认选项、建议、兼容性和限制。

1. 用户指定了模型 → 必须：使用该确切模型——不得替换、不得“优化”、不得添加用户未要求的参数。
2. 模型选择取决于需求、场景或价格时，请查阅 qwencloud-model-selector skill。
3. 未指定模型 → 从模型目录中选择当前默认模型或针对该任务的推荐模型。如果用户要求的操作与模型文档中记载的硬性限制冲突，请说明限制并让用户决定；绝不能暗中替换用户明确选择的模型。

⚠️ 重要：模型目录是某一时间点的快照，可能已经过时。模型可用性 经常变化。做出模型决策前，务必查看官方模型列表， 以获取权威且最新的目录。

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

动态模型查询：如果 qwencloud-model-selector skill 或 QwenCloud CLI（qwencloud models info <model>）可用，请使用它获取实时模型数据。CLI 需要身份验证——登录流程请参阅 qwencloud-usage skill。

执行

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

先决条件

• API 密钥：依次检查 QWENCLOUD_API_KEY、QWEN_API_KEY，然后是 DASHSCOPE_API_KEY，且只能使用非明文检查方式（例如，在 shell 中使用 [ -n "$QWENCLOUD_API_KEY" ]；仅报告“已设置”或“未设置”，绝不显示密钥值）。如果未设置：如果 qwencloud-ops-auth skill 可用，则运行该 skill；否则，引导用户从 QwenCloud Console 获取密钥，并通过 .env 文件（在项目根目录或当前目录运行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量进行设置。脚本会在当前工作目录和项目根目录中查找 .env。Skills 可单独安装——不要假定 qwencloud-ops-auth 已安装。 注意：脚本会自动加载当前目录和项目根目录中的 .env（此外也会读取已导出的环境变量）。shell 检查显示 $QWENCLOUD_API_KEY“未设置”，并不意味着脚本会失败——密钥可能仍在 .env 中找到。shell 检查仅供参考；权威测试方式是直接运行脚本（如果任何位置都找不到密钥，脚本会退出并显示明确错误）。
• Python 3.9+（仅使用标准库，无需安装 pip 包）

环境检查

首次执行前，请确认 Python 可用：

python3 --version  # must be 3.9+

如果 python3 不可用或版本低于 3.9，PAYG 可以使用路径 2（curl）；Token Plan 则必须安装 Python 3.9+。

默认：运行脚本

脚本路径：脚本位于此技能目录（包含此 SKILL.md 的目录）下的 scripts/ 子目录中。**必须先找到此技能的安装目录，然后始终使用绝对路径执行 脚本。**不要假设脚本位于当前工作目录中。执行前不要使用 cd 切换目录。

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

**发现：**先运行 python3 <this-skill-dir>/scripts/image.py --help，查看所有可用参数。

# Text-to-image (use the default from the CDN model catalog)
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

# Image editing with reference images (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/qwencloud-image-generation/images/out.png \
  --print-response

# z-image-turbo (sync-only, no n; size omitted → server default 1024*1536)
python3 <this-skill-dir>/scripts/image.py \
  --model z-image-turbo \
  --request '{"prompt":"A sitting orange cat, realistic","prompt_extend":false}' \
  --output output/qwencloud-image-generation/images/out.png \
  --print-response

# qwen-image-3.0-pro (no size → auto-recommended resolution)
python3 <this-skill-dir>/scripts/image.py \
  --model qwen-image-3.0-pro \
  --request '{"prompt":"A poster reading \"限时特惠\"","enable_thinking":true}' \
  --output output/qwencloud-image-generation/images/out.png \
  --print-response

# qwen-mt-image-2.0 (API supports sync/async; bundled script uses async)
python3 <this-skill-dir>/scripts/image.py \
  --model qwen-mt-image-2.0 \
  --request '{"image_url":"https://example.com/poster_zh.jpg","source_lang":"zh","target_lang":"en"}' \
  --output output/qwencloud-image-generation/images/out.png \
  --print-response

更多示例（交错输出、wan2.5-i2i、qwen-image-2.0-pro、qwen-image-plus）：请参阅 execution-guide.md

参数	描述
--request '{...}'	JSON 请求正文
--file path.json	从文件加载请求
--async	强制使用异步模式；如果脚本的实现使用异步，脚本会自动启用该模式。对于仅支持同步的模型（例如 qwen-image-max），此参数会被忽略
--model ID	覆盖模型（请查看上方的模型目录，了解当前默认值）
--output path	将图像保存到指定路径（多图输出时保存到指定目录）。将多张图像写入同一目录时，文件会自动使用 OSS URL 中的唯一标识符命名，以防止不同运行之间相互覆盖。显式指定的文件路径仍优先使用；多次调用时请使用不同的文件名，以避免覆盖
--print-response	将响应 JSON 打印到标准输出

验证结果

• 退出代码为 0 且输出包含有效 JSON，其中包含 output.results 或 output.task_id → 成功
• 非零退出代码、HTTP 错误、空响应或错误 JSON → 失败
• 异步：提交必须返回 output.task_id；轮询必须达到 task_status: SUCCEEDED
• 执行后检查：确认输出文件存在且大小非零（ls -la <output_path>）
• 必须执行 — 标准错误信号检查：确认结果后，扫描命令的标准错误输出，查找 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]。如果出现任一信号，在回复用户之前，必须按照下方的更新检查（执行后必做）中的说明操作。

失败时

如果脚本运行失败，请将错误输出与下方的诊断表进行匹配，以确定解决方法。如果没有匹配项，请阅读 execution-guide.md，了解替代方案：curl 命令（路径 2 — 同步和异步）、代码生成（路径 3）和自主解决（路径 5）。

如果完全无法使用 Python → PAYG 可以使用路径 2（curl）；Token Plan 必须安装 Python 3.9+。

错误模式	诊断	解决方法
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+
未找到 QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY	缺少 API 密钥	从 QwenCloud Console 获取密钥；添加到 .env：echo 'QWENCLOUD_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 指定可写目录

快速参考

请求字段（通用）

字段	类型	描述
prompt	string	要生成的图像的文本描述（必填；不适用于图像翻译）
negative_prompt	string	图像中需要避免的内容（最多 500 个字符）
size	string	分辨率；目录中列出的限制请参阅模型目录，未列出的模型专属值请参阅 API 指南或官方文档
seed	int	用于确保可复现性的随机种子 [0, 2147483647]
model	string	模型 ID；请查看上方模型目录，了解当前默认模型和支持的模型
prompt_extend	bool	启用提示词改写（默认值：true；仅适用于图像编辑模式）
enable_thinking	bool	仅适用于 qwen-image-3.0 — 增强推理（默认值：true）。仅在 prompt_extend=true 时生效
prompt_extend_mode	string	仅适用于 qwen-image-3.0 — direct（DPE，默认值）或 agent（APE；仅适用于 t2i）

请求字段（wan2.7-image-pro / wan2.7-image — 多功能）

字段	类型	描述
reference_images	string[]	0–9 个图像 URL 或本地路径
reference_image	string	单个图像 URL/路径（简写形式）
size	string	1K、2K（默认值）或 4K（仅限 pro，t2i 模式）。也可使用像素尺寸
enable_sequential	bool	true：顺序多图模式（n=1–12）。false（默认值）：单张/批量模式（n=1–4）
n	int	要生成的图像数量。顺序模式：1–12（默认值 12）。非顺序模式：1–4（默认值 4）。按图像计费。
thinking_mode	bool	启用增强推理以提升质量（默认值：true）。仅适用于 t2i（无图像、非顺序模式）
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 会生成连贯的图像序列（例如，同一角色出现在不同场景中）。

请求字段（wan2.6-image — 图像编辑）

字段	类型	描述
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）

其他模型

如需查看当前模型列表及模型专属的兼容性差异，请使用上方链接的模型目录。

图像翻译请求字段

对于从目录中选定的图像翻译模型，请使用 image_url、source_lang 和 target_lang；不要发送 prompt。可选的 ext 对象用于传递领域/风格提示、精确匹配时要跳过的词语、术语对以及图像分割设置。即使成功完成的任务没有可翻译文本，也仍可能产生费用。

完整参数表：详细参数请参阅 api-guide.md。

尺寸参考（wan2.6-image）

• 编辑模式：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）

响应字段

字段	描述
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 详情

• 同步端点（wan2.6-t2i、wan2.6-image 编辑、qwen-image-edit 系列、qwen-image-max、z-image-turbo）：POST /api/v1/services/aigc/multimodal-generation/generation
• 异步端点（wan2.6 及更早的 t2i）：POST /api/v1/services/aigc/image-generation/generation，并设置 X-DashScope-Async: enable
• 异步端点（wan2.5-i2i-preview；qwen-mt-image-2.0 的捆绑脚本路由）：POST /api/v1/services/aigc/image2image/image-synthesis，并设置 X-DashScope-Async: enable。图像翻译 API 本身支持同步和异步模式；image.py 当前实现了异步提交和轮询。
• 异步端点（qwen-image-plus 和 qwen-image）：POST /api/v1/services/aigc/text2image/image-synthesis，并设置 X-DashScope-Async: enable。qwen-image-max 仅支持同步模式，不得使用此路由。
• 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，TTL 为 48h）。直接传入本地路径即可，无需手动上传。

  ⚠️ Token Plan 限制：Token Plan 不支持上传本地文件。如果使用 Token Plan 密钥（sk-sp-...），请提供可公开访问的 https:// URL 作为参考图像，而不是本地路径。

• 生产环境：默认临时存储的 TTL 为 48h，上传限制为 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 提供凭证。请使用遵循最小权限原则的 RAM 用户（仅对目标存储桶授予 oss:PutObject 和 oss:GetObject 权限）。如果已安装 qwencloud-ops-auth，请参阅其 references/custom-oss.md 获取完整设置指南。
• 交错同步：需要流式传输（X-DashScope-Sse: enable + stream: true）；请改用此脚本的异步模式

跨技能串联

将生成的图像用作其他技能（例如 video-gen i2v、vision analyze）的输入时：

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

场景	使用
传给其他技能（video-gen、vision、image-edit）	image_url（URL）
向用户展示 / 在编辑器中打开	local_path（本地文件）

错误处理

HTTP	含义	操作
401	API 密钥无效或缺失	如果可用，运行 qwencloud-ops-auth；否则提示用户设置密钥（仅进行非明文检查）
400	请求无效（提示词、尺寸无效）	检查参数和限制
429	请求频率受限	使用指数退避重试
5xx	服务器错误	使用指数退避重试

用量与账单：使用 qwencloud-usage 技能直接检查用量、免费套餐额度和账单。或者，用户可以访问 QwenCloud 控制台： 用量分析 | 按需付费账单 | 编码计划账单

绝不要编造、猜测或拼接用量／账单／控制台 URL。 仅提供此技能中列出的确切链接。如果此处未列出某个 URL，请勿自行编造。

输出位置

优先使用当前工作目录。默认子目录：./output/qwencloud-image-generation/。

禁止写入：绝不要将输出文件写入此技能的安装目录或任何 skills/ 层级目录。所有生成的内容都必须写入当前工作目录下的 output/，或用户指定的路径。

Token Plan 支持

Token Plan 密钥（sk-sp-...）支持部分图像模型。脚本会自动路由至 Token Plan 端点。

⚠️ Token Plan 限制：Token Plan 不支持上传本地文件。如果使用 Token Plan 密钥（sk-sp-...），请提供可公开访问的 https:// URL 作为参考图像，而非本地路径。

支持的模型

获取并阅读当前的 Token Plan 模型目录，然后使用其中精确列出的图像生成模型。如果 CDN 访问失败，请使用本地备用文件。

Token Plan 不支持的模型

Token Plan 模型目录中未列为支持图像生成的模型需要使用 PAYG 密钥。

必需的标头

会自动包含 User-Agent: qwencloud-skills。

更新检查（执行后必须进行）

脚本执行后，检查 stderr 中是否包含操作信号。脚本会自动检测更新状态并发出结构化信号。你必须根据这些信号采取行动。本节也适用于用户明确要求检查更新的情况。

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

当 stderr 中出现此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。切勿默默跳过。

更新检查技能尚未安装。它会通知你 qwencloud/qwencloud-ai 的新功能和错误修复。

1. 立即安装 — 我会为你运行安装命令
2. 暂时跳过 — 本次不进行任何操作
3. 不再提醒我 — 永久关闭此提示

用户回复后：

• 用户选择 1 → 运行：npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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，然后照常继续

信号：[UPDATE_AVAILABLE]

当 stderr 中出现此信号时，你必须在回复中附上简短的更新通知，其中包含版本信息和 stderr 输出中显示的更新命令。

stderr 中没有信号

如果 stderr 中既没有 [ACTION_REQUIRED]，也没有 [UPDATE_AVAILABLE]，则无需采取任何操作——该技能已安装且为最新版本（或缓存时间不超过 24 小时）。

用户的明确请求

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

1. 在同级技能目录中查找 qwencloud-update-check/SKILL.md。
2. 如果找到，则运行：python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response 并报告结果。
3. 如果未找到，则展示上述安装选项。

参考资料

• execution-guide.md — 备用路径（curl 同步/异步、代码生成、自主执行）
• api-guide.md — API 补充指南
• sources.md — 官方文档 URL