Amux AI

Create task

Last updated October 8, 2026

Submit asynchronous image generation tasks for google/gemini-nano-banana-2.1 and retrieve a task ID immediately.

Submit google/gemini-nano-banana-2.1 image requests to /v1/tasks for asynchronous execution. Returns a task id immediately without holding an open HTTP connection—suited to batch workloads and mobile or serverless clients.

Unified endpoint for generation and editing: omit image for text-to-image generation, or include image for reference-based editing using the same parameter set.

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

Authorization

header
AuthorizationstringRequired

Bearer <your Amux AI key>

Request

multipart/form-data
modelstringRequired

Model identifier.

promptstringRequired

Text prompt for generation or editing.

imagearray<string>

Optional reference image files (maximum 25 MB each). Omit for text-to-image generation; include for image-to-image editing. For per-model reference image limits, see the synchronous endpoint.

Both image and image[] field names are accepted.

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"

Output aspect ratio. Unsupported values are ignored, recorded in amux.notes, and replaced by the model default. Also accepts Gemini's nested forms generationConfig.imageConfig.aspectRatio and generationConfig.responseFormat.image.aspectRatio; top-level aspect_ratio takes precedence over nested forms, and imageConfig takes precedence over responseFormat.image (the same precedence applies to image_size).

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

Output resolution tier. Unsupported values follow the same fallback behavior as aspect_ratio.

sizestring

OpenAI-style pixel dimension string for callers migrating from OpenAI endpoints. Mapped to a supported aspect ratio and resolution tier for this model, with any lossy conversion recorded in amux.notes. Ignored when aspect_ratio or image_size is explicitly provided.

webhook_urlstring

Public HTTPS endpoint to receive the task completion callback ({event, sent_at, task} envelope signed with Amux-Signature and retried with exponential backoff), identical to POST /v1/tasks.

Must be a publicly routable HTTPS URL (private and loopback addresses are rejected); validated at submission time.

Response

202response

Task accepted and upper-bound funds reserved. Poll or await webhook delivery using the returned id.

400response

Invalid request parameters (including streaming parameters, which are unsupported on both /v1/tasks and this model).

402response

Insufficient available workspace balance to cover the upper-bound reservation.

503response

Concurrent task limit reached; retry after the interval indicated in Retry-After.

Submission and retrieval

Submission returns HTTP 202 with a queued task object. Poll the retrieve task endpoint by id until the task reaches a terminal state, or supply webhook_url at submission to receive a signed completion callback.

When status is succeeded, output.images[].url provides temporary URLs to the generated image files. Hosted files expire after the retention period and return 404 thereafter; download any artifacts required for long-term storage.

To wait inline for fast completions, include the Prefer: wait=60 request header: if the task finishes within the specified window, the terminal task object is returned directly; otherwise, standard asynchronous processing continues.

Parameters

Generation parameters and supported ranges match the synchronous endpoint: 14 aspect ratios and resolution tiers 1K · 2K · 4K.

As the unified task endpoint, top-level snake_case fields (aspect_ratio, image_size) are recommended. Gemini's nested forms (generationConfig.imageConfig and generationConfig.responseFormat.image) are also accepted; top-level fields take precedence over nested forms, and imageConfig takes precedence over responseFormat.image.

Billing

Billing matches synchronous calls. Failed and expired tasks incur no charges, and any funds reserved at submission are automatically released.

Errors

Error responses use the standard gateway error schema. See Errors and retries for error codes and retry guidance.

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