How to Build an Image Editing Workflow with GPT Image 2

When you are building a product feature that edits images, the hard part is usually not the prompt itself. It is the workflow around it: accepting a source image, preserving the parts that should not change, validating size constraints, handling long-running requests, and making failures debuggable.

This guide walks through a practical image-editing flow using Ace Data Cloud's OpenAI Images Edits endpoint with gpt-image-2. The goal is simple: take an existing image, describe the change you want, and return an edited image while keeping the implementation predictable enough for a real app.

What you can do

The Images Edits API is designed for instruction-based edits on existing images. According to the documentation, the core endpoint is:

POST https://api.acedata.cloud/openai/images/edits

In a JSON request, image can be a single image URL or an array of image URLs. If you are uploading local files, the API also supports multipart/form-data with one or more image fields. The GPT Image series supports up to 16 reference images, which is useful when you want to keep a base image and provide additional visual references.

The common fields you will usually work with are:

• model: one of gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, their corresponding :official variants, or gpt-image-2:reverse.
• image: a source image URL, an array of up to 16 URLs, or uploaded multipart image files.
• prompt: the editing instruction.
• size: auto or a valid WIDTHxHEIGHT value.
• n: number of outputs from 1 to 10, with only 1 supported when response_format is b64_json.
• response_format: url or b64_json.
• callback_url: an optional webhook URL for asynchronous completion.

How it works

A good edit request has three parts: the source image, the instruction, and the canvas settings. The source image gives the model the visual structure. The instruction tells it what to change and, just as importantly, what to preserve. The canvas settings make the result fit your product surface.

For example, the source documentation shows an edit where the prompt explicitly preserves the mug, tabletop, camera angle, portrait layout, and soft shadow, while changing only the mug color and background. That is the style of prompt you want in production: concrete, bounded, and clear about invariants.

Start with a URL-based edit

If your application already stores images in object storage or a CDN, the JSON flow is the easiest place to start. Here is a minimal curl request using the documented endpoint and fields:

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

A successful synchronous response includes success, task_id, trace_id, created, model, data, and usage. The edited image URL is returned under 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
  }
}

Use multipart upload for local files

When the image is still on a user's machine or inside a backend job, use multipart/form-data. The documented shape is straightforward:

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

This form is convenient for admin tools, batch scripts, and internal review workflows. If you need multiple references, repeat the image file field. For JSON requests, pass an array of URLs instead.

Validate size before you send the request

The size rules matter if you expose custom dimensions in a UI. The documented constraints are:

• 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.
• The aspect ratio must not exceed 3:1.

If size is omitted or set to auto, the model selects the canvas based on the prompt and the first reference image. For product features, I usually start with auto during prototyping, then lock dimensions once the layout requirements are known.

Handle long-running edits with callbacks

Image edits can take long enough that a synchronous request is not always the best fit. The API supports an optional callback_url:

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

With an asynchronous call, the immediate 200 response is a small object containing task_id. The final result is delivered to your callback after completion. This is the pattern I would use for queues, background jobs, or any user-facing app where a browser tab should not wait on a long HTTP request.

Troubleshooting checklist

The documentation calls out a few common failure modes that are worth turning into product-level checks:

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

Error responses include trace_id. Log that ID with your job record so you can investigate issues without exposing the API key.

A practical builder pattern

A reliable image-editing feature can be small: upload or reference an image, validate size, build a prompt that names both changes and invariants, send the request, store task_id and trace_id, then persist the returned data[0].url. That gives you enough structure to support previews, retries, support logs, and asynchronous completion later.

For the complete field list and the original examples, read the OpenAI Images Edits API Integration Guide.