A Practical Guide to Editing Images with GPT-Image-2

Image editing APIs are most useful when they preserve the parts of an image you care about while changing only the parts you asked for.

This guide walks through the OpenAI Images Edits API on Ace Data Cloud using gpt-image-2. The goal is practical: take an existing image, send a clear edit instruction, and receive an edited image without building a custom upload pipeline first.

What you can do

The edits endpoint accepts an input image plus a text instruction and returns a modified image. According to the public documentation, the GPT Image series can use up to 16 reference images in one request, which makes it useful for workflows such as:

turning an infographic into a dark-mode version while keeping the layout intact;
changing the style of a product or scene while preserving object arrangement;
combining multiple reference images into one composed output;
redrawing an image at a requested output size such as 1024x1024, 2048x2048, or a valid custom size.

The same interface also supports several model families. The document lists gpt-image-1, gpt-image-2, gpt-image-2:official, gpt-image-2:reverse, and the nano-banana family. This article focuses on gpt-image-2 because it is the most straightforward path for URL-based JSON requests.

How it works

The main endpoint for JSON-based editing is:

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

For gpt-image-2, you can send application/json with the following core fields:

model: for example, gpt-image-2;
image: an image URL, a base64 image string, or an array of image URLs/base64 values;
prompt: the editing instruction;
size: auto, omitted, or a string in WIDTHxHEIGHT format;
n: number of results, from 1 to 10.

When size is auto or omitted, the output keeps the aspect ratio of the reference image. If you want to change the aspect ratio, specify size explicitly. Custom sizes must use width and height values that are multiples of 16, with long side no more than 3840 and total pixels no more than 8,294,400.

Start with a URL-based edit

The URL-based JSON path is convenient for backend jobs because your service does not need to download the source image and re-upload it as multipart form data. Here is a minimal curl request that converts an infographic-style image to a dark theme while preserving structure:

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

The documented response includes success, task_id, trace_id, created, and a data array. Each item in data can contain a revised_prompt and a result url.

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode...",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

Use multiple reference images

If a task needs visual context from several files, pass an array in image. The documentation says the GPT Image series supports up to 16 images. A typical product-composition request looks like this:

import requests

url = "https://api.acedata.cloud/openai/images/edits"
headers = {
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

This pattern is useful when your application already stores assets in object storage or a CDN. You can keep the orchestration layer simple: collect URLs, write the edit instruction, submit one JSON payload, then store the returned image URL.

When to use base64 or multipart

URL input is not the only path. The image field can also accept base64 values, either as data:image/png;base64,... or raw base64. That is helpful for local images you do not want to upload elsewhere before editing.

If you are already using the official OpenAI Python SDK, the documented multipart-style workflow also works by setting the base URL to Ace Data Cloud and using client.images.edit:

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

import base64
from openai import OpenAI

client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

A few implementation notes

Use precise prompts when you need preservation: say what must stay identical, not only what should change.
For n > 1, use URL output rather than response_format=b64_json, because the documentation notes that base64 JSON only supports n=1.
Validate size before sending the request. Invalid formats return a 400 error, and oversized custom dimensions can return a 4xx error.
For long-running jobs, the documented asynchronous callback flow lets you provide callback_url and correlate the result by task_id.

Wrapping up

The practical value of the edits endpoint is that it fits cleanly into existing builder workflows: an image URL, a specific instruction, a model name, and a result URL. Start with one reference image and a narrow edit, then expand to multi-reference workflows once the prompt style is reliable.

For the full parameter details and examples, read the OpenAI Images Edits API Integration Guide.

Search This Blog

AceDataCloud