qwen-image-3-0-pro

name	qwen-image-3-0-pro
description	调用千问AI平台 qwen-image-3.0-pro 模型进行文生图（同步 REST 调用）。当用户需要用 qwen-image-3.0-pro 生成海报、复杂文字排版、写实摄影、插画等图像时使用本 skill。触发词：qwen-image-3.0-pro、qwen-image、千问文生图、千问AI平台画图、qwen画图。只实现 qwen-image-3.0-pro 文生图，不支持图生图/图像编辑/其他模型。
agent_created	true

qwen-image-3.0-pro 文生图

调用千问AI平台 DashScope 原生同步接口，用 qwen-image-3.0-pro 模型把文本提示词生成 PNG 图像并下载到本地。

何时使用

• 用户明确点名 qwen-image-3.0-pro 或千问AI平台画图。
• 需要中文/多语言文字精准渲染、复杂版式（海报、菜单、分镜、试卷）或写实摄影质感的图像。
• 用户只要求文生图。如需图生图或图像编辑，告诉用户本 skill 不支持，建议用千问对应能力。

前置条件

1. 用户已在千问AI平台开通 qwen-image-3.0-pro 并获取 API Key。
2. API Key 存在环境变量 DASHSCOPE_API_KEY 中。若缺失，提示用户在平台获取后设置环境变量，不要让用户在对话里贴出密钥，也不要把密钥写进脚本或命令历史。
3. 网络可访问 dashscope.aliyuncs.com。

核心规则（不可违反）

• 模型固定：只用 qwen-image-3.0-pro，不切换、不泛化到 qwen-image-plus/max/2.0 或 wan 系列。
• 端点固定：DashScope 原生端点 https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。不走 OpenAI 兼容模式，否则返回 model_not_supported。
• 付费检查点：该模型按张计费（1K ¥0.25/张，2K ¥0.50/张），RPM=1。每次真正调用前必须向用户展示预计费用并等待确认，缺省只做 dry-run。
• URL 24 小时过期：拿到结果立即下载，不依赖 URL 长期可用。
• 不自动重试付费请求：网络中断可能发生在服务端已生成之后，自动重试会重复计费。

工作流

Step 1：澄清需求

输入：用户的画图请求。 输出：结构化的生成参数。

逐项确认或合理推断以下字段：

字段	取值	默认
prompt	正向提示词，中英文均可，官方上限 800 Token	必填
negative_prompt	不希望出现的元素，≤500 字符	空
size	宽*高，总像素 512²-2048²，宽高比 1:8-8:1	不传，模型推荐
n	1-6	1
prompt_extend	true/false	true
prompt_extend_mode	direct/agent（agent 适合极短提示词）	direct
watermark	true/false	false
seed	0-2147483647	随机

常用尺寸速查：20482048(1:1)、26881536(16:9)、15362688(9:16)、23681728(4:3)、1728*2368(3:4)。

提示词编写建议：结构化描述主体、场景、色调、构图、氛围；需要文字渲染时把要出现的文字明确写进 prompt。详细指南见 references/api_reference.md。

Step 2：dry-run 预览

用 scripts/generate.py 不带 --yes 执行，展示完整请求体和预计费用：

python scripts/generate.py \
  --prompt "..." \
  --size 2048*2048 \
  --n 1 \
  --output-dir ./outputs

输出包含模型、数量、计费档位、预计费用和完整 JSON 请求体，不产生实际调用。

🔴 CHECKPOINT · 🛑 STOP：把预计费用和请求体展示给用户，等待明确确认（如"继续"/"执行"/"确认"）后再进入 Step 3。

Step 3：正式调用

用户确认后加 --yes 执行：

python scripts/generate.py \
  --prompt "..." \
  --size 2048*2048 \
  --n 1 \
  --output-dir ./outputs \
  --yes

脚本流程：读取 DASHSCOPE_API_KEY → POST 请求 → 解析 output.choices[].message.content[].image → 下载 PNG 到 --output-dir → 打印 request_id、usage 和本地文件路径。

环境变量未设置时直接报错退出，不调用 API。

Step 4：交付与善后

• 把下载到本地的 PNG 路径用 present_files 展示给用户。
• 告知用户图片 URL 已过期风险已规避（已下载本地）。
• 如需复用 seed 复现，把用到的 seed 记下。

失败模式与处理

触发条件	一线处理	仍失败兜底
DASHSCOPE_API_KEY 未设置	提示用户在平台获取并设置环境变量	用户无法设置 → 终止，不调用
size 不在 512²-2048² 或宽高比越界	脚本 parse_size 直接报错，按报错调整	用户给的是"横版/竖版"描述 → 按 16:9 或 9:16 推荐合法像素
HTTP 429 Throttling	告知 RPM=1，至少等 60 秒再人工重试	频繁触发 → 减少调用频率，不要并发
DataInspectionFailed / IPInfringementSuspect	修改 prompt 移除违规、名人、品牌、版权 IP	反复触发 → 换内容方向
500/503 服务异常	保留 request_id，稍后人工重试	不要自动重试，避免重复计费
网络中断	不自动重试；告知用户可能已生成	用户决定是否重新调用
响应无图片 URL	打印完整响应交给用户排查	检查 prompt 是否被截断或审核拦截
下载失败	重试下载（不重新生成，不重复计费）	URL 已过期 → 需重新调用并再次确认费用

反例与黑名单（不要做的事）

1. 不切换模型：不用 qwen-image-plus/max/2.0 或 wan 系列替代，即使它们更便宜或更快。
2. 不走兼容端点：不用 OpenAI compatible-mode 调用，会返回 model_not_supported。
3. 不自动重试付费请求：429/5xx/网络中断一律人工重试，避免重复计费。
4. 不把密钥写进脚本或命令历史：只从 DASHSCOPE_API_KEY 读取。
5. 不让用户在对话里贴密钥：引导设置环境变量。
6. 不跳过付费检查点：即使用户说"快画"，也要先展示费用再调用。
7. 不依赖 URL 长期可用：拿到立即下载，24 小时后过期。
8. 不编造参数：所有字段来自官方文档，不新增文档未列出的参数。
9. 不并发调用：RPM=1，串行执行。

资源

路径	用途
scripts/generate.py	确定性调用脚本，含参数校验、dry-run、付费预估、下载
references/api_reference.md	官方 API 速查：端点、字段、响应、定价、错误码
test-prompts.json	darwin 评分用测试 prompt

参考来源

• 开发指南：https://platform.qianwenai.com/docs/developer-guides/image-generation/text-to-image
• API 参考：https://platform.qianwenai.com/docs/api-reference/image-generation/qwen-text-to-image
• 模型页：https://www.qianwenai.com/models/qwen-image-3.0-pro