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
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 billingUse 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
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:
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
auto | Default. Uses provider-native async when the selected route supports it; otherwise uses platform-managed async. |
provider | Requires a route with native async support. |
platform | Runs 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.
queued | No | Persisted and waiting for dispatch. |
submitting | No | Being submitted to the selected provider. |
in_progress | No | Generation or provider polling is in progress. |
cancel_requested | No | Cancellation was requested; the provider may still finish. |
completed | Yes | result.data contains the generated images. |
failed | Yes | Generation failed; inspect error. |
cancelled | Yes | Cancelled before provider work began. |
expired | Yes | Exceeded the server-side task lifetime. |
needs_attention | Yes | Submission 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.
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":"..."}}.
400 | Invalid model or execution mode, unsupported streaming fields, invalid idempotency key, or a non-integer limit. |
401 | Missing or invalid inference API key. |
404 | The task does not exist or is not owned by the caller. |
409 | The idempotency key was already used with a different request. |
413 | The persisted task request exceeds the configured size limit. |
500 | Unexpected server failure. Retry task creation only with the original idempotency key. |