Create async image task

POST/v1/async/images/tasks

Create a durable asynchronous image-generation task. The endpoint returns HTTP 202 immediately; poll Retrieve async image task for the result.

The synchronous POST /v1/images/generations endpoint is unchanged. See Async Image Generation for the complete workflow.

Authentication

Authorization Bearer

API key as bearer token in the Authorization header.

Headers

Idempotency-Keystring

Recommended retry key, scoped to the authenticated owner. Maximum 200 characters.

Request Body

modelstringrequired

Public image model name.

promptstring

Image prompt. Requirements depend on the selected model.

executionenum<string>

Execution preference.

ninteger

Number of images.

sizestring

Requested image size, for example 1024x1024.

qualitystring

Requested image quality when supported by the model.

output_formatstring

Requested output format when supported by the model.

streamboolean

Must be false or omitted.

partial_imagesinteger

Not supported; omit this field.

Additional model-specific image fields accepted by the synchronous image API may be supplied.

Response

idstring

Task ID with img_task_ prefix.

objectstring

image_generation.task

modelstring

Public model name.

statusstring

Initial status, normally queued.

executionenum<string>

Requested preference, then resolved execution mode when available.

versioninteger

Monotonically increasing task version.

resultobject

Image response when an idempotent replay returns an already completed task.

errorobject

Error details when an idempotent replay returns a failed or needs_attention task.

error.messagestring

Human-readable error message.

error.codestring

Machine-readable error code.

error.typestring

Error category when returned.

error.stagestring

Processing stage where the error occurred.

error.upstream_http_statusinteger

Provider HTTP status when the error came from upstream.

error.upstream_messagestring

Provider error message when available.

created_atstring

ISO-8601 creation time.

updated_atstring

ISO-8601 last update time.

completed_atstring

ISO-8601 completion time when terminal.

Request

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    "execution": "auto"
10  }'

Response

JSON
1{
2  "id": "img_task_01abc",
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}
Was this page helpful?
Create async image task · Token360