Amux

Create image task

最近更新：2026年9月7日

按百炼原生形状提交 qwen/qwen-image-3.0-pro 的异步出图任务，立刻拿 task_id。

提交 qwen/qwen-image-3.0-pro 的出图任务，立刻返回 task_id，图在后台生成。 请求体与同步那条完全一样，只是这条不等。

POSThttps://gateway.amux.ai/api/v1/services/aigc/image-generation/generation

鉴权

header
Authorizationstring必填

Bearer <你的 Amux 密钥> 站内 API Key。

请求

application/json
modelstring必填

上游模型名。这条端点上写 qwen-image-3.0-pro；站内 ID qwen/qwen-image-3.0-pro 同样收。

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 之间。

站内在操练场里按常用比例 × 两档分辨率给了预设——但不限于这几个，

任何满足上面两条约束的尺寸都收：

比例1K2K
1:11024*10242048*2048
16:91280*7202560*1440
9:16720*12801440*2560
4:31152*8642304*1728
3:4864*11521728*2304
3:21248*8322496*1664
2:3832*12481664*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 TasksPOST /v1/tasks拿 id + 可选回调新接入建议这条，与厂商无关

三条走的是同一套路由、定价、预扣与任务记录，差别只在请求体形状与交付方式。

计费

按张计价，不按 token——这个模型的三个 token 字段恒为 0。计费项是 输入图（参考图）与输出图两项，提示词不计价。

⚠️ 单价不写在这里。 价格会调整，而这份文档是跟着代码走的：改一次价要记得 回来改四份 spec 加二十页，漏一处就是文档上标着一个已经不收的价——那比不写更坏。 当前单价见模型详情页与定价页，它们直接读价格表。

提交时按上界预扣，完成后按实际用量结算并退还差额；可用余额不足以覆盖预扣时 返回 402。失败与过期不计费，预扣已释放。

输出按分辨率分档

上游按输出图的像素面积分 1K / 2K 两档，而官方没有公布那条界线。 我们不猜：结算读上游报回来的档位，那是精确的。

提交时要预扣，那一刻还没有上游的回答，所以按上界冻结，落到低档时按低档 结算并退还差额。代价只是多冻一点；好处是这条界线哪天变了，账单不会跟着错。

错误

错误体形状与阿里云百炼一致，type 取值与重试语义见错误与重试。

cURL
curl https://gateway.amux.ai/api/v1/services/aigc/image-generation/generation \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "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"
}