GPT-Image-2.5 Image Generation

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.5-flare",
    "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

POST

images

generations

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.5-flare",
    "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

Model selection: gpt-image-2.5-flare is faster and works well for everyday high-quality images, batch generation, and rapid prototyping. gpt-image-2.5-sunburst prioritizes editing precision for production assets, advertising creatives, and detailed multi-turn editing. Both models use the same pricing.

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.5-flare",
    "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

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

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

Authentication

string

required

All endpoints use Bearer Token authentication. Get your key from the API Key page.

Authorization: Bearer YOUR_API_KEY

Choose a model

Model	Strength	Recommended use
`gpt-image-2.5-flare`	Default option with faster generation	Social content, product images, visual search, rapid prototypes, and batch generation
`gpt-image-2.5-sunburst`	Prioritizes editing precision	Production product images, advertising creatives, and detailed multi-turn editing

The two models have identical token usage and pricing for the same parameters. Select one based on the speed-versus-quality tradeoff. Compared with gpt-image-2, GPT-Image-2.5 adds the xhigh and max quality levels. Its medium and high levels use roughly one quarter of the output tokens of the previous generation’s levels with the same names.

Request parameters

string

required

Image model name: gpt-image-2.5-flare or gpt-image-2.5-sunburst.

string

required

Text description of the image to generate or edit. Describe the subject, scene, composition, style, lighting, and anything that must be preserved or changed.

string

default:"auto"

Output aspect ratio or exact pixel dimensions.

auto: let the model choose from the prompt or reference images
Aspect ratio: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3
Exact dimensions, such as 1600x1200

For image-to-image requests, omit size to let the service calculate dimensions from the input aspect ratio and resolution.

string

default:"1k"

Resolution tier used with an aspect-ratio size: 1k, 2k, or 4k. This field is ignored for exact pixel dimensions.

string

default:"auto"

Image quality: low, medium, high, xhigh, max, or auto.

xhigh and max are exclusive to GPT-Image-2.5. Sending them to gpt-image-2 returns HTTP 400; the request is not silently downgraded.

integer

default:"1"

Number of images to generate. Range: 1 to 4. Pass a number, not a string.

string

default:"png"

Output file format: png, jpeg, or webp.

integer

Compression level from 0 to 100. Only applies to jpeg and webp.

string

Background mode: transparent, opaque, or auto.

background: "transparent" requires output_format: "png" or output_format: "webp". JPEG has no alpha channel.

string

default:"low"

Content moderation level: auto or low. APIMart explicitly sends low when omitted; an explicit auto value is passed through.

string[]

Reference image URLs for image-to-image generation or editing. Up to 16 images are accepted, and including this field activates editing mode.Only publicly accessible HTTP(S) URLs are accepted. Upload local images with POST /v1/uploads/images, then use the returned url.

string

Mask image for local inpainting. It only takes effect when image_urls is also provided. Both gpt-image-2.5-flare and gpt-image-2.5-sunburst support this parameter.Pass a single string in either format:

An HTTP(S) image URL that the server can download directly
A PNG Data URL in the form data:image/png;base64,...

Mask requirements:

Use a PNG with an alpha channel; PNG is also recommended for the source image
Its pixel dimensions must exactly match image_urls[0]. Match the first input image, not the output size
Fully transparent pixels (alpha=0) mark the area to edit; the remaining area is used for preservation
Send one mask per request. With multiple reference images, the mask only applies to the first input image
The general file-size guide says under 50 MB, while the mask parameter reference says under 4 MB. Until verified, use the stricter 4 MB limit

A plain black-and-white image without an alpha channel cannot be used directly as a mask. APIMart does not add an alpha channel and currently does not prevalidate that the mask dimensions match the source image; the caller must ensure both.

An HTTP(S) URL must work without cookies or additional authorization headers. Signed URLs should remain valid throughout queueing and execution. The default download limit is 20 MB with a 60-second timeout; a deployment may override these defaults.The mask guides editing, but the model does not guarantee that pixels outside the mask boundary remain completely unchanged.

Size rules

Exact pixel dimensions must satisfy all of these constraints:

Width and height are both multiples of 16
Neither side exceeds 3840 pixels
Long-side to short-side ratio is at most 3:1
Total pixel count is between 655,360 and 8,294,400

Resolutions above 2560×1440 are experimental and may be less stable than common sizes.

Aspect ratio and resolution mapping

`size`	`1k`	`2k`	`4k`
`1:1`	1024×1024	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	2560×2048	3216×2576
`4:5`	1024×1280	2048×2560	2576×3216
`16:9`	1536×864	2048×1152	3840×2160
`9:16`	864×1536	1152×2048	2160×3840
`2:1`	2048×1024	2688×1344	3840×1920
`1:2`	1024×2048	1344×2688	1920×3840
`21:9`	2016×864	2688×1152	3840×1648
`9:21`	864×2016	1152×2688	1648×3840
`3:1`	1536×512	3072×1024	3840×1280
`1:3`	512×1536	1024×3072	1280×3840

You may also pass any exact dimensions that satisfy the size rules; they do not need to appear in this table.

Usage examples

Text to image

{
  "model": "gpt-image-2.5-flare",
  "prompt": "a sky garden in a futuristic city, morning mist, architectural photography",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high",
  "n": 1
}

Precision editing with Sunburst

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "preserve the product and package text, replace the background with a soft off-white studio, and add a natural shadow",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Local inpainting with a mask

This example edits only the fully transparent area of the mask. The mask dimensions must match product.png:

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "replace only the area covered by the transparent mask with a gold ribbon, preserving the product and the rest of the background",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}

Transparent background

{
  "model": "gpt-image-2.5-flare",
  "prompt": "e-commerce product photo of white sneakers, complete subject, transparent background",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}

Submission and task query

Successful submission immediately returns an asynchronous task ID. data is an array; read data[0].task_id. Call the task status endpoint with the returned ID. Poll every 2–5 seconds until the status becomes completed or failed. Use POST /v1/tasks/batch to query multiple tasks.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "credits_cost": 0.1325,
    "result": {
      "images": [
        {
          "url": ["https://upload.apimart.ai/f/image/example.png"],
          "expires_at": 1789000000
        }
      ]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

Image URLs are located at data.result.images[].url[]. Download and store them promptly instead of relying on temporary URLs.

Status	Meaning
`submitted`	Task submitted
`processing`	Generation in progress
`completed`	Generation succeeded; `result.images` is available
`failed`	Generation failed; check `error.message`; reserved funds are refunded

Billing

GPT-Image-2.5 is billed by actual token usage. Flare and Sunburst use identical rates. Check the pricing page or /api/pricing for current account pricing.

Item	Price per 1M tokens
Image output	$30.00
Image input	$8.00
Cached image input	$2.00
Text input	$5.00
Cached text input	$1.25

1024×1024 output token reference

`quality`	Output tokens	Official output cost
`low`	196	$0.00588
`medium`	439	$0.01317
`high`	1756	$0.05268
`xhigh`	3122	$0.09366
`max`	7024	$0.21072

With quality: "auto", the model chooses the actual level at runtime. The service reserves funds using the max level for the selected size and settles against actual usage when the task finishes. Specify quality when available balance matters.

For n > 1, the reservation scales linearly with the requested image count. Final billing uses the number of images actually generated, and failed tasks are refunded automatically.

Output token reference

Values are per generated image. Actual billing also includes prompt and reference-image input tokens.

Size	Pixels	low	medium	high	xhigh	max
`1:1`	1024×1024	196	439	1756	3122	7024
`3:2`	1536×1024	158	343	1372	2459	5488
`2:3`	1024×1536	158	343	1372	2459	5488
`4:3`	1024×768	134	301	1204	2140	4815
`3:4`	768×1024	134	301	1204	2140	4815
`5:4`	1280×1024	173	378	1510	2702	6119
`4:5`	1024×1280	173	378	1510	2702	6119
`16:9`	1536×864	120	280	1078	1917	4312
`9:16`	864×1536	120	280	1078	1917	4312
`2:1`	2048×1024	132	295	1180	2098	4720
`1:2`	1024×2048	132	295	1180	2098	4720
`21:9`	2016×864	105	225	943	1617	3682
`9:21`	864×2016	105	225	943	1617	3682
`3:1`	1536×512	56	134	535	937	2140
`1:3`	512×1536	56	134	535	937	2140
`1:1@2k`	2048×2048	397	892	3568	6343	14272
`3:2@2k`	2048×1360	211	460	1838	3216	7351
`2:3@2k`	1360×2048	211	460	1838	3216	7351
`4:3@2k`	2048×1536	247	556	2223	3952	8892
`3:4@2k`	1536×2048	247	556	2223	3952	8892
`5:4@2k`	2560×2048	377	826	3303	5911	13385
`4:5@2k`	2048×2560	377	826	3303	5911	13385
`16:9@2k`	2048×1152	157	367	1413	2511	5650
`9:16@2k`	1152×2048	157	367	1413	2511	5650
`2:1@2k`	2688×1344	180	405	1617	2874	6466
`1:2@2k`	1344×2688	180	405	1617	2874	6466
`21:9@2k`	2688×1152	143	306	1285	2202	5016
`9:21@2k`	1152×2688	143	306	1285	2202	5016
`3:1@2k`	3072×1024	103	247	988	1729	3952
`1:3@2k`	1024×3072	103	247	988	1729	3952
`1:1@4k`	2880×2880	659	1483	5930	10542	23719
`3:2@4k`	3520×2336	450	982	3926	6870	15703
`2:3@4k`	2336×3520	450	982	3926	6870	15703
`4:3@4k`	3312×2480	491	1104	4413	7845	17650
`3:4@4k`	2480×3312	491	1104	4413	7845	17650
`5:4@4k`	3216×2576	535	1173	4690	8393	19006
`4:5@4k`	2576×3216	535	1173	4690	8393	19006
`16:9@4k`	3840×2160	371	865	3336	5930	13342
`9:16@4k`	2160×3840	371	865	3336	5930	13342
`2:1@4k`	3840×1920	300	675	2700	4799	10798
`1:2@4k`	1920×3840	300	675	2700	4799	10798
`21:9@4k`	3840×1648	234	500	2099	3598	8196
`9:21@4k`	1648×3840	234	500	2099	3598	8196
`3:1@4k`	3840×1280	139	332	1328	2324	5311
`1:3@4k`	1280×3840	139	332	1328	2324	5311

Limits and common errors

Item	Limit or handling
Images per request (`n`)	1–4
Reference images	Up to 16
Output format	PNG / JPEG / WebP
Transparent background	PNG / WebP only
Partial streaming images	Not supported
Unsupported `quality`	`xhigh` / `max` require GPT-Image-2.5
Invalid exact dimensions	Use multiples of 16 within the pixel and aspect-ratio limits

Response

integer

Response status code; 200 when submission succeeds.

array

Submission response data.

Show Array item

string

Initially submitted.

string

Unique task ID used to query generation status and results.

Overview

Models

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

GPT-Image-2.5 Image Generation

Authentication

Choose a model

Request parameters

Size rules

Aspect ratio and resolution mapping

Usage examples

Text to image

Precision editing with Sunburst

Local inpainting with a mask

Transparent background

Submission and task query

Billing

1024×1024 output token reference

Output token reference

Limits and common errors

Response

​Authentication

​Choose a model

​Request parameters

​Size rules

​Aspect ratio and resolution mapping

​Usage examples

​Text to image

​Precision editing with Sunburst

​Local inpainting with a mask

​Transparent background

​Submission and task query

​Billing

​1024×1024 output token reference

​Output token reference

​Limits and common errors

​Response

Authentication

Choose a model

Request parameters

Size rules

Aspect ratio and resolution mapping

Usage examples

Text to image

Precision editing with Sunburst

Local inpainting with a mask

Transparent background

Submission and task query

Billing

1024×1024 output token reference

Output token reference

Limits and common errors

Response