用 Wan/Qwen Image…

当用户想要生成插画、产品图、海报、艺术设计，或基于参考图做风格迁移、主体一致性编辑、多图合成、文字渲染、图文交错内容时，用 QwenCloud 的 Wan/Qwen Image 模型完成文生图与图像编辑。

适用场景

解决思路

1. 先定位本技能安装目录（即包含 SKILL.md 的目录），始终用绝对路径执行 scripts/image.py，不要假设脚本在当前工作目录，也不要用 cd 切换目录；所有脚本都在前台运行并等待 stdout，不要放后台。
2. 首次执行前先运行 python3 --version 确认 Python 3.9+；若 python3 不可用或低于 3.9，PAYG 可走 curl 路径，Token Plan 必须安装 Python 3.9+。
3. 先运行 python3 <this-skill-dir>/scripts/image.py --help 查看全部可用参数。
4. 用非明文方式检查 API Key：依次检查 QWENCLOUD_API_KEY、QWEN_API_KEY、DASHSCOPE_API_KEY，只报告 set/not set，绝不输出密钥值；脚本会自动从当前目录和项目根目录加载 .env，shell 检查显示 not set 不代表脚本会失败，以实际运行脚本为准。
5. 若未配置 API Key，不要直接向用户索要密钥；改为创建含占位符的 .env（QWENCLOUD_API_KEY=sk-your-key-here），并引导用户到 QwenCloud Console（https://home.qwencloud.com/api-keys）获取密钥替换；仅当用户明确要求时才写入真实密钥。
6. 用 python3 -c 调用 detect_api_key_type 检测密钥类型（不暴露密钥）：输出 token-plan 表示 sk-sp- 前缀的 Token Plan 密钥，payg 表示标准 PAYG 密钥，not-set 表示未找到密钥。
7. Token Plan 密钥不要用 curl，始终使用自带的 Python 脚本；Coding Plan 密钥（同为 sk-sp- 前缀但来自 Coding Plan 订阅）不可用于图像生成，脚本会在启动时检测密钥类型并自动路由。
8. 选择模式前先获取并阅读当前的 QwenCloud 图像生成模型目录（CDN 地址 https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-image-generation-models.md），其中包含模式到模型的推荐、模型列表、基本信息、兼容性说明和默认模型；CDN 访问失败时使用本地回退 cdn/references/qwencloud-image-generation-models.md。
9. 模型选择规则：用户明确指定模型时必须严格使用该模型，不得替换成“更合适”或更新的模型、不得添加用户未要求的参数（thinking_mode、color_palette、bbox_list、风格提示等）、不得“优化”用户的显式选择；用户未指定模型时，按模型目录中的当前默认或任务推荐选择；若用户指定的模型与文档中的硬性约束冲突，向用户说明约束让其自行决定，绝不静默替换。
10. 模型选择依赖需求、场景或价格时，参考 qwencloud-model-selector 技能；模型目录只是时间点快照，做模型决策前始终查看官方模型列表 https://www.qwencloud.com/models 获取权威最新目录；模型详情页为 https://www.qwencloud.com/models/<model-name>（用精确模型 ID 替换，绝不修改或猜测 URL 中的模型名）；若 qwencloud-model-selector 技能或 QwenCloud CLI（qwencloud models info <model>）可用，用其获取实时模型数据（CLI 需认证，登录流程见 qwencloud-usage 技能）。
11. 单次会话生成多个文件时，必须给每个文件名加数字后缀（如 out_1.png、out_2.png）防止覆盖。
12. 用脚本执行文生图：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（模型用 CDN 模型目录中的默认值）。
13. 用参考图做图像编辑（wan2.6-image）：加 --model wan2.6-image，request 中带 prompt、reference_images（URL 或本地路径）、n、size（如 1K）。
14. z-image-turbo（仅同步、无 n；省略 size 则服务端默认 1024*1536）：--model z-image-turbo，request 如 '{"prompt":"A sitting orange cat, realistic","prompt_extend":false}'。
15. qwen-image-3.0-pro（不传 size 则自动推荐分辨率）：--model qwen-image-3.0-pro，request 如 '{"prompt":"A poster reading \"限时特惠\"","enable_thinking":true}'。
16. qwen-mt-image-2.0 图像翻译（API 支持同步/异步，自带脚本用异步）：--model qwen-mt-image-2.0，request 用 image_url、source_lang、target_lang，不要发 prompt；可选 ext 对象携带领域/风格提示、精确匹配跳过词、术语对和图像分割设置；无可翻译文本的成功任务仍可能计费。
17. 脚本参数：--request '{...}' 传 JSON 请求体；--file path.json 从文件加载请求；--async 强制异步（脚本在实现使用异步处自动启用，对 qwen-image-max 等仅同步模型忽略）；--model ID 覆盖模型；--output path 保存图片（多图输出时为目录，同目录多图自动用 OSS URL 唯一标识命名防跨次覆盖，显式文件路径优先，跨调用用不同文件名避免覆盖）；--print-response 打印响应 JSON 到 stdout。
18. 验证结果：退出码 0 且输出含 output.results 或 output.task_id 的合法 JSON 为成功；非零退出、HTTP 错误、空响应或错误 JSON 为失败；异步提交必须返回 output.task_id，轮询必须到达 task_status: SUCCEEDED；执行后用 ls -la <output_path> 确认输出文件存在且大小非零。
19. 强制检查 stderr 信号：确认结果后扫描 stderr 是否含 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]，若存在必须按 Update Check 章节处理后再回复用户。
20. 失败时按诊断表匹配错误：command not found: python3 → 试 python 或 py -3，缺失则装 Python 3.9+；Python 3.9+ required 或类型注解 SyntaxError → 升级 Python；密钥未找到 → 从 QwenCloud Console 获取并写入 .env 或运行 qwencloud-ops-auth；HTTP 401 → 运行 qwencloud-ops-auth（仅非明文检查）并验证密钥；SSL: CERTIFICATE_VERIFY_FAILED → macOS 运行 Install Certificates.command，否则设 SSL_CERT_FILE；URLError/ConnectionError → 检查网络，代理后设 HTTPS_PROXY；HTTP 429 → 退避重试；HTTP 5xx → 退避重试；PermissionError → 用 --output 指定可写目录。无匹配时读 references/execution-guide.md 找替代路径（curl 同步/异步、代码生成、自主解决）。
21. 常用请求字段：prompt（必填，图像翻译除外）、negative_prompt（最多 500 字符）、size、seed（[0, 2147483647]）、model、prompt_extend（默认 true，仅图像编辑模式）、enable_thinking（仅 qwen-image-3.0，默认 true，仅当 prompt_extend=true 时生效）、prompt_extend_mode（仅 qwen-image-3.0，direct 为 DPE 默认，agent 为 APE 仅文生图）。
22. wan2.7-image-pro / wan2.7-image 多功能字段：reference_images（0–9 个 URL 或本地路径）、reference_image（单图简写）、size（1K、2K 默认、4K 仅 pro 的文生图模式，或像素尺寸）、enable_sequential（true 为顺序多图模式 n=1–12，false 默认单张/批量模式 n=1–4）、n（顺序模式 1–12 默认 12，非顺序 1–4 默认 4，按图计费）、thinking_mode（默认 true，仅文生图无图且非顺序时可用）、bbox_list（交互编辑区域，格式 [[[x1,y1,x2,y2],...], ...]，列表长度等于图片数，无编辑的图片用空 []）、color_palette（自定义配色 3–10 色，每项 {"hex":"#C2D1E6","ratio":"23.51%"}，比例和为 100%，仅非顺序模式）、watermark（默认 false，加“AI Generated”水印）。
23. wan2.6-image 图像编辑字段：reference_images（编辑模式 1–4 个，交错模式 0–1 个）、reference_image（单图简写，reference_images 优先）、enable_interleave（false 默认图像编辑模式，true 为图文交错输出）、n（编辑模式生成张数 1–4 默认 1，按图计费）、max_images（交错模式最大张数 1–5 默认 5，按图计费）、watermark（默认 false）。
24. 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）。
25. 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 及更早的文生图）为 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；异步端点（qwen-image-plus 和 qwen-image）为 POST /api/v1/services/aigc/text2image/image-synthesis 加 X-DashScope-Async: enable，qwen-image-max 仅同步不得用此路由。
26. 分辨率与输入约束：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。
27. 本地文件：脚本自动上传到 DashScope 临时存储（oss:// URL，48 小时 TTL），直接传本地路径即可，无需手动上传；Token Plan 不支持本地文件上传，用 sk-sp- 密钥时必须提供公开可访问的 https:// URL 而非本地路径。
28. 生产环境：默认临时存储有 48 小时 TTL 和 100 QPS 上传限制，不适合生产、高并发或压测；要使用自有 OSS bucket，在 .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 提供凭证，使用仅具最小权限（目标 bucket 上仅 oss:PutObject + oss:GetObject）的 RAM 用户；若装了 qwencloud-ops-auth 见其 references/custom-oss.md。
29. 图文交错同步需要流式（X-DashScope-Sse: enable + stream: true），改用本脚本的异步模式。
30. 跨技能串联：把生成图作为其他技能（如 video-gen i2v、vision 分析）输入时直接传 image_url，不要下载后再以本地路径传入；所有下游脚本会识别 https://、oss:// 前缀并直接透传不再上传；local_path 仅用于用户预览或非 API 操作（如在编辑器中打开）。
31. 响应字段：image_url（# 生成图 URL，24 小时有效，串联到其他技能时用这个）、image_urls（多图输出的全部 URL）、image_count、local_path（下载后的本地路径，用于用户预览或非 API 操作）、local_paths、interleaved_content（交错模式的 {type, text/image} 对象数组）、width/height、seed。
32. 输出位置：优先当前工作目录，默认子目录 ./output/qwencloud-image-generation/；绝不把输出文件写入本技能安装目录或任何 skills/ 层级，所有生成内容必须写到当前工作目录下的 output/ 或用户指定路径。
33. Token Plan 支持：sk-sp- 密钥对部分图像模型可用，脚本自动路由到 Token Plan 端点；先获取并阅读 Token Plan 模型目录（CDN https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-token-plan-models.md，失败时用本地回退 cdn/references/qwencloud-token-plan-models.md），使用其中明确列出的图像生成模型；未列为图像能力的模型需要 PAYG 密钥；User-Agent: qwencloud-skills 自动包含。
34. 更新检查（强制）：stderr 含 [ACTION_REQUIRED] qwencloud-update-check skill is not installed 时，必须向用户展示三个选项并等待回复后再继续：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 后正常继续。
35. stderr 含 [UPDATE_AVAILABLE] 时，必须在回复中追加简短更新提示，包含版本信息和 stderr 中给出的更新命令；stderr 两者都没有则无需操作（已安装且最新或在 24 小时缓存内）。
36. 用户明确要求检查更新时：在兄弟技能目录中查找 qwencloud-update-check/SKILL.md，找到则运行 python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response 并报告结果，未找到则展示上述安装选项。
37. 错误处理：401 密钥无效或缺失 → 可用则运行 qwencloud-ops-auth，否则提示用户设置密钥（仅非明文检查）；400 请求错误（prompt、size 无效）→ 核对参数与约束；429 限流 → 指数退避重试；5xx 服务端错误 → 指数退避重试。
38. 用量与计费：用 qwencloud-usage 技能查询用量、免费额度与计费，或让用户访问 QwenCloud 控制台（Usage Analytics https://home.qwencloud.com/analytics、Pay-as-you-go Billing https://home.qwencloud.com/billing/pay-as-you-go、Coding Plan Billing https://home.qwencloud.com/billing/coding-plan）；绝不编造、猜测或构造用量/计费/控制台 URL，只提供本技能列出的确切链接。
39. 安全：绝不以明文输出任何 API Key 或凭证，始终用变量引用（shell 中 $QWENCLOUD_API_KEY，Python 中 os.environ["QWENCLOUD_API_KEY"]）；任何凭证检查必须非明文，只报告状态（如 set/not set、valid/invalid），绝不报告值；绝不显示可能含密钥的 .env 或配置文件内容。

适用边界 · 注意事项

• 用户想理解/分析现有图片或做 OCR 时（应使用 qwencloud-vision）。
• 用户想做视频生成时（应使用 qwencloud-video-generation）。
• 纯文本任务，不涉及图像生成或编辑。