Async Image Generation

Use this when image generation is slow and you do not want the client to block. Only gpt-image-* models are supported (for example gpt-image-2).

Synchronous generation remains:

POST /v1/images/generations

API

Submit

POST /v1/images/tasks
Authorization: Bearer sk-YOUR_TOKEN
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "a small red cube on a white background",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

Immediate response:

{
  "id": "task_xxx",
  "object": "image.task",
  "status": "queued",
  "created": 1780000000,
  "model": "gpt-image-2"
}

Poll

GET /v1/images/tasks/{task_id}
Authorization: Bearer sk-YOUR_TOKEN

Statuses: queued / in_progress / completed / failed.

On success, data follows the OpenAI image shape (url or b64_json).

Sync vs async

	Sync `/v1/images/generations`	Async `/v1/images/tasks`
Client wait	Until the image is ready	Return `task_id`, then poll
Models	Channel-dependent	`gpt-image-*` only
Best for	MeiGen / Codex OpenAI sync mode	Self-hosted MCP / scripts

Cursor MCP

Tools:

generate_image: submit async task, return task_id immediately
check_image_task: poll status; save file when done

See MCP Image for Cursor config.

Limits

Default task timeout ~10 minutes (IMAGE_ASYNC_TIMEOUT_SEC)
Default concurrency 2 (IMAGE_ASYNC_MAX_CONCURRENT)
quality / style / user are accepted and ignored when unsupported
Non-gpt-image-* models return HTTP 400