APIMODELSAPIMODELS
Docs/Qwen Image 3.0 API

Qwen Image 3.0 API

阿里巴巴 Qwen Image 3.0。同一端点支持文生图与图像编辑(传参考图即进入编辑,最多 3 张),强项是密集图内文字、12 国语言与结构化版面。分辨率 1K / 2K,画幅 8 档或 auto。两档:标准 qwen3-image($0.035/张)、Pro qwen3-image-pro(1K $0.037 / 2K $0.075)。异步任务:POST 创建后 GET 轮询或走 callback_url。

认证

Authorization: Bearer YOUR_API_KEY

模型与价格

模型model价格说明
Qwen Image 3.0qwen3-image$0.0351K/2K 同价 · 日常批量
Qwen Image 3.0 Proqwen3-image-pro$0.037 / $0.0751K / 2K · 照片级细节

图像编辑时每张参考图另加 $0.004。失败不扣费。

端点

POST/api/v1/images/generations创建任务
GET/api/v1/images/generations?task_id=...查询状态

代码示例

# ─── 1. Text-to-image ──────────────────────────────────────
# model: "qwen3-image" (standard) or "qwen3-image-pro" (higher fidelity).
# resolution: "1K" | "2K". aspect_ratio: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9 (or "auto").
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image",
    "prompt": "A cafe opening poster, vertical layout. Bold brush-calligraphy title, small caption text, minimal editorial style",
    "resolution": "2K",
    "aspect_ratio": "9:16"
  }'

# Response:
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx...", "state": "pending" } }


# ─── 2. Image editing with a reference URL ─────────────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image-pro",
    "prompt": "Keep the subject, change to soft evening light",
    "image_urls": ["https://example.com/photo.jpg"],
    "aspect_ratio": "auto"
  }'


# ─── 3. Multi-image edit (up to 3 reference images) ────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image",
    "prompt": "Replace the poster in image 1 with the product from image 2",
    "image_urls": [
      "https://example.com/scene.jpg",
      "https://example.com/product.jpg"
    ]
  }'


# ─── 4. Poll task status ───────────────────────────────────
curl "https://api.apimodels.app/v1/images/generations?task_id=clxxx..." \
  -H "Authorization: Bearer YOUR_API_KEY"

请求参数

字段必填类型说明
model是string"qwen3-image"(标准)或 "qwen3-image-pro"(Pro)
prompt是string图片描述或编辑指令,支持中英文。编辑多图时可用 "image 1"、"image 2" 引用具体参考图。
resolution否string"1K"(默认)或 "2K"。标准版 1K/2K 同价 $0.035;Pro 版 1K $0.037、2K $0.075。
aspect_ratio否string画幅:1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 16:9 / 9:16 / 21:9。省略或传 "auto" 由模型按提示词自动选择。
image_urls否string[]参考图 URL(1–3 张,每张 ≤ 10MB,jpeg/png/webp)。传入则走图像编辑,每张另加 $0.004。
image_url否string单张参考图 URL,等价于 image_urls 只传一张。
image_base64否stringBase64 或 data URI 的参考图(本地文件用)。
negative_prompt否string反向提示词,描述不希望出现的内容。
prompt_extend否boolean是否开启提示词智能改写,默认 true。短提示词开启后效果更好。
seed否integer随机种子 [0, 2147483647]。固定可复现结果。
callback_url否string任务完成回调 URL,服务端 POST 与轮询相同结构的 JSON。

响应字段

字段必填类型说明
code—integer200 表示创建/查询成功;其他值见错误码表
msg—string"success" 或错误描述
data.taskId—string任务 ID,查询状态时用
data.state—stringpending / processing / completed / failed
data.resultUrls—string[]仅在 state=completed 时返回;R2 托管图片 URL,保留 30 天后自动删除,请及时下载或转存。
data.failMsg—string仅在 state=failed 时返回,上游失败原因

说明

  • 异步流程:POST 立即返回 taskId(state=pending),再 GET ?task_id= 轮询直到 completed。
  • 出图较慢,请把轮询窗口留够。我们自己生产数据的实测分位数:标准档中位 73 秒、九成在 96 秒内(最快 36 秒);Pro 中位 121 秒,但尾巴很长——一成会超过 324 秒,最慢见过 359 秒。所以标准档留 3 分钟、Pro 至少留 8 分钟,不要按几十秒的超时去掐客户端请求。
  • 端点自动路由:只传 prompt → 文生图;携带 image_urls / image_url / image_base64 → 图像编辑。无需切换端点或模型名。
  • aspect_ratio 传 "auto"(或省略)时由模型按提示词自动选择画幅——不会报错。
  • 图像编辑最多 3 张参考图,每张另加 $0.004;标准/Pro 输入图单价相同。
  • callback_url 优先于轮询——后端会在完成时 POST 同样的 data 结构,适合生产。
  • resultUrls 指向 R2,保留 30 天后自动删除,请在窗口内下载或转存到自有存储。
  • 失败不扣费:state=failed 的任务不计入账单,可安全重试。

试一试:Playground,Pro 版见 Qwen Image 3.0 Pro

常见问题

Qwen Image 3.0 API 多少钱?

标准版 qwen3-image 1K/2K 同价 $0.035/张;Pro 版 qwen3-image-pro 1K $0.037、2K $0.075。图像编辑每张参考图另加 $0.004。失败不扣费。

一个模型同时能文生图和编辑吗?

可以。只传 prompt 就是文生图;加 image_urls(1–3 张参考图)同一个模型就转为图像编辑。无需切端点或模型名。

一次请求要多久?轮询窗口该留多长?

按我们自己生产数据的实测:标准档中位 73 秒、九成在 96 秒内;Pro 中位 121 秒但尾巴很长,一成超过 324 秒、最慢见过 359 秒。标准档留 3 分钟、Pro 至少留 8 分钟。按中位数设窗口正是「任务看起来卡住」的最常见原因。

一次能传几张参考图?

最多 3 张,每张不超过 10MB,jpeg/png/webp。传第 4 张会在创建时直接被拒,而不是静默丢掉。每张参考图 +$0.004,所以 1K 标准档带 3 张参考图编辑 = $0.035 + 3 × $0.004 = $0.047。

aspect_ratio 传 auto 是什么行为?

跟随第一张参考图的比例 —— 做编辑时不想让主体被重新裁切就用它。纯文生图时没有可跟随的对象,请显式传八种比例之一(1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9)。

能不能用回调代替轮询?

可以,创建任务时传 callback_url,出图后我们会 POST 给你 —— 考虑到 Pro 的长尾,回调比轮询更合适。GET ?task_id= 轮询同时仍然可用,两者不互斥;回调 + 一个低频兜底轮询是最稳的组合。

resultUrls 能用多久?

30 天,到期自动删除。需要长期使用的请自行下载转存,别把我们的链接当永久图床存进你的库里。

Qwen Image 3.0 支持 4K 或蒙版局部重绘吗?

都不支持。所有档位最高 2K,要原生 4K 请用 gpt-image-2($0.05/张)。也没有 mask 参数;局部修改的做法是把原图放进 image_urls,再用提示词描述要改什么。