Create image task

Submit a qwen/qwen-image-3.0-pro generation task and get a task_id immediately while the image is produced in the background. The request body is identical to the synchronous endpoint; this one simply does not wait.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

application/json

modelstringRequired

The upstream model name. Write qwen-image-3.0-pro on this endpoint; the site ID qwen/qwen-image-3.0-pro is accepted too.

inputobjectRequired

The input. Prompt and reference images both live here, reusing the multimodal chat message shape.

›inputobject

messagesarray<object>Required

The messages. Generation needs exactly one user message.

›messagesarray<object>

rolestring

Always user.

contentarray<object>

Content items. Reference images first, prompt last, following the

official examples.

- {"image": "..."} — a reference image, 1 to 3. Takes a public https URL or

an inline data:image/png;base64,... value. Upstream limits: JPG / JPEG / PNG /

BMP / TIFF / WEBP / GIF, up to 10MB each, edges ideally 384–2048 pixels;

- {"text": "..."} — the prompt. Several are joined with newlines rather than

dropped.

Image-to-image simply puts another item before the prompt:

```json

"content": [

{ "image": "https://example.com/ref.png" },

{ "text": "turn the dog into a ginger cat" }

]

```

⚠️ Do not put image and text in the same item — follow the official

examples and use two.

›contentarray<object>

textstring

The prompt. Officially recommended to stay under 4,500 tokens.

parametersobject

Generation parameters, all optional. Anything you leave out keeps the upstream default; we do not fill them in for you.

›parametersobject

sizestring

The output size, written width*height (widthxheight is accepted too and

normalised to the upstream spelling).

Two hard constraints, 400 on the spot rather than a size we quietly picked

for you:

- the area width × height must be between **262,144 (512*512) and

6,553,600 (2560*2560)**;

- the aspect ratio must be between 1:8 and 8:1.

The playground offers presets across **common aspect ratios × two resolution

tiers — not a closed list**: any size satisfying the two constraints above is

accepted.

Ratio	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 and 2K here are just names for the area bands, not a parameter you can send —

upstream has no image_size and works the tier out from the output area itself.

⚠️ The rule is area, not the longest edge: 2048*512 is only 1,048,576

pixels and bills as 1K upstream.

nintegerDefault 1

How many images (1–6). Billed per image, and the reservation multiplies too.

seedinteger

The random seed, for reproducible results. Random when omitted.

negative_promptstring

What you do not want. Free text.

prompt_extendbooleanDefault true

Whether the model rewrites and expands the prompt before generating.

prompt_extend_mode"direct" | "agent"Default "direct"

How the rewrite works; only meaningful while prompt_extend is on.

- direct — a straight expansion, available for both text-to-image and

image-to-image;

- agent — the smarter rewrite, text-to-image only. Sending it together

with reference images is an error rather than a silent downgrade to

direct — the silent version leaves you thinking agent ran when it did not.

enable_thinkingbooleanDefault true

Let the model think before generating. Turning it off is faster; leaving it on usually gives steadier composition.

watermarkbooleanDefault false

Whether to stamp an "AI generated" watermark in the bottom-right corner.

webhook_urlstring

When the task reaches a terminal state we POST the result here, in exactly

the same shape as the POST /v1/tasks callback (a {event, sent_at, task}

envelope, an Amux-Signature header, and backoff retries).

⚠️ This field is ours; upstream has no equivalent. DashScope's async tasks do

have callbacks, but they are configured as EventBridge rules in the Alibaba Cloud

console — the address cannot travel in the request.

It is accepted both here (a sibling of input / parameters) **and inside

parameters**. Giving both with different values is an error rather than a

silent pick.

https only, and never a private address — we deliver from our servers. The

address is validated at submission, so a typo fails immediately instead of

after the task has run.

Response

200response

The task was accepted. Poll with output.task_id.

400response

A bad parameter. When a value is outside this model's range the error says what is acceptable.

402response

The available balance cannot cover this reservation.

503response

No provider can serve this model right now.

Two things that follow upstream exactly#

• It answers 200, not 202. Alibaba Model Studio's own endpoint answers 200, and clients written against the official shape read 202 as a failure;
• X-DashScope-Async: enable is accepted and ignored. This path is always asynchronous here, with or without the header, so requests written the official way work unchanged.

One thing upstream does not have#

webhook_url is ours. DashScope's async tasks do have callbacks, but they are configured as EventBridge rules in the Alibaba Cloud console — the address cannot travel in the request. Without it, callers on this endpoint could only poll, while the same task through the Amux entry point gets a push.

It is accepted at the top level (a sibling of input / parameters) and inside parameters. Giving both with different values is an error rather than a silent pick.

Two ways to retrieve#

Both read the same task, not two stores. The DashScope shape has no fields for usage or cost, so those two only appear on the Amux endpoint.

Three ways to call this model#

All three share one set of routing, pricing, reservation and task records; they differ only in request shape and delivery.

Pricing#

Billed per image, not per token — all three token fields are always 0 on this model. Two line items: input images (references) and output images; the prompt itself is not billed.

⚠️ Unit prices are deliberately not repeated here. Prices change, and this document ships with the code: every change would mean remembering to edit four specs and twenty pages, and one missed spot is a documented price we no longer charge — worse than not stating it. Current prices live on the model page and the pricing page, which read the price book directly.

We reserve an upper bound on submission, settle against actual usage and release the difference; a balance that cannot cover the reservation returns 402. Failures and expiry are not billed, and the reservation is already released.

Output is tiered by resolution#

Upstream splits output images into 1K and 2K tiers by pixel area, and the boundary is not published. We do not guess it — settlement reads the tier upstream reports back, which is exact.

The reservation happens before upstream has answered, so it freezes the upper bound and releases the difference when it lands on the lower tier. The cost is a slightly larger hold; the benefit is that our billing does not go wrong the day that boundary moves.

Errors#

Errors come back in Alibaba Model Studio's shape. The type values and their retry semantics are in Errors and retries.

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"
}