A Practical Guide to Editing Images with the GPT Image 2 API

A Practical Guide to Editing Images with the GPT Image 2 API

When an image is almost right, rebuilding it from scratch is usually the wrong move. A small product color change, a cleaner background, or a revised composition should be an edit, not a full regeneration. The GPT Image 2 / 2.5 Image Editing API on Ace Data Cloud is built for that workflow: send a reference image, describe the exact change, and receive an edited result through the same API surface.

What you can do

The editing endpoint is useful whenever you already have source visual material and want controlled changes. Typical builder workflows include:

  • Changing a product attribute while preserving camera angle, layout, and shadows.
  • Replacing a background for a cleaner app-store, blog, or landing-page asset.
  • Using multiple references to guide a composite or consistent visual direction.
  • Moving long-running image jobs to an asynchronous callback flow.

The public documentation shows the endpoint https://api.acedata.cloud/openai/images/edits. It accepts an Ace Data Cloud API key in the Authorization: Bearer ... header and supports both JSON image URLs and multipart local uploads.

How it works

The simplest mental model is: one image input plus one editing instruction equals one task result. In JSON requests, the image field can be a single URL or an array of URLs. For local files, use multipart/form-data and send one or more image file fields. The GPT Image series supports up to 16 reference images, which is enough for many practical cases such as combining a base product shot with a logo, palette reference, or scene direction.

The core fields are intentionally small:

  • model: choose gpt-image-2, gpt-image-2.5-flare, or gpt-image-2.5-sunburst. The documentation also notes corresponding :official variants, and gpt-image-2 supports :reverse.
  • image: a single URL, an array of up to 16 URLs, or one or more multipart file fields.
  • prompt: the editing instruction. This is where you specify what changes and what must remain unchanged.
  • size: auto or a valid WIDTHxHEIGHT.
  • n: 1–10. When response_format is b64_json, only 1 is supported.
  • response_format: url or b64_json.
  • callback_url: optional callback URL for asynchronous completion.

Edit from an image URL

URL-based editing is the best starting point for server-side workflows because you can keep the request as JSON and avoid temporary file handling. The important part is to write a prompt that separates the target change from the protected parts of the original image. For example, if you only want to recolor an object, explicitly say which elements should stay unchanged.

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

Upload a local image

If the image lives on your machine or in a private build step, use multipart upload instead. The documented local-file pattern is compact:

curl https://api.acedata.cloud/openai/images/edits   -H "Authorization: Bearer YOUR_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 in CLI scripts, CMS tooling, or design automation pipelines where the generated asset is written to disk before the edit step. If you need multiple references, repeat the image field in the multipart request.

Choose a size deliberately

The size field can be auto, but explicit dimensions make repeatable publishing workflows easier. The documented rules 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, and the aspect ratio must not exceed 3:1. If size is omitted or set to auto, the model chooses the canvas from the prompt and the first reference image.

For a blog cover, for example, a horizontal canvas such as 1200x640 satisfies the multiple-of-16 rule and stays inside the pixel and aspect-ratio limits.

Use callbacks for long-running edits

Image edits can take long enough that a synchronous HTTP request may not be the best fit. The documentation recommends adding callback_url for long-running tasks:

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

With the asynchronous flow, a 200 response may return a task_id, and the final result is sent to your callback after completion. This is a cleaner fit for queues, background jobs, and product interfaces where users should not wait on an open request.

Troubleshooting checklist

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

Error responses include a trace_id. Keep that value when reporting an issue, but do not share your API key.

Closing thoughts

The most reliable image-editing prompts read like precise production notes: preserve the composition, name the exact element to change, specify what must not appear, and choose a size that fits the publishing target. Start with one reference image and gpt-image-2, then move to multiple references or callbacks when your workflow needs them.

For the complete field list and current model enumerations, read the OpenAI Images Edits API Integration Guide.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more