Create image task
最近更新：2026年9月7日
按百炼原生形状提交 qwen/qwen-image-3.0 的异步出图任务，立刻拿 task_id。
提交 qwen/qwen-image-3.0 的出图任务，立刻返回 task_id，图在后台生成。
请求体与同步那条完全一样，只是这条不等。
https://gateway.amux.ai/api/v1/services/aigc/image-generation/generation鉴权
headerAuthorizationstring必填Bearer <你的 Amux 密钥> 站内 API Key。
请求
application/jsonmodelstring必填上游模型名。这条端点上写 qwen-image-3.0；站内 ID qwen/qwen-image-3.0 同样收。
inputobject必填输入。提示词与参考图都在这里，沿用多模态对话的消息形状。
›inputobject
messagesarray<object>必填消息数组。出图只需要一条 user 消息。
›messagesarray<object>
rolestring恒为 user。
contentarray<object>内容项。参考图在前、提示词在后，照官方示例的顺序。
- {"image": "..."} —— 参考图，1–3 张。收公开 https 地址，也收
data:image/png;base64,... 形式的内联图。官方限制：JPG / JPEG / PNG / BMP /
TIFF / WEBP / GIF，单张 ≤10MB，边长建议 384–2048 像素；
- {"text": "..."} —— 提示词。给了多条会按换行拼起来，不会丢。
图生图就是在提示词那项前面再放一项：
```json
"content": [
{ "image": "https://example.com/ref.png" },
{ "text": "把这只狗换成一只橘猫" }
]
```
⚠️ 一项里不要同时写 image 和 text——照官方示例分成两项写。
›contentarray<object>
textstring提示词。官方建议不超过 4,500 token。
parametersobject生成参数，均为可选。未提供的字段沿用上游自己的默认值，本站不代为设置。
›parametersobject
sizestring输出尺寸，写成 宽*高（宽x高 同样收，我们会归一成上游的写法）。
两条硬约束，超出当场 400，不会被静默改成一个我们猜的尺寸：
- 面积 宽 × 高 落在 262,144（512*512）到 6,553,600（2560*2560） 之间；
- 宽高比在 1:8 到 8:1 之间。
站内在操练场里按常用比例 × 两档分辨率给了预设——但不限于这几个，
任何满足上面两条约束的尺寸都收：
| 比例 | 1K | 2K |
|---|---|---|
| 1:1 | 1024*1024 | 2048*2048 |
| 16:9 | 1280*720 | 2560*1440 |
| 9:16 | 720*1280 | 1440*2560 |
| 4:3 | 1152*864 | 2304*1728 |
| 3:4 | 864*1152 | 1728*2304 |
| 3:2 | 1248*832 | 2496*1664 |
| 2:3 | 832*1248 | 1664*2496 |
这里的 1K / 2K 只是面积档的叫法，不是一个可传的参数——上游没有
image_size，档位由它按输出面积自己算。
⚠️ 判据是面积，不是最长边：2048*512 面积只有 1,048,576，上游按 1K 算。
ninteger默认 1出几张（1–6）。按张计费，预扣也按张乘。
seedinteger随机种子，用于复现结果。未提供时随机生成。
negative_promptstring不想要什么。自由文本。
prompt_extendboolean默认 true是否让模型在生成前先把提示词改写扩写一遍。
prompt_extend_mode"direct" | "agent"默认 "direct"改写用哪种方式，只在 prompt_extend 开着时有意义。
- direct —— 直接扩写，文生图与图生图都可用；
- agent —— 智能扩写，只支持文生图。带了参考图时这一项当场报错，
而不是被静默换成 direct——那样你以为开的是 agent，出来的却不是。
enable_thinkingboolean默认 true出图之前先想一轮。关掉更快，开着构图通常更稳。
watermarkboolean默认 false是否在输出图右下角打上「AI 生成」水印。
webhook_urlstring任务到终态时往这里 POST 一份结果，形状与 POST /v1/tasks 那条的回调完全一致
（{event, sent_at, task} 信封 + Amux-Signature 签名 + 退避重试）。
⚠️ 这个字段是本站加的，官方没有。 百炼的异步任务确实有回调，但它是在阿里云
控制台用 EventBridge 配事件规则——请求里传不了地址。
写在这里（与 input / parameters 平级）或写进 parameters 里都收；
两处都写且不一样时报错，不替你挑一个。
只收 https，且不能指向内网——我们是从服务端发过去的。地址在提交这一刻
就校验，写错了当场报错，而不是等任务跑完才发现回调从来没来。
响应
200response任务已受理。拿 output.task_id 去轮询。
400response参数不合法。取值超出这个模型的范围时，报错里会写明可接受的取值。
402response可用余额不足以覆盖这次的预扣。
503response当前没有可用的供应商能服务这个模型。
两处照着官方来的地方
- 返回 200 而不是 202。 阿里云百炼官方那条就是 200，按官方形状实现的 客户端会把 202 判成失败；
X-DashScope-Async: enable收下即忽略。 这条路径在本站恒为异步， 带不带都一样——照官方写法发过来的请求原样能用。
一处官方没有的地方
webhook_url 是本站加的。百炼的异步任务确实有回调，但它是在阿里云控制台
用 EventBridge 配事件规则，请求里传不了地址。不加的话，走这条端点的调用方
只能轮询，而同一个任务走站内统一入口就能收到推送。
写在顶层（与 input / parameters 平级）或写进 parameters 里都收；
两处都写且不一样时报错，不替你挑一个。
两条取回方式
| 取回端点 | 响应形状 | 适用场景 |
|---|---|---|
GET /api/v1/tasks/{id} | 百炼原生 | DashScope 客户端会自行拼接该地址 |
GET /v1/tasks/{id} | 站内统一 | 新接入建议使用，附带 usage 与 cost |
两者查的是同一个任务，不是两套存储。百炼形状里没有承载用量与费用的字段， 所以那两项只在站内统一端点上给。
这个模型的三条调用方式
| 地址 | 交付 | 什么时候用 | |
|---|---|---|---|
| 官方同步 | POST …/multimodal-generation/generation | 挂着等，35–70 秒 | 已有 DashScope 代码，且能接受长连接 |
| 官方异步 | POST …/image-generation/generation | 拿 task_id | 已有 DashScope 代码，不想守着连接 |
| Amux Tasks | POST /v1/tasks | 拿 id + 可选回调 | 新接入建议这条，与厂商无关 |
三条走的是同一套路由、定价、预扣与任务记录，差别只在请求体形状与交付方式。
计费
按张计价，不按 token——这个模型的三个 token 字段恒为 0。计费项是 输入图（参考图）与输出图两项，提示词不计价。
⚠️ 单价不写在这里。 价格会调整，而这份文档是跟着代码走的：改一次价要记得 回来改四份 spec 加二十页，漏一处就是文档上标着一个已经不收的价——那比不写更坏。 当前单价见模型详情页与定价页，它们直接读价格表。
提交时按上界预扣，完成后按实际用量结算并退还差额；可用余额不足以覆盖预扣时 返回 402。失败与过期不计费，预扣已释放。
输出不分档
qwen/qwen-image-3.0 的输出图不按分辨率分价。上游内部仍分 1K / 2K，但在这个模型上两档
同价，因此 size 只影响画面，不影响这一项的费用。
错误
错误体形状与阿里云百炼一致，type 取值与重试语义见错误与重试。
curl https://gateway.amux.ai/api/v1/services/aigc/image-generation/generation \
-H "Authorization: Bearer $AMUX_API_KEY" \
-d '{
"model": "qwen-image-3.0",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "一只戴着墨镜的柴犬坐在冲浪板上，阳光明媚的海滩"
}
]
}
]
},
"parameters": {
"size": "1024*1024"
}
}'{
"output": {
"task_id": "task_01M1CG35C16CJ790D00BV1RBVM",
"task_status": "PENDING",
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"type": "image",
"image": "https://cdn.amux.ai/gen/20260907/task_01M1CG35C16CJ790D00BV1RBVM-0.png"
}
]
}
}
],
"code": "<string>",
"message": "<string>"
},
"request_id": "task_01M1CG35C16CJ790D00BV1RBVM"
}