chenoneto qwen-image-3.0-pro 文生图
调用千问AI平台 DashScope 原生同步接口，用 qwen-image-3.0-pro 模型把文本提示词生成 PNG 图像并下载到本地。
何时使用
- 用户明确点名
qwen-image-3.0-pro或千问AI平台画图。 - 需要中文/多语言文字精准渲染、复杂版式（海报、菜单、分镜、试卷）或写实摄影质感的图像。
- 用户只要求文生图。如需图生图或图像编辑，告诉用户本 skill 不支持，建议用千问对应能力。
前置条件
- 用户已在千问AI平台开通
qwen-image-3.0-pro并获取 API Key。 - API Key 存在环境变量
DASHSCOPE_API_KEY中。若缺失，提示用户在平台获取后设置环境变量，不要让用户在对话里贴出密钥，也不要把密钥写进脚本或命令历史。 - 网络可访问
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 已过期 → 需重新调用并再次确认费用 |
反例与黑名单（不要做的事）
- 不切换模型：不用 qwen-image-plus/max/2.0 或 wan 系列替代，即使它们更便宜或更快。
- 不走兼容端点：不用 OpenAI compatible-mode 调用，会返回 model_not_supported。
- 不自动重试付费请求：429/5xx/网络中断一律人工重试，避免重复计费。
- 不把密钥写进脚本或命令历史：只从
DASHSCOPE_API_KEY读取。 - 不让用户在对话里贴密钥：引导设置环境变量。
- 不跳过付费检查点：即使用户说"快画"，也要先展示费用再调用。
- 不依赖 URL 长期可用：拿到立即下载，24 小时后过期。
- 不编造参数：所有字段来自官方文档，不新增文档未列出的参数。
- 不并发调用：RPM=1，串行执行。
资源
| 路径 | 用途 |
|---|---|
scripts/generate.py |
确定性调用脚本，含参数校验、dry-run、付费预估、下载 |
references/api_reference.md |
官方 API 速查：端点、字段、响应、定价、错误码 |
test-prompts.json |
darwin 评分用测试 prompt |