Async Image Generation

Token360 Async Image Generation creates a durable task and lets your application poll for the result without holding the original HTTP connection open.

The existing POST /v1/images/generations endpoint remains synchronous. Async image generation uses the separate /v1/async/images/tasks namespace.

Workflow

text
11. POST /v1/async/images/tasks                 → task id (HTTP 202)
22. GET  /v1/async/images/tasks/{task_id}       → poll until terminal
33. POST /v1/async/images/tasks/{task_id}/cancel → optional, best effort
44. GET  /v1/billing/requests/image-task:{task_id}?type=image → reconcile billing

Use GET /v1/async/images/tasks?limit=20 to list your newest tasks.

All task endpoints require an inference API key in Authorization: Bearer .... They return the public V1 JSON object directly and include Cache-Control: no-store.

Create

Shell
1curl -X POST https://api.token360.ai/v1/async/images/tasks \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -H "Idempotency-Key: image-order-20260921-0001" \
5  -d '{
6    "model": "gpt-image-2.5-flare",
7    "prompt": "A watercolor lighthouse at sunrise",
8    "size": "1024x1024",
9    "n": 1,
10    "execution": "auto"
11  }'

The response is a task object with HTTP 202 Accepted:

JSON
1{
2  "id": "img_task_...",
3  "object": "image_generation.task",
4  "model": "gpt-image-2.5-flare",
5  "status": "queued",
6  "execution": "auto",
7  "version": 1,
8  "created_at": "2026-09-21T12:00:00Z",
9  "updated_at": "2026-09-21T12:00:00Z"
10}

stream must be false or omitted. partial_images is not supported.

Execution modes

autoDefault. Uses provider-native async when the selected route supports it; otherwise uses platform-managed async.
providerRequires a route with native async support.
platformRuns the normal provider request in Token360's durable background worker.

The task API is shared by GPT-image, Nano Banana, and other image model families. Native async availability varies by model and route.

Idempotency

Send an Idempotency-Key (maximum 200 characters) on every create request.

  • Same key and same request: returns the original task with HTTP 202, including after completion.
  • Same key and different request: returns HTTP 409.
  • No key: each accepted request creates a new task and may create a separate provider charge.

If the create connection times out, retry with the same key. Do not generate a new key for the retry.

Polling and statuses

Poll every 2-5 seconds initially, then use exponential backoff with jitter up to about 30 seconds. Webhooks are not currently available for async image tasks.

queuedNoPersisted and waiting for dispatch.
submittingNoBeing submitted to the selected provider.
in_progressNoGeneration or provider polling is in progress.
cancel_requestedNoCancellation was requested; the provider may still finish.
completedYesresult.data contains the generated images.
failedYesGeneration failed; inspect error.
cancelledYesCancelled before provider work began.
expiredYesExceeded the server-side task lifetime.
needs_attentionYesSubmission outcome is ambiguous; automatic resubmission was suppressed.

For needs_attention, do not retry with a new idempotency key. Keep the task ID and contact Token360 support: a new provider submission could create a duplicate image and duplicate charge.

Billing

Completed usage is correlated as image-task:<task_id>. Billing ingestion is asynchronous, so the billing record may appear shortly after task completion.

Shell
1curl 'https://api.token360.ai/v1/billing/requests/image-task:img_task_...?type=image' \
2  -H "Authorization: Bearer sk-your-api-key"

Errors

Errors use the public V1 error shape: {"error":{"message":"...","type":"...","code":"..."}}.

400Invalid model or execution mode, unsupported streaming fields, invalid idempotency key, or a non-integer limit.
401Missing or invalid inference API key.
404The task does not exist or is not owned by the caller.
409The idempotency key was already used with a different request.
413The persisted task request exceeds the configured size limit.
500Unexpected server failure. Retry task creation only with the original idempotency key.
Was this page helpful?
Async Image Generation · Token360