Qwen-ImageAPI 参考

用代码调用千问图片模型出图、改图：三步快速开始、每个字段、每张积分价、回调和幂等。

测试版接口POST /v1/images/generationsOpenAPI llms.txt

申请 API 开通

开发者 API 需申请开通。

图片 API 目前是测试版，字段可能调整。创作台不受影响。

快速开始三次调用

设置 Key，带价格上限提交任务，再取结果。

01
设置 Key
开发者 API 需申请开通：在创作台的 API Keys 页面申请。Key 只显示一次，存进环境变量。
Shell
```
export API_KEY="sk_test_…"
```

提交任务

带上 Idempotency-Key 和 max_credits 上限提交。改图模型还要带 image_url。马上返回 202 和排队中的任务，积分同时冻结。

POST /images/generations

curl https://api.pershot.app/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2512",
    "prompt": "A ceramic mug on a walnut table, soft window light, product photo",
    "size": "1K",
    "aspect_ratio": "1:1",
    "max_credits": 2
  }'

应当返回

{
  "id": "job_01J9ZK4T8W",
  "object": "job",
  "kind": "image",
  "status": "queued",
  "money_status": "reserved",
  "queue_position": 2,
  "requested_model": "qwen-image-2512",
  "credits_quoted": 2,
  "credits_charged": null
}

03
取结果
轮询这个任务，直到状态是 succeeded。outputs[].url 是签名链接，24 小时后失效，要留的文件及时下载。
GET /jobs/{id}
```
curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \
  -H "Authorization: Bearer $API_KEY"
```

参数和限制

下表读自 OpenAPI 文档，它和接口校验用的是同一套结构定义。不认识的字段会被拒绝。

Qwen-Image 请求字段
字段	类型	取值	说明
`model`必填	string	qwen-image-2512-lightning · qwen-image-2512 · qwen-image-edit-2511-lightning · qwen-image-edit-2511	型号 ID。
`prompt`必填	string	2–2,000 个字符	要生成什么：主体、镜头和光线。
`size`默认 "1K"	string	1K · 2K	1K 用于草稿和首帧，2K 用于细节。
`aspect_ratio`默认 "1:1"	string	16:9 · 9:16 · 1:1	画幅。
`image_url`可选	string	https 链接	视频的首帧；改图模型的原图。公开的 https 链接或上传得到的链接。
`seed`可选	integer	0–2,147,483,647	输入相同时复现结果。
`quote_id`可选	string	以 qt_ 开头	按 POST /v1/quotes 的报价执行，报价 10 分钟内有效。
`max_credits`可选	number	> 0	这个任务最多花多少。超过就拒绝，不会扣费。
`webhook_url`可选	string	https 链接	接收任务事件的 https 地址。
`end_user_id`可选	string	1–128 个字符	仅限已开通的开发者账户（需申请开通）：给这次请求标上的你自己的用户 ID，会显示在用量里。
`project_id`可选	string	以 prj_ 开头
`shot_id`可选	string	以 sht_ 开头
`routing_preference`可选	string	stability · speed

quote_id 和 max_credits 必须二选一。这个接口不接受 model 为 "auto"：视频请先调用 POST /v1/auto/plan，再带上 max_credits 提交它选出的模型。

型号: qwen-image-2512-lightning出图 · Qwen-Image-2512 · Lightning 4-stepqwen-image-edit-2511-lightning改图 · Qwen-Image-Edit-2511 · Lightningqwen-image-2512出图 · Qwen-Image-2512qwen-image-edit-2511改图 · Qwen-Image-Edit-2511
频率和并发: 默认每个 Key 每分钟 60 次请求，每个账户同时 3 个任务。多开 Key 不会增加并发。
给 AI 智能体: 给 AI 智能体读的纯文本：输入、可用取值、每种设置的价格和请求示例qwen-image-2512-lightningqwen-image-2512qwen-image-edit-2511-lightningqwen-image-edit-2511

参数限制

下表读自接口校验用的同一张表。每一行都写明由谁检查，超出后会怎样。

平台校验我们检查，不符合就返回 400，不报价也不冻结积分。
供应商校验由供应商检查。被拒的任务会失败，不收费。
建议值没有人检查。控制在范围内，效果更好。

qwen-image-2512-lightning, qwen-image-2512 的参数限制
限制项	取值	单位	谁来检查	超出后
请求参数
提示词长度`prompt`	2 至 2,000	字符	平台校验	返回 400 invalid_request（prompt），不报价，也不冻结积分。
图片尺寸`size`	1K, 2K默认 1K	–	平台校验	返回 400 invalid_request（size）。
画幅`aspect_ratio`	16:9, 9:16, 1:1默认 1:1	–	平台校验	返回 400 invalid_request（aspect_ratio）。
你传入的图片
原图`image_url`	不接受	–	平台校验	改图模型必须带 image_url，出图模型不接受：返回 400 invalid_request（image_url）。
输出
输出像素	1K16:91344×7689:16768×13441:11024×10242K16:92048×11529:161152×20481:12048×2048	像素	平台校验	我们按这些尺寸出图。
输出边长	256 至 2,048	像素（每边）	供应商校验	上面的尺寸都在范围内。更大的尺寸供应商会拒绝。
输出格式	JPEG	–	平台校验	图片都是 JPEG。
链接
结果链接	24	小时	平台校验	过期后链接返回 403。重新读取任务即可拿到新链接。文件本身保留 12 个月（任务的 outputs_expire_at 是具体日期）；存进素材库或用在项目里的会保留更久。

qwen-image-edit-2511-lightning, qwen-image-edit-2511 的参数限制
限制项	取值	单位	谁来检查	超出后
请求参数
提示词长度`prompt`	2 至 2,000	字符	平台校验	返回 400 invalid_request（prompt），不报价，也不冻结积分。
图片尺寸`size`	1K, 2K默认 1K	–	平台校验	返回 400 invalid_request（size）。
画幅`aspect_ratio`	16:9, 9:16, 1:1默认 1:1	–	平台校验	返回 400 invalid_request（aspect_ratio）。
你传入的图片
原图`image_url`	必须 1 张	–	平台校验	改图模型必须带 image_url，出图模型不接受：返回 400 invalid_request（image_url）。
上传大小`file`	最多 10	MB	平台校验	POST /v1/uploads 返回 400 invalid_request（file）。
上传格式`file`	JPEG, PNG, WebP	–	平台校验	按文件内容判断，不看文件名。其他类型返回 400 invalid_request（file）。
输出
输出像素	1K16:91344×7689:16768×13441:11024×10242K16:92048×11529:161152×20481:12048×2048	像素	平台校验	我们按这些尺寸出图。
输出边长	512 至 2,048	像素（每边）	供应商校验	上面的尺寸都在范围内。更大的尺寸供应商会拒绝。
输出格式	JPEG	–	平台校验	图片都是 JPEG。
链接
上传链接	7	天	平台校验	过期后链接返回 403，需要重新上传。
结果链接	24	小时	平台校验	过期后链接返回 403。重新读取任务即可拿到新链接。文件本身保留 12 个月（任务的 outputs_expire_at 是具体日期）；存进素材库或用在项目里的会保留更久。

其他网站上的图片我们不会去下载。这类链接由供应商检查尺寸，被拒的任务不收费。同样的限制也能以 JSON 读取：GET /v1/models 为每个型号返回 limits 对象。

所有型号的参数限制

价格算法公开

每张一个价，按型号和尺寸计，单位是积分（1 美元 = 100 积分）。出图和改图分开定价。

Qwen-Image 价格
型号	1K	2K
`qwen-image-2512-lightning`出图	1 积分≈ $0.01≈ 1,000 张 / $10	3 积分≈ $0.03≈ 333 张 / $10
`qwen-image-edit-2511-lightning`改图	2 积分≈ $0.02≈ 500 张 / $10	4 积分≈ $0.04≈ 250 张 / $10
`qwen-image-2512`出图	2 积分≈ $0.02≈ 500 张 / $10	6 积分≈ $0.06≈ 166 张 / $10
`qwen-image-edit-2511`改图	3 积分≈ $0.03≈ 333 张 / $10	10 积分≈ $0.10≈ 100 张 / $10

价格怎么算

回调和幂等

重试不会重复扣费，也不必一直轮询。

幂等: 每个生成请求都要带 Idempotency-Key（1 至 255 个可见 ASCII 字符）。24 小时内用同一个键，返回同一个任务和 HTTP 200，所以超时后重试不会多建任务，也不会多扣费。
被拒的提示词: 预检拒绝的提示词（422 content_rejected）什么都不会创建，同一个键可以换个提示词再用。
事件: job.queuedjob.processingjob.succeededjob.failedjob.cancelled
签名: X-Signature 里有 t（Unix 时间）和 v1：用你的 whsec_ 密钥，对 t、一个点和原始请求体做 HMAC-SHA256。时间戳超过 5 分钟的请求直接拒绝，并按 X-Event-Id 去重。
投递: 10 秒内返回 2xx 即算送达。失败后依次在 1 分钟、5 分钟、30 分钟、2 小时、6 小时后重试。不跟随重定向。

回调内容

{
  "id": "evt_01J9ZKB1QX",
  "type": "job.succeeded",
  "created_at": "2026-09-29T14:02:31Z",
  "data": {
    "job": {
      "id": "job_01J9ZK4T8W",
      "object": "job",
      "kind": "image",
      "status": "succeeded",
      "money_status": "settled",
      "requested_model": "qwen-image-2512",
      "credits_charged": 2,
      "outputs": [
        {
          "kind": "image",
          "url": "https://…/job_01J9ZK4T8W.png?sig=…"
        }
      ]
    }
  }
}

校验 X-Signature

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
  let t = null;
  const signatures = [];
  for (const item of (header ?? "").split(",")) {
    const [key, value] = item.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(Buffer.from(value, "hex"));
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.

错误码和处理办法

所有错误的结构都一样：一个 error 对象，含 code、message、param 和 request_id。最常遇到的是这些：

错误码	HTTP	怎么处理
`invalid_request`	400	按 param 指出的字段修改。
`unauthorized`	401	检查 Key 和 Bearer 请求头。
`insufficient_credits`	402	充值后用同一个 Idempotency-Key 重试。
`forbidden_model`	403	在创作台把该型号或工具加进这个 Key 的可用清单，或换一个 Key。视频增强等工具要单独勾选。
`quote_expired`	409	重新报价，报价 10 分钟内有效。
`price_changed`	409	价格超过了你的上限。重新报价，或调高 max_credits。
`content_rejected`	422	没有扣费。修改提示词或图片后再试。
`rate_limited`	429	按 Retry-After 等待后重试。
`upstream_unavailable`	503	模型暂时不可用，稍后重试。没有开始的任务不收费。

OpenAPI 3.1 文档 llms.txt 完整文档从 fal、Replicate 或 WaveSpeed 迁移