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.
https://gateway.amux.ai/v1/tasksAuthorization
headerAuthorizationstringRequiredBearer <your Amux AI key>
Request
multipart/form-datamodelstringRequiredModel identifier.
promptstringRequiredText 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.
sizestringOpenAI-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_urlstringPublic 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
202responseTask accepted and upper-bound funds reserved. Poll or await webhook delivery using the returned id.
400responseInvalid request parameters (including streaming parameters, which are unsupported on both /v1/tasks and this model).
402responseInsufficient available workspace balance to cover the upper-bound reservation.
503responseConcurrent 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 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>"
}
}