GPT Image 2 / 2.5 Image Generation API

1. Obtain an API Key

Open the Ace Data Cloud application list, enter an available application, and copy the API Key. Obtain an Ace Data Cloud API Key

2. Send the First Request

curl https://api.acedata.cloud/openai/images/generations \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Minimal editorial product illustration: one plain white ceramic coffee mug centered on a solid cobalt blue tabletop, pale cream background, soft shadow, clean geometric shapes, no text, no logo, portrait composition",
    "size": "1024x1536"
  }'

The image in a successful response is located at data[].url. Below is the actual 1024×1536 result obtained through an Ace Data Cloud request on September 8, 2026 (task d56455e2-e7f7-4bcd-b935-475b0a1e0948, trace eb938601-8192-407f-b539-1e0554b697ec): White ceramic mug generated by GPT Image 2

White ceramic mug generated by GPT Image 2

3. Common Parameters

Field	Description
`model`	`gpt-image-2` (recommended by default), `gpt-image-2.5-flare` (faster), or `gpt-image-2.5-sunburst` (higher fidelity and control); all three can use their corresponding `:official` variants, and `gpt-image-2` also supports `:reverse`
`prompt`	Image description, up to 32,000 characters
`size`	`auto` or `WIDTHxHEIGHT`; width and height must be multiples of 16, the longest side must not exceed 3840, total pixels must be 655,360–8,294,400, and the aspect ratio must not exceed 3:1
`n`	1–10; only 1 is supported when `response_format=b64_json`
`quality`	`low`, `medium`, `high`, or `auto`; support and billing methods vary across routes
`response_format`	`url` or `b64_json`
`callback_url`	Optional; sends results to this address after a long-running task is completed

Common sizes:

Ratio	1K	2K	4K
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

size: "auto" selects the canvas according to the ratio, pixels, and layout intent in the prompt; directly specify dimensions when exact pixels are required.

Models and Billing Methods

Model	Applicable Scenarios and Billing Methods
`gpt-image-2`	Default reverse route, billed at a fixed rate per successfully generated image
`gpt-image-2:reverse`	Explicitly selects the reverse route, billed at a fixed rate per successfully generated image
`gpt-image-2:official`	Official API route, with higher stability, billed by actual Token usage
`gpt-image-2.5-flare`	Focuses on generation speed, billed at a fixed rate per successfully generated image
`gpt-image-2.5-flare:official`	Official API route, with higher stability and a focus on generation speed, billed by actual Token usage
`gpt-image-2.5-sunburst`	Focuses on high fidelity and fine-grained control, billed at a fixed rate per successfully generated image
`gpt-image-2.5-sunburst:official`	Official API route, with higher stability and a focus on high fidelity and fine-grained control, billed by actual Token usage

The displayed prices for the official API route are estimates before the request; the final amount is based on the actual Token usage in the response and usage records.

4. Multiple Image Generation

curl https://api.acedata.cloud/openai/images/generations \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A small fox reading under a glowing mushroom, watercolor illustration",
    "size": "1536x1024",
    "n": 2
  }'

gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, and gpt-image-2:reverse are billed by the number of successfully generated images; gpt-image-2:official, gpt-image-2.5-flare:official, and gpt-image-2.5-sunburst:official are billed according to the actual text input and image output Tokens in the response. Displayed prices are estimates before the request; the final amount is based on usage records.

5. Asynchronous Callback

After adding callback_url to the request body, the API first returns {"task_id": "..."} and POSTs the final result to that URL upon completion; synchronous requests still return created and data:

{
  "model": "gpt-image-2",
  "prompt": "A product poster with clear typography",
  "size": "1024x1024",
  "callback_url": "https://example.com/webhooks/images"
}

The callback receiver should use task_id for deduplication and validate the request source and data format.

6. Troubleshooting

Status	Check
400	The combination of `model`, `prompt`, size format, `n`, and `response_format`
401	Whether the API Key is complete and whether the Header is `Authorization: Bearer ...`
429	Requests are too frequent; retry later
504	Synchronous generation timed out; use `callback_url`

Error responses include error.code, error.message, and trace_id. Provide trace_id when reporting an issue, and do not provide the API Key. For complete fields and real-time enums, refer to the OpenAI Images Generations API page. For image editing, see GPT Image 2 / 2.5 Image Editing.

Getting Started

Core Concepts

Integrations

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Coding

More guides

GPT Image 2 / 2.5 Image Generation API

1. Obtain an API Key

2. Send the First Request

3. Common Parameters

Models and Billing Methods

4. Multiple Image Generation

5. Asynchronous Callback

6. Troubleshooting

​1. Obtain an API Key

​2. Send the First Request

​3. Common Parameters

​Models and Billing Methods

​4. Multiple Image Generation

​5. Asynchronous Callback

​6. Troubleshooting

1. Obtain an API Key

2. Send the First Request

3. Common Parameters

Models and Billing Methods

4. Multiple Image Generation

5. Asynchronous Callback

6. Troubleshooting