Amux

Create task

Last updated October 8, 2026

Submit a google/gemini-nano-banana-2.1 generation as an async task and get a task id immediately.

Queue a google/gemini-nano-banana-2.1 generation. The call returns a task id straight away, so nothing has to hold the connection open. Suited to batches, and to clients that may disconnect midway.

This endpoint does not distinguish generation from editing — without a reference image it generates, with one it edits. On the Gemini side these are the same endpoint to begin with, so the parameters are identical too.

POSThttps://gateway.amux.ai/v1/tasks

Authorization

header
AuthorizationstringRequired

Bearer <your Amux key>

Request

multipart/form-data
modelstringRequired

The Amux model ID.

promptstringRequired

What you want. With reference images it describes the change you want.

imagearray<string>

Reference images, optional — without them this generates, with them it edits.

25MB each; for how many this model takes see the

synchronous call.

Both image and image[] are accepted as the field name.

aspect_ratio"1:1" | "1:4" | "1:8" | "2:3" | "3:2" | "3:4" | "4:1" | "4:3" | "4:5" | "5:4" | "8:1" | "9:16" | "16:9" | "21:9"

Aspect ratio. A value this model does not accept is dropped and noted in amux.notes; the upstream then uses its own default rather than rejecting the request.

In addition to this field, the nested Gemini forms generationConfig.imageConfig.aspectRatio and generationConfig.responseFormat.image.aspectRatio are also accepted. Google's documentation has used each of the latter two in different versions; Amux supports both. When more than one form is supplied, this field takes precedence; between the two nested forms, imageConfig takes precedence. The same rule applies to image_size.

image_size"1K" | "2K" | "4K"

Resolution tier. Out-of-range values are handled the same way as aspect_ratio.

sizestring

An OpenAI-style pixel string, for callers migrating from OpenAI. It is folded into a ratio and a tier, narrowed to what this model accepts, and any loss is noted in amux.notes. If aspect_ratio or image_size is also given, those win and size is ignored.

webhook_urlstring

POSTs the result here once the task reaches a terminal state. The shape is

identical to the callback on POST /v1/tasks (the {event, sent_at, task}

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

This field is ours, not the vendor's. Model Studio async tasks do support

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

console -- the address cannot be passed per request. Without this field, callers

on this endpoint could only poll, while the same task submitted through the

unified endpoint gets pushed.

https only, and never a private address -- we send it from our servers. The

URL is validated at submit time, so a typo fails immediately rather than

after the task has run.

Response

202response

Accepted, and the hold has been placed. Use id to retrieve the result.

400response

Invalid request. This includes streaming fields — the endpoint is asynchronous, and this model does not support streaming either.

402response

The available balance does not cover the upper-bound hold.

503response

Too many tasks in flight; retry later (the response carries Retry-After).

Submitting and retrieving

Submission returns 202 and a task in the queued state. Poll it by id with the retrieval endpoint until the status reaches a terminal value.

On succeeded, output.images[].url is a directly accessible address. Stored artifacts are cleaned up, so download anything you need to keep.

To get the result synchronously, send Prefer: wait=60 with the submission: if the task finishes within that many seconds the terminal state is returned directly, otherwise it stays asynchronous.

Parameters

The generation parameters match the synchronous call and the accepted ranges are the same — 14 aspect ratios, resolutions 1K · 2K · 4K.

Tasks is the unified entry point; the request body should use this endpoint's field names (aspect_ratio / image_size).

The nested Gemini forms generationConfig.imageConfig and generationConfig.responseFormat.image are also accepted. Google's documentation has used each of them in different versions, and Amux supports both. When more than one form is supplied, this endpoint's fields take precedence; between the two nested forms, imageConfig takes precedence.

Billing

Identical to the synchronous call, billed by token. Failed and expired tasks are not charged — the hold placed at submission is released.

Errors

Errors use the unified in-house shape. See Errors and retries for values and retry semantics.

cURL
curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=google/gemini-nano-banana-2.1" \
  -F "prompt=<string>" \
  -F "image=@/path/to/image.png" \
  -F "aspect_ratio=1:1" \
  -F "image_size=1K" \
  -F "size=1024x1024" \
  -F "webhook_url=<string>"
{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "<string>",
  "created_at": "<string>",
  "output": {
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "cost": "0.0336",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}