qianwen-image-generation

Qwen 图像生成

使用 Wan 和 Qwen Image 模型生成和编辑图像。支持文生图、参考图像编辑（风格迁移、主体一致性、多图合成、文本渲染）以及交错式文本-图像输出。 此技能是 QianWen-AI/qianwen-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 中使用 $DASHSCOPE_API_KEY，Python 中使用 os.environ["DASHSCOPE_API_KEY"]）。任何凭据检查或检测都必须以非明文方式进行：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不要显示可能包含机密的 .env 或配置文件内容。

**未配置 API 密钥时，绝不要要求用户直接提供密钥。**应协助创建带占位符的 .env 文件（DASHSCOPE_API_KEY=sk-your-key-here），并指导用户从 QianWen 控制台获取实际密钥后替换占位符。只有在用户明确要求时，才能写入实际密钥值。

密钥兼容性

PAYG（sk-ws-...；旧版 sk-...）和 Token Plan（sk-sp-...）密钥均受支持。检测 API 密钥类型时不得暴露密钥：

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

输出	含义
token-plan	Token Plan 密钥 — 仅使用下方 Token Plan 目录中的模型。
payg	按量付费密钥 — 可使用完整模型目录。
not-set	未配置密钥。

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

Token Plan 不支持本地文件上传；在 i2i 模式下，请提供可访问的参考图像 URL（https:// 或 oss://），而不是本地路径。

Token Plan 仅支持特定模型 — 请严格使用上述参考资料中列出的模型；不要猜测或探测模型是否可用。对于 PAYG，请继续阅读下文。

模式选择指南

1. 用户指定了模型 → 直接使用。
2. 当模型选择取决于需求、场景或价格时，请参考 qianwen-model-selector 技能。

在选择模式或选择、推荐或设为默认模型之前，请获取并阅读最新的 Qwen 图像生成模型目录。其中包含模式到模型的推荐、模型列表、模型基本信息、兼容性说明和默认模型。如果无法访问 CDN，请使用本地备用文件。

⚠️ 重要：上述模型列表是一个特定时间点的快照，可能已经过时。模型可用性 经常变化。在做出模型选择之前，请务必查看官方模型列表 获取权威且最新的目录。

模型详情：如需了解特定模型的更多信息，请引导用户访问 https://www.qianwenai.com/models/<model-name>。将 <model-name> 替换为准确的模型 ID；切勿修改或猜测。

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

执行

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

前置条件

• API 密钥：使用 Key Compatibility 中的非明文检测器；不要将其替换为变量存在性检查。如果未找到密钥，在可用时使用 qianwen-ops-auth，或指导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。技能可以独立安装。
• Python 3.9+（仅使用标准库，无需安装 pip 包）

环境检查

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

python3 --version  # must be 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9，请跳转至 execution-guide.md 中的 路径 2（curl）。

默认方式：运行脚本

脚本路径：脚本位于本技能目录（即包含此 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/qianwen-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/qianwen-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	强制使用异步模式（wan2.5 及更早版本必需；qwen-image-plus/max 和交错输出会自动启用）
--model ID	覆盖模型（请查看上方模型目录，了解当前默认模型）
--output path	将图像保存到指定路径（多图输出时则保存到指定目录）。向同一目录写入多张图像时，文件会自动使用 OSS URL 中的唯一标识符命名，避免不同运行之间发生覆盖。显式文件路径仍优先；多次调用时请使用不同的文件名，以避免覆盖
--print-response	将响应 JSON 打印到标准输出

模型优先级：CLI 的 --model 标志 > --request JSON 中的 "model" 字段 > 内置默认值。

验证结果

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

失败时

如果脚本失败，请将错误输出与下方诊断表进行匹配，以确定解决方法。如果没有匹配项，请阅读 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+
未找到 QIANWEN_API_KEY/DASHSCOPE_API_KEY	缺少 API 密钥	从 QianWen Console 获取密钥；将密钥添加到 .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 指定可写目录

快速参考

请求字段（常用）

字段	类型	描述
prompt	string	要生成图像的文本描述（必填）
negative_prompt	string	图像中要避免的内容（最多 500 个字符）
size	string	分辨率；支持的值和默认值因模型而异，请阅读上方的模型目录
seed	int	用于保证可复现性的随机种子 [0, 2147483647]
model	string	模型 ID；请查看上方的模型目录，了解当前默认模型和支持的模型
prompt_extend	bool	启用提示词改写（默认值：true；仅限图像编辑模式）

请求字段（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（默认值为 1）。非连续模式：1–4（默认值为 1）。按图像计费。
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）

其他模型

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

对于目录条目允许生成多个输出的固定分辨率异步文生图模型，捆绑脚本目前会将 n 限制为 1。如需在单个请求中生成多个输出，请使用 api-guide.md 中的直接 API 调用流程。

完整参数表：详细参数请参阅 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 系列）：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）：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，有效期为 48h）。直接传入本地路径即可，无需手动上传。
• 生产环境：默认临时存储的有效期为 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 权限）。如果已安装 qianwen-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 密钥无效或缺失	如果可用，运行 qianwen-ops-auth；否则提示用户设置密钥（仅检查是否为非明文）
400	请求错误（提示词、尺寸无效）	验证参数和约束条件
400 The product is not activated / Model not subscribed	账户未启用第三方模型	访问 Model Market，找到该模型并点击“Enable” / “开通”
429	请求频率受限	使用指数退避策略重试
5xx	服务器错误	使用指数退避策略重试

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

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

输出位置

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

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

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

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

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

当 stderr 包含此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。不要默默跳过。

更新检查 skill 尚未安装。安装后，你可以及时了解 QianWen-AI/qianwen-ai 的新功能和错误修复。

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，然后照常继续

信号：[UPDATE_AVAILABLE]

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

stderr 中没有信号

如果 stderr 中既不包含 [ACTION_REQUIRED]，也不包含 [UPDATE_AVAILABLE]，则无需采取任何操作——该 skill 已安装且为最新版本（或在 24 小时内使用了缓存）。

用户明确提出请求

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

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

参考资料

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