GPT-Image-2 Image Generation

• Asynchronous processing mode, returns task ID for subsequent queries
• OpenAI Images compatible protocol, supports text-to-image / image-to-image
• 15 image aspect ratios supported via the size field
• Output pixel tier controlled via resolution (1k / 2k / 4k)
• Up to 16 reference images, URL and base64 can be mixed
• Billed by resolution tier (1K / 2K / 4K)

POST /v1/images/generations

cURL

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

200

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

cURL

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

200

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

Authorizations

Authorization · string · required

All endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key management page to get your API Key

Include it in the request header:

Authorization: Bearer YOUR_API_KEY

Body

model · string · default: "gpt-image-2" · required

Image generation model name

Fixed to gpt-image-2

prompt · string · required

Text description for image generation

• Supports English and Chinese, detailed descriptions recommended
• Pre-submission content moderation / safety review — violations are rejected immediately

n · integer · default: "1"

Number of images to generate

Range: 1

Must be a pure number (e.g., 1), do not wrap in quotes

size · string · default: "1:1"

Image aspect ratio

Supported ratios, plus auto to let the server pick a suitable ratio automatically:

size	Type
auto	Automatic
1:1	Square
3:2	Landscape
2:3	Portrait
4:3	Landscape
3:4	Portrait
5:4	Landscape
4:5	Portrait
16:9	Landscape
9:16	Portrait
2:1	Landscape
1:2	Portrait
3:1	Landscape
1:3	Portrait
21:9	Landscape
9:21	Portrait

Pixel dimensions can also be passed directly, such as 1881x836 / 887x1774.

When size is set to auto, the default ratio is 1:1.

resolution · string · default: "1k"

Output resolution tier

Options: 1k / 2k / 4k

size × resolution → actual pixel mapping:

size	1k	2k	4k
1:1	1024×1024 / 1254×1254	2048×2048	2880×2880
3:2	1536×1024	2048×1360	3520×2336
2:3	1024×1536	1360×2048	2336×3520
4:3	1024×768	2048×1536	3312×2480
3:4	768×1024	1536×2048	2480×3312
5:4	1280×1024 / 1448×1086	2560×2048	3216×2576
4:5	1024×1280 / 1122×1402	2048×2560	2576×3216
16:9	1536×864 / 1672×941	2048×1152	3840×2160
9:16	864×1536 / 941×1672	1152×2048	2160×3840
2:1	2048×1024 / 1774×887	2688×1344	3840×1920
1:2	1024×2048 / 887×1774	1344×2688	1920×3840
3:1	1881×836 / 1536×512	3072×1024	3840×1280
1:3	887×1774 / 512×1536	1024×3072	1280×3840
21:9	2016×864 / 1915×821	2688×1152	3840×1648
9:21	864×2016 / 821×1915	1152×2688	1648×3840

4K supports the 15 ratios listed above; you can also pass the pixel dimensions from the table directly via size.

image_urls · array

Reference image array (OpenAI standard field). Switches to image-to-image mode when provided.

Show Details

• Up to 16 reference images, exceeding returns image_urls exceeds max 16
• Supports image URL (public stable link)
• Supports base64 data URI (e.g. data:image/png;base64,...)
• URL and base64 can be mixed in the same array, handled by the server
• Without size, output resolution = input image resolution; with size, output is forced to the specified ratio

Other OpenAI standard fields (response_format, quality, style) are not supported and will be ignored. Task results only return url — please download and convert to base64 yourself if needed.

official_fallback · boolean · default: "false"

Whether to fall back to the official channel

• false: Do not use (default)
• true: Use the official channel

Usage Examples

Text-to-image (minimal request)

{
  "model": "gpt-image-2",
  "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style"
}

Text-to-image (with ratio + 2K)

{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "resolution": "2k"
}

Text-to-image (4K output)

{
  "model": "gpt-image-2",
  "prompt": "An ancient castle under a starry sky",
  "size": "16:9",
  "resolution": "4k"
}

Image-to-image (reference = URL)

{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "https://example.com/photo.jpg"
  ]
}

Image-to-image (reference = base64)

{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

Image-to-image (multi-reference fusion, URL + base64 mixed)

{
  "model": "gpt-image-2",
  "prompt": "Fuse these two photos into a single poster",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

Response

code · integer

Response status code

data · array

Response data array

Show Properties

status · string

Task status

• submitted - Submitted

task_id · string

Unique task identifier, used for subsequent result queries

Querying Task Results

After successful submission, a task_id is returned. Poll the task status via GET /v1/tasks/{task_id}, see Task Query API for details.

Success Response Example

{
  "code": 200,
  "data": {
    "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
    "status": "completed",
    "progress": 100,
    "created": 1776748674,
    "completed": 1776748726,
    "actual_time": 52,
    "cost": 0.05279,
    "estimated_time": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_task_xxx_0.png"
          ],
          "expires_at": 1776835126
        }
      ]
    }
  }
}

Image access: data.result.images[0].url[0]

Task Status

Status	Meaning
submitted	Submitted
processing	Being processed upstream
completed	Success, result.images available
failed	Failed, check error.message

Polling Recommendations

• Initial query delay: Wait 10~20 seconds after submission before first query
• Query interval: 3~5 seconds recommended, avoid millisecond-level polling
• Timeout reference: A single image typically completes in 3060 seconds (observed actual_time 4453s)
• Batch query: To query multiple tasks at once, use POST /v1/tasks/batch with body {"task_ids": ["task_xxx", "task_yyy"]}

Notes

1. Asynchronous processing: Submission returns task_id, poll /v1/tasks/{task_id} to get the final image URL
2. Content moderation: prompt is reviewed first — violations are rejected with no billing
3. Result URL: The platform mirrors upstream temporary signed links to its own R2 object storage, returning a stable link that clients can access directly
4. URL validity: expires_at = completed + 24h in the response is a hint field, please download or mirror to your own CDN promptly
5. Ratio conflict: Use the size field for aspect ratio — avoid repeating it in prompt to prevent upstream ambiguity
6. Billing: Billed by resolution tier (1K / 2K / 4K), no charge on failure or moderation rejection
7. 4K supported ratios: All 15 ratios above support 4K; you can also pass the corresponding pixel dimensions directly via size
8. Task retention: task_id is retained in the database for several days by default (configured by TASK_RETENTION_DAYS) — expired queries return “task does not exist or has expired”