Create image task

Takes the same request body as the synchronous endpoint but returns a task_id immediately, with the image produced in the background.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> An Amux key created in the console. If you lose it, you can view it again on the keys page.

Request

application/json

modelstringRequired

The Amux model ID. Today this endpoint serves alibaba/qwen-image-3.0 and alibaba/qwen-image-3.0-pro.

inputobjectRequired

Chat-shaped input. The prompt and the reference images both live here, not in two separate fields.

›inputobject

messagesarray<object>

One user message is enough.

›messagesarray<object>

rolestring

Always user.

contentarray<object>

The prompt and reference images, mixed. At least one text item is required.

›contentarray<object>

textstring

The prompt. Multiple items are joined with newlines, in order.

imagestring

A reference image: a public https URL, or data:image/...;base64,.... Up to 3.

parametersobject

Generation parameters, all optional.

›parametersobject

sizestring

width*height. The area must be between 262144 (512x512) and 6553600 (2560x2560), with an aspect ratio between 1:8 and 8:1. The 1024x1024 spelling is accepted too and normalised before it reaches the upstream.

nintegerDefault 1

How many images to produce, 1-6.

seedinteger

Random seed, 0-2147483647.

negative_promptstring

Negative prompt: what should stay out of the picture.

prompt_extendboolean

Whether the model rewrites and expands the prompt first. On by default upstream.

watermarkbooleanDefault false

Whether to stamp a watermark on the output.

webhook_urlstring

POSTs the result here once the task reaches a terminal state. This field is ours, not the vendor's (Model Studio callbacks are configured as EventBridge rules in the console). The payload matches the callback on POST /v1/tasks exactly.

Response

200response

Accepted. Take output.task_id to GET /api/v1/tasks/{id} and poll.

400response

Invalid parameters: the size area or aspect ratio is out of range, more than 3 reference images, or a missing prompt.

402response

Available balance does not cover the reservation.

503response

No provider can currently serve this model.

Supported models#

The same two as the synchronous endpoint:

Three 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;
• Retrieval goes through GET /api/v1/tasks/{id} — the same endpoint as video, rendered into two shapes according to the task's modality. It is not a second address.

⚠️ Parameters are still validated at submission#

Upstream's async endpoint does not validate its input: a malformed size is accepted and the task fails a dozen seconds later. We reject before the task row exists, and the error says which parameter and what range is acceptable.

This is one place where we are stricter than upstream, and what it saves you is exactly "waiting a dozen seconds to learn you mistyped one character".

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.

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.

Retrieval#

task_id is an Amux task ID, not an upstream one. Both retrieval endpoints take it and return two renderings of the same task:

The DashScope shape has no fields for usage or cost, so those two only appear on the Amux endpoint.

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": "alibaba/qwen-image-3.0",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "text": "A red paper boat drifting down a rain gutter"
            }
          ]
        }
      ]
    },
    "parameters": {
      "size": "1024*1024"
    }
  }'

{
  "output": {
    "task_id": "<string>",
    "task_status": "<string>"
  },
  "request_id": "<string>"
}