# Qwen Image 3 0 Pro

> 调用千问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 文生图，不支持图生图/图像编辑/其他模型。

- Skill: `chenoneto/qwen-image-3-0-pro` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add chenoneto/qwen-image-3-0-pro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chenoneto/qwen-image-3-0-pro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: chenoneto (https://skillmd.com/u/chenoneto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chenoneto/qwen-image-3-0-pro

---


# 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 | 随机 |

常用尺寸速查：2048*2048(1:1)、2688*1536(16:9)、1536*2688(9:16)、2368*1728(4:3)、1728*2368(3:4)。

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

### Step 2：dry-run 预览

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

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

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

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

### Step 3：正式调用

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

```bash
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