GPT Image 2 / 2.5 Image Editing API

¶ 1. Obtain an API Key

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

¶ 2. Edit Using an Image URL

Original image:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform2.cdn.acedata.cloud/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0.png",
    "prompt": "Keep the mug, tabletop, camera angle, portrait layout, and soft shadow unchanged. Change only the mug color from white to vivid orange and the pale cream background to solid dark navy blue. No text and no logo.",
    "size": "1024x1536"
  }'

Successful response:

{
  "success": true,
  "task_id": "49848451-c624-4df9-9dc2-494018daaf4c",
  "trace_id": "5ac021c2-2891-4eed-bfcf-4c6668ac1be1",
  "created": 1788831893,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://platform2.cdn.acedata.cloud/gpt-image/49848451-c624-4df9-9dc2-494018daaf4c_0.png"
    }
  ],
  "usage": {
    "input_tokens": 775,
    "output_tokens": 1372,
    "total_tokens": 2147
  }
}

This is the editing result actually completed through Ace Data Cloud on September 8, 2026. The mug was changed to orange, the background was changed to dark navy blue, and the original composition and 1024×1536 size were retained:

¶ 3. Upload a Local Image

Use multipart/form-data:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a bright modern studio"

You can repeatedly pass in image; the GPT Image series supports up to 16 reference images. The image field in JSON requests can be a single URL or an array of URLs; local files use multipart upload.

¶ 4. Common Parameters

Field	Description
model	gpt-image-2, 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
image	JSON uses a single URL or an array of up to 16 URLs; multipart uses one or more image file fields
prompt	Editing instruction
size	auto or a valid WIDTHxHEIGHT
n	1–10; only 1 is supported when response_format=b64_json
response_format	url or b64_json
callback_url	Optional asynchronous callback URL

The size rules are consistent with the generation API: width and height must be multiples of 16, the longer side must not exceed 3840, the total pixels must be 655,360–8,294,400, and the aspect ratio must not exceed 3:1. When size is omitted or auto is used, the model selects the canvas based on the prompt and the first reference image.

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 Tokens for text input, reference image input, and image output, with the usage records being final.

¶ 5. Asynchronous Callbacks and Troubleshooting

For long-running tasks, add the following to the request:

{
  "callback_url": "https://example.com/webhooks/images"
}

An asynchronous 200 response is {"task_id": "..."}; the final result is returned through a callback after completion. A synchronous request returns created and data.

Status	Check
400	Image format/count, parameter combinations, and size format
401	API Key and Bearer Header
429	Request frequency
504	Switch to asynchronous callbacks

Error responses include trace_id. Provide this ID when reporting issues; do not provide the API Key.

For complete fields and real-time enumerations, refer to the OpenAI Images Edits API page. For generating images from text only, see GPT Image 2 / 2.5 Image Generation.