Async Image Tasks

Async image tasks are designed for long-running production image generation. The client submits a task, receives a task ID, and then reads the result later through polling or SSE.

The same /v1/images/tasks endpoint dispatches by model. One task accepts one model, one prompt, and n images.

Async image tasks require an image API key. The key must be bound to an image batch group. See Create API Keys before integrating this endpoint.

Currently supported:

Model	Image batch group model platform	Upstream protocol
gpt-image-*, image2	OpenAI	OpenAI Images API
gemini-2.5-flash-image	Gemini	Gemini native generateContent
gemini-3.1-flash-image	Gemini	Gemini native generateContent

For Gemini image generation, use the official model names. Do not use aliases such as banana or nano-banana.

Submit a Task

Interface details:

Item	Value
Method	POST
Path	/v1/images/tasks
Content-Type	application/json
Success status	202
Authentication	Authorization: Bearer YOUR_API_KEY
Key requirement	Use an image API key bound to an image batch group; the requested model must exist in that image batch group

Request parameters:

Parameter	Type	Required	Description
model	string	No	Image model. Defaults to gpt-image-2. image2 is normalized to gpt-image-2; Gemini uses official model names.
prompt	string	Yes	Image prompt. Must be a non-empty string.
size	string	No	Output size. OpenAI forwards it to the Images API; Gemini uses it to infer imageConfig.imageSize and common aspect ratios.
n	integer	No	Number of images. Defaults to 1, must be greater than 0, and is limited by server configuration.
stream	boolean	No	Must be false or omitted; async image tasks do not support streaming upstream responses.
response_format	string	No	OpenAI only. Defaults to b64_json when omitted.
quality	string	No	Native OpenAI image parameter, forwarded when supported upstream.
background	string	No	Native OpenAI image parameter, forwarded when supported upstream.
output_format	string	No	Native OpenAI image parameter, forwarded when supported upstream.
moderation	string	No	Native OpenAI image parameter, forwarded when supported upstream.

Gemini optional parameters:

Parameter	Type	Description
image_size / imageSize	string	Image size tier. Supports 1K, 2K, 4K; common dimension strings are normalized by the server.
aspect_ratio / aspectRatio	string	Supports 1:1, 16:9, 9:16, 4:3, 3:4.
temperature, top_p / topP, top_k / topK, seed, max_output_tokens / maxOutputTokens	number	Written into Gemini generationConfig.
generation_config / generationConfig	object	Forwarded and merged into Gemini generationConfig. The server ensures image output modality is included.
image_config / imageConfig	object	Forwarded and merged into generationConfig.imageConfig.
system_instruction / systemInstruction	string/object	Optional Gemini system instruction.
safety_settings / safetySettings	array	Optional Gemini safety settings.

Unsupported request formats:

Format	Notes
multipart/form-data	Async tasks currently support JSON generation requests only.
Image edits	Async tasks currently map to /v1/images/generations only.
Multiple prompts	One task accepts only one prompt.
General API keys	General-group keys cannot submit async image tasks.

OpenAI request example:

curl https://llmapi.site/v1/images/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "image2",
    "prompt": "a clean studio product photo of a matte black water bottle",
    "size": "1024x1024",
    "n": 2
  }'

Response example:

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "queued",
  "created_at": "2026-05-14T05:13:00Z",
  "model": "gpt-image-2",
  "n": 2,
  "size": "1024x1024",
  "estimated_cost": 0.12,
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

Gemini request example:

curl https://llmapi.site/v1/images/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "a clean studio product photo of a matte black water bottle",
    "image_size": "1K",
    "aspect_ratio": "1:1",
    "n": 1
  }'

Retrieve a Task

Interface details:

Item	Value
Method	GET
Path	/v1/images/tasks/{task_id}
Authentication	Authorization: Bearer YOUR_API_KEY
Permission	The task must have been created by the current API key

Path parameters:

Parameter	Type	Required	Description
task_id	string	Yes	Task ID returned by the submit endpoint.

Request example:

curl https://llmapi.site/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da \
  -H 'Authorization: Bearer YOUR_API_KEY'

Status values:

Status	Description
queued	Task is queued and waiting for a worker.
running	Task is running.
succeeded	Task completed and result contains image data.
failed	Task failed and error contains the reason; no charge is applied and the reservation is released.
timeout	Task timed out; no charge is applied, the reservation is released, and the server does not retry automatically.
canceled	Task was canceled; no charge is applied and the reservation is released.

Successful task response:

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "succeeded",
  "created_at": "2026-05-14T05:13:00Z",
  "started_at": "2026-05-14T05:13:02Z",
  "finished_at": "2026-05-14T05:13:42Z",
  "model": "gpt-image-2",
  "n": 2,
  "size": "1024x1024",
  "estimated_cost": 0.12,
  "actual_cost": 0.12,
  "result": {
    "data": [
      {
        "index": 0,
        "url": "https://oss.example.com/images/task-0.png?signature=...",
        "content_type": "image/png",
        "size_bytes": 1048576,
        "expires_at": "2026-05-21T05:13:42Z"
      }
    ]
  },
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

Gemini tasks use the same response shape. model preserves the official Gemini model name:

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "queued",
  "created_at": "2026-05-14T05:13:00Z",
  "model": "gemini-2.5-flash-image",
  "n": 1,
  "size": "1K",
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

Failed task response:

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "failed",
  "model": "gpt-image-2",
  "n": 1,
  "error": {
    "code": "upstream_error",
    "message": "image generation failed"
  }
}

Cancel a Task

Interface details:

Item	Value
Method	POST
Path	/v1/images/tasks/{task_id}/cancel
Authentication	Authorization: Bearer YOUR_API_KEY
Permission	The task must have been created by the current API key
Cancellable status	queued

Request example:

curl -X POST https://llmapi.site/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY'

Notes:

• Only queued tasks can be canceled.
• A running task may already be executing upstream and is not interrupted by this endpoint.
• Canceling a terminal task returns a conflict error.

Billing Behavior

Stage	Behavior
Before submission	Validates balance, API key status, group permission, and content moderation.
Enqueue	Reserves estimated balance from model, size, and image count.
Success	Settles actual cost from the generated result. If actual cost is lower than the reservation, the difference is returned; if it is higher, the difference is deducted and the user balance may become negative.
Usage record	Written after a task is successfully settled. A usage-record write failure does not change the task's successful status.
Failure, timeout, or cancel	No charge is applied and the full reserved balance is released.

Failed and timed-out tasks are not retried automatically. Submit a new task if the caller wants to retry.

Async image tasks currently do not support regular subscription-billing groups. Use an image API key bound to an image batch group. Regular subscription groups receive IMAGE_TASK_SUBSCRIPTION_UNSUPPORTED.