Create task
最近更新：2026年9月7日
用 qwen/qwen-image-3.0-pro 向站内统一入口提交异步任务。请求体平铺，参考图走文件上传。
向 /v1/tasks 提交 qwen/qwen-image-3.0-pro 的生成任务：立即返回 id，图在后台生成。
这条端点不分生成和编辑——不带 image 就是生成，带了就是图生图。
下面的参数表是 multipart/form-data 形态，它是超集。不带参考图时，
同样这些字段也可以用 JSON 发。
https://gateway.amux.ai/v1/tasks鉴权
headerAuthorizationstring必填Bearer <你的 Amux 密钥> 站内 API Key。
请求
multipart/form-datamodelstring必填站内模型 ID，可带 :供应商 后缀锁定供应商。
promptstring必填想要什么。带了参考图时它描述的是「想怎么改」。
imagearray<string>参考图，可选——不给就是纯生成，给了就是图生图。最多 3 张。
⚠️ 这条端点上参考图只能作为文件上传（multipart/form-data）。
media 那个字段是给视频模型的角色素材用的，图像模型上传了会当场报错——
静默忽略的话你会付一张纯生成的钱，而参考图从头到尾没参与。
image 与 image[] 两种字段名均支持。
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，且不能指向内网——我们是从服务端发过去的。地址在提交这一刻
就校验，写错了当场报错，而不是等任务跑完才发现回调从来没来。
响应
202response任务已建立。拿 id 去轮询，或等回调。
400response参数不合法。取值超出这个模型的范围时，报错里会写明可接受的取值。
402response可用余额不足以覆盖这次的预扣。
503response当前没有可用的供应商能服务这个模型。
⚠️ 参考图只能作为文件上传
这条端点上参考图走 image 字段（image[] 同样收），最多 3 张。
media 那个字段是给视频模型的角色素材（首尾帧、参考视频…）用的，
图像模型上传了会当场报错。它不会被静默忽略——静默忽略的后果是你付了
一张纯生成的钱，而参考图从头到尾没参与，出来的图和你想要的没关系。
拿结果的三种方式
| 怎么用 | 什么时候合适 | |
|---|---|---|
| 轮询 | GET /v1/tasks/{id} | 最简单，建议间隔 5–10 秒 |
| 回调 | 提交时带 webhook_url | 不想守着连接 |
| 就地等 | 提交时带 Prefer: wait=60 | 想同步拿到，又不想自己轮询 |
任务生命周期、回调签名与验签示例、幂等键 —— 这些所有模型都一样， 见创建任务。
这个模型的三条调用方式
| 地址 | 交付 | 什么时候用 | |
|---|---|---|---|
| 官方同步 | 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。失败与过期不计费，预扣已释放。
输出按分辨率分档
上游按输出图的像素面积分 1K / 2K 两档，而官方没有公布那条界线。 我们不猜：结算读上游报回来的档位，那是精确的。
提交时要预扣，那一刻还没有上游的回答，所以按上界冻结，落到低档时按低档 结算并退还差额。代价只是多冻一点；好处是这条界线哪天变了，账单不会跟着错。
错误
错误体形状与 OpenAI 一致，type 取值与重试语义见错误与重试。
curl https://gateway.amux.ai/v1/tasks \
-H "Authorization: Bearer $AMUX_API_KEY" \
-F "model=qwen/qwen-image-3.0-pro" \
-F "prompt=把这只狗换成一只戴红围巾的橘猫" \
-F "image=@/path/to/image.png" \
-F "size=1024*1024" \
-F "webhook_url=https://hooks.example.com/amux"{
"id": "task_01M1CG35C16CJ790D00BV1RBVM",
"status": "queued",
"model": "qwen/qwen-image-3.0-pro",
"created_at": "2026-09-07T11:25:44Z",
"output": {
"images": [
{
"index": 0,
"url": "https://cdn.amux.ai/gen/20260907/task_01M1CG35C16CJ790D00BV1RBVM-0.png"
}
],
"videos": [
{}
]
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"total_tokens": 0
},
"cost": "0.043",
"error": {
"message": "<string>",
"code": "<string>"
}
}