Documentation
API Reference / Image Generation API
Interactive API
API Reference · Image Generation API

Image Generation API

Asynchronous image generation with gpt-image-2 - create, poll, retrieve. Base64-encoded results, one-time delivery within a 30-minute TTL window.

Overview

Image generation is an asynchronous task: POST /images/generations/async returns a task ID immediately, then poll GET /images/generations/{id} until status becomes completed, at which point the response contains b64_json for each generated image.

Supported model: gpt-image-2. Use GET /images/models for the live list. Full schema and constraints are available in the interactive API explorer.

  • GET https://api.alltoken.ai/v1/images/models - list available image models
  • POST https://api.alltoken.ai/v1/images/generations/async - create a generation task
  • GET https://api.alltoken.ai/v1/images/generations/{id} - poll task status

Result delivery is one-time: once the completed response is read, the server deletes the temporary file. Persist the b64_json client-side on first receipt. Tasks expire after 30 minutes.

List Image Models

GET
$GET https://api.alltoken.ai/v1/images/models

Returns all available image generation models in OpenAI-compatible format.

Response JSON
1{
2 "object": "list",
3 "data": [
4 { "id": "gpt-image-2", "object": "model", "owned_by": "openai" }
5 ]
6}

Create an Image Generation Task

POST
$POST https://api.alltoken.ai/v1/images/generations/async

Headers:

  • Authorization: Bearer <API_KEY> - required
  • Idempotency-Key: <uuid> - optional but recommended. Server dedupes within a short window; retries with the same key return the original task.
Request body JSON
1{
2 "model": "gpt-image-2",
3 "prompt": "A clean product photo of a glass teapot on a walnut table, soft natural light",
4 "size": "1024x1024",
5 "quality": "high",
6 "output_format": "png",
7 "background": "auto",
8 "moderation": "auto"
9}

Response (task created, status queued):

Response JSON
1{
2 "id": "igen_a7b68c38c4b7832ee386a13e",
3 "status": "queued",
4 "model": "gpt-image-2",
5 "created_at": "2026-05-12T08:00:00Z"
6}

Request Parameters

  • model (required) - Image model ID, currently gpt-image-2
  • prompt (required) - Text description of the desired image
  • size - Output dimensions: 1024x1024 / 1536x1024 / 1024x1536 / auto
  • quality - low / medium / high / auto; controls inference budget and per-image cost
  • output_format - png / jpeg / webp
  • background - auto / opaque
  • moderation - auto (default; recommended) / low (less restrictive; user accepts full content compliance responsibility)

Get Task Status

GET
$GET https://api.alltoken.ai/v1/images/generations/{id}

Returns task details. When status is completed, the data array carries each generated image as b64_json (base64-encoded PNG/JPEG/WebP per the requested output_format).

Response JSON (completed)
1{
2 "id": "igen_a7b68c38c4b7832ee386a13e",
3 "status": "completed",
4 "model": "gpt-image-2",
5 "created": 1778572818,
6 "completed_at": "2026-05-12T08:00:18Z",
7 "expires_at": "2026-05-12T08:30:18Z",
8 "size": "1024x1024",
9 "quality": "high",
10 "output_format": "png",
11 "data": [
12 {
13 "b64_json": "iVBORw0KGgo...",
14 "revised_prompt": "A clean studio product photo of a clear borosilicate glass teapot..."
15 }
16 ],
17 "usage": {
18 "input_tokens": 24,
19 "output_tokens": 1290,
20 "total_tokens": 1314
21 }
22}

One-time delivery: the temporary image file is deleted server-side after the first successful completed read. Persist b64_json immediately. Re-polling after delivery returns 410 image_already_retrieved.

Task Status Values

  • queued - Enqueued, waiting for GPU
  • processing - Model is generating
  • completed - Done; data[].b64_json available for one read
  • failed - Generation failed; details in error
  • cancelled - Cancelled before completion

Recommended polling interval: 1-3 seconds. Most tasks complete in 8-25 seconds; high-quality 1536x1024 jobs may take 30-60 seconds. Expired or already-retrieved results are returned as 410 errors.

Error Responses

  • 400 - Bad request, such as an empty prompt or invalid size
  • 401 - Invalid or missing API Key
  • 402 - Insufficient balance
  • 404 - Task ID not found
  • 409 - Duplicate Idempotency-Key for an already-active task, or another request is currently claiming the completed result
  • 410 - Task expired (30-minute TTL elapsed) or result was already retrieved
  • 429 - Rate limit exceeded; respect the Retry-After header