How to Build a Practical Image Editing Workflow with the GPT Image 2 API

Most image automation projects do not need a completely new image every time. They need controlled edits: keep the product, composition, or camera angle stable, then change one specific thing such as the background, object color, or studio setting. The GPT Image 2 / 2.5 image editing API in Ace Data Cloud is useful for exactly that kind of workflow.

What you can do

The image editing endpoint lets you send an existing image plus a written instruction, then receive an edited result. The documented endpoint is POST https://api.acedata.cloud/openai/images/edits. In a JSON request, the image field can be a single image URL or an array of image URLs. For local files, the same workflow is available through multipart/form-data using one or more image file fields.

This makes the API a good fit for builder workflows such as:

• Changing a product background while preserving the object and camera angle.
• Applying a precise visual edit to a reference image from a URL.
• Using multiple references when a prompt needs more visual context.
• Moving long-running edits to an asynchronous callback flow instead of blocking a request.

How it works

The request is conceptually simple: choose a model, provide the input image, write the edit instruction, and optionally choose an output size or response mode. The common fields documented for the endpoint are model, image, prompt, size, n, response_format, and callback_url.

The documented model options include gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. The same document also notes corresponding :official variants, and that gpt-image-2 supports :reverse. For most implementation work, start with the smallest complete request first, inspect the output, and only then add parameters such as size or callback_url.

Edit an image from a URL

If your source asset is already hosted, use a JSON request. The following example follows the documented pattern: it sends a Bearer token, sets Content-Type: application/json, uses model, passes a URL in image, gives a specific prompt, and requests a portrait canvas with size.

curl https://api.acedata.cloud/openai/images/edits   -H "Authorization: Bearer $ACE_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"
  }'

That style of prompt matters. It explicitly says what should stay unchanged, what should change, and what should not appear. For editing tasks, this is usually more reliable than a broad aesthetic prompt because the model has to preserve parts of the original image while transforming only selected details.

Understand the response shape

A successful synchronous response includes success, task_id, trace_id, created, model, data, and usage. The edited image URL is returned inside data:

{
  "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
  }
}

In production, store task_id and trace_id with your own job record. If a user reports a bad edit or an operational error, trace_id gives you a clean support handle without exposing the API key.

Upload local images when assets are not hosted

When the input image is on disk, send multipart/form-data. The documented local upload pattern uses form fields for model, image, and prompt:

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

The GPT Image series supports up to 16 reference images. With JSON, pass those references as an array of URLs in image. With multipart upload, repeat the image file field. A practical pattern is to put the base image first, then add secondary references only when they clearly improve the edit instruction.

Choose size, output mode, and async behavior deliberately

The documented size value can be auto or a valid WIDTHxHEIGHT. Width and height must be multiples of 16, the longer side must not exceed 3840, total pixels must be between 655,360 and 8,294,400, and the aspect ratio must not exceed 3:1. If size is omitted or set to auto, the model chooses the canvas based on the prompt and the first reference image.

The response_format field can be url or b64_json. The documented limit for n is 1–10, but only 1 is supported when response_format is b64_json. For longer tasks, add a callback_url. An asynchronous 200 response returns {"task_id":"..."}, and the final result is delivered to the callback after completion.

Troubleshooting checklist

• 400: check image format/count, parameter combinations, and size format.
• 401: check the API key and Bearer header.
• 429: reduce request frequency.
• 504: switch to asynchronous callbacks.

The useful habit is to treat image editing as a job pipeline rather than a one-off prompt. Validate the input image, build a narrow edit instruction, persist task_id and trace_id, and choose callbacks when latency matters. That gives you a workflow that is easier to debug and safer to expose inside your own product.

For the full field list and the source examples, read the OpenAI Images Edits API guide.