Create task

Submit a x-ai/grok-imagine-image-quality task to /v1/tasks: you get an id immediately and generation runs in the background.

This endpoint does not separate generation from editing — without image it generates, with image it edits. The parameters are identical, so there is only this one page.

The parameter table below shows the multipart/form-data form, which is a superset. Without reference images the same fields can be sent as JSON.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

multipart/form-data

modelstringRequired

Amux model ID. Append :provider to pin a specific provider.

promptstringRequired

What you want. With reference images it describes how to change them.

imagearray<string>

Reference images, optional — without them this is text-to-image, with them it is an edit.

Both image and image[] are accepted.

At most 3, each up to 25 MiB, and at most 48 MB once encoded.

nintegerDefault 1

How many images to produce (1–10, default 1). Billed per image; the hold scales with it too.

aspect_ratio"1:1" | "4:3" | "3:4" | "3:2" | "2:3" | "16:9" | "9:16" | "2:1" | "1:2" | "21:9" | "5:2" | "19.5:9" | "9:19.5" | "20:9" | "9:20" | "auto"Default "1:1"

Output aspect ratio, 1:1 by default. Identical to what the upstream model accepts — sixteen values:

1:1 4:3 3:4 3:2 2:3 16:9 9:16 2:1 1:2 21:9 5:2 19.5:9 9:19.5 20:9 9:20 auto

The ratio changes the shape of the output only and does not change the pricing tier — all sixteen were measured at the same price.

A ratio outside this set is dropped and explained in amux.notes.

image_size"1K" | "2K"Default "1K"

Resolution tier. 1K (default) or 2K. 4K is not supported.

It also determines the output format: 1K produces JPEG, 2K produces PNG.

Treat the extension of the returned URL as authoritative.

When omitted, 1K is sent explicitly — the tier is always written into the upstream

request rather than left to the upstream default.

moderation"auto" | "low" | "high"Default "auto"

Moderation strength. auto (default), low or high.

userstring

End-user identifier for abuse tracking. Omit the field entirely if you do not need it.

webhook_urlstring

Where to POST the result once the task reaches a terminal state. HTTPS only, and it must not point at a private network.

Response

200response

Already terminal (Prefer: wait waited it out), or this is a replay of the same idempotency key.

202response

Task accepted and the hold is in place. Use id to retrieve the result.

400response

Invalid request, including stream and partial_images — this endpoint is asynchronous, and these two models do not support streaming at all.

402response

Available balance cannot cover the upper-bound hold.

503response

The in-flight queue is full; retry later (the response carries Retry-After).

Three ways to get the result#

Task lifecycle, webhook signing and verification, and idempotency keys are the same for every model — see Create task.

How it differs from the compatible endpoints#

On the synchronous path a timeout anywhere — reverse proxy, gateway, client default — loses you the image after the money is spent. Prefer this endpoint for slow work.

Reference images#

The field name may be image or image[] (official SDKs send the former for a single image and the latter for several). Reference images are optional — without them this is text-to-image, with them it is an edit.

Three limits; exceeding any of them returns 400 and never silently drops an image:

1. At most 3 — a hard upstream limit for this model;
2. 25 MiB per image;
3. 48 MB total once encoded.

Reference images are billed per image, independently of n: producing two images from one reference image still counts as one reference image.

⚠️ Masks are not supported (mask) — the upstream edit endpoint has no such concept. The field is dropped and explained in amux.notes.

⚠️ Reference images must be uploaded as files; URLs are not supported.

Dimensions and format#

Dimensions are expressed with two parameters: aspect_ratio and image_size. This model does not accept size (an exact pixel string); it is dropped and explained in amux.notes.

Other ratios scale within the same tier; the full list is in the next section. 4K is not supported.

The ratio changes the shape of the output only and does not change the pricing tier; the resolution tier does.

⚠️ The output format follows image_size and cannot be chosen — neither output_format nor output_compression has any effect on this model. Treat the extension of the returned URL as authoritative.

Aspect ratio#

Output aspect ratio, 1:1 by default. Identical to what the upstream model accepts — sixteen values:

The ratio changes the shape of the output only and does not change the pricing tier — all sixteen were measured at the same price.

A ratio outside this set is dropped and explained in amux.notes; we will not guess one for you.

quality is not supported#

The upstream model accepts this parameter, but on this model it changes neither the output resolution nor the pricing tier. It is therefore marked unsupported here: it is dropped and explained in amux.notes.

The pricing tier for this model depends on image_size alone.

Unsupported parameters#

Passing them is not an error: they are dropped and explained in amux.notes. If the result is not what you expected, check notes first.

⚠️ style is the exception: dropping it produces no amux.notes entry. Every other parameter above is marked unsupported in this model's parameter matrix, so there is something to report; style is not a parameter Amux models at all, so it is discarded while the request is parsed. In other words, sending style gives you no feedback whatsoever — write your code as if it did not exist.

Errors#

The error body matches OpenAI's shape. See Errors and retries for the type values and retry semantics.

curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=x-ai/grok-imagine-image-quality" \
  -F "prompt=Make the fox wear a red scarf" \
  -F "image=@/path/to/image.png" \
  -F "image_size=1K" \
  -F "webhook_url=https://hooks.example.com/amux"

{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "x-ai/grok-imagine-image-quality",
  "created_at": "<string>",
  "output": {
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "output_images": 0,
    "input_images": 0
  },
  "cost": "0.0500",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}