OpenAI Images Edits API Application and Usage

OpenAI image editing service allows you to input any number of images and instructions, outputting modified images. Currently, the interface supports both gpt-image-1 and the latest gpt-image-2, as well as the nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro series models through the same interface.

This document mainly introduces the usage process of the OpenAI Images Edits API, allowing us to easily utilize the official OpenAI image editing features.

¶ Application Process

To use the OpenAI Images Edits API, first go to the Ace Data Cloud Console to obtain your API Token for backup.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and will return to the current page upon completion.

One API Token can call all services on the platform without needing to apply separately for each service. The first application will grant free credits for a trial; when credits are insufficient, you can recharge the general balance in the console.

📘 Complete documentation: OpenAI Images Edits API →

¶ GPT-Image-2 Model

gpt-image-2 shows significant improvements in image editing scenarios compared to gpt-image-1:

• Structure remains more stable: Changing skin, color scheme, or background almost never disrupts the original layout and composition.
• Text retention is more accurate: Images containing text, such as infographics, posters, and menus, remain clear and readable after editing.
• Supports direct URL input: In addition to traditional multipart/form-data file uploads, gpt-image-2 also supports passing image URLs in JSON format, eliminating the need to download images locally first, making it very suitable for server-side pipeline integration.
• Supports base64 direct input: Consistent with the official, the image field can also directly accept base64 (data:image/png;base64,... or raw base64), allowing local images to be edited without first uploading to an image hosting service.
• Supports high-resolution redrawing: You can input a 1K original image and request 2K / 4K output through the size parameter, with the model completing the enlargement during the editing process.

¶ Line Variants (:official / :reverse)

gpt-image-2 defaults to the standard line. You can explicitly select the line by appending a suffix to the model name:

• gpt-image-2:official: Official channel, stable and compliant. Supports true 2K / 4K high resolution, billed per image, with a unit price twice that of the default gpt-image-2. If the line is unavailable, it will return an error directly without automatic downgrade.
• gpt-image-2:reverse: Completely equivalent to the default gpt-image-2, offering better cost performance at the same price.

¶ Supported size Values

The constraints on size for the editing interface are completely consistent with the generation interface—gpt-image-2 only requires size to be auto, empty, or in the WIDTHxHEIGHT format; any other form will return 400. All sizes (1K / 2K / 4K / custom) are charged uniformly per image, regardless of the original image resolution and the size request value.

Size limitations: Custom sizes must meet the criteria of both width and height being multiples of 16, long side ≤ 3840, total pixel count ≤ 8,294,400; exceeding these will return 4xx.

Ratio	1K Recommended	2K Recommended	4K Recommended
1:1	1024x1024	2048x2048	2880x2880
4:3	1536x1024	2048x1536	3264x2448
3:4	1024x1536	1536x2048	2448x3264
16:9	1792x1024	2048x1152	3840x2160
9:16	1024x1792	1152x2048	2160x3840

For example: If the original image is 1024x1024, and size is set to 2048x2048, the model will redraw according to the editing instructions and output a 2K image; if size is set to 3840x2160, it will output a 4K landscape image; if auto is passed or omitted, the model will choose automatically. All three will be billed the same.

About the n Parameter The gpt-image-2 editing interface supports n > 1: a single request can return and bill for the corresponding number of edited results (n values from 1 to 10). This also applies to gpt-image-1 / gpt-image-1.5, as well as the nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro series. Note that response_format=b64_json only supports n=1; for n>1, please use the default URL return. If some images fail to generate, only the successful parts will be returned and billed.

Below are two different real examples to experience the editing capabilities of gpt-image-2.

¶ Calling Method One: JSON + Image URL (Recommended)

Send a request directly in application/json format, filling the image field with the URL of an image; the model will fetch the image and edit it according to the prompt.

For example, the original image below is a science popularization illustration generated using gpt-image-2:

We want to change it to a "night mode" color scheme. We can call it like this:

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

Or using Python:

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

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

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

The return result is as follows:

{
  "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: 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.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

The edited image is as follows:

It can be seen that the module structure, information partition, and font layout have been strictly preserved, with only the color scheme inverted to a dark theme.

Tip: The image field also supports passing an array, for example, "image": ["url1", "url2", "url3"], allowing up to 16 reference images to be passed simultaneously for the model to comprehensively reference multiple images for editing.

Base64 direct transmission: The image (and each item in the array) can also be base64 — data:image/png;base64,... or raw base64, suitable for local images that you do not want to upload to an image hosting service first. For example:

import base64, requests
b64 = base64.b64encode(open("input.png", "rb").read()).decode()
payload = {
    "model": "gpt-image-2",
    "image": f"data:image/png;base64,{b64}",
    "prompt": "Convert this infographic to dark mode.",
    "size": "1024x1536"
}
requests.post("https://api.acedata.cloud/openai/images/edits", json=payload,
              headers={"authorization": "Bearer {token}"})

¶ Calling Method Two: JSON + Multiple Reference Images

gpt-image-2 supports referencing multiple images simultaneously to generate the final result, for example, combining multiple product photos into a single gift basket:

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

¶ Scenario Example: Change Style + Maintain Structure

Here is another example, replacing a wooden bookshelf with a modern floating shelf while strictly preserving the number and arrangement of books on each shelf.

Original image (wooden bookshelf generated with gpt-image-2):

Call:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

Editing result (task_id: e9544dba-727e-44a2-81e1-223d49869380):

It can be seen that the style and environment have been completely replaced according to the prompt, but the number of books on each shelf (1 / 3 / 7) is still strictly preserved, and a potted succulent has been added as requested.

¶ Calling Method Three: multipart/form-data (Compatible with OpenAI SDK)

If you are already using the official OpenAI Python SDK, the existing multipart/form-data upload method is also applicable; just change the model to gpt-image-2:

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)

When using the SDK, you need to import two environment variables first, set OPENAI_BASE_URL to https://api.acedata.cloud/openai, and OPENAI_API_KEY to the token you applied for:

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

¶ Nano Banana Series Models

The nano-banana series has also integrated with /openai/images/edits in editing scenarios; just change the model to any of the ones in the table below.

Model	Billing (Credits / Time)	Applicable Scenarios
nano-banana	0.14	General image editing, fastest speed, lowest cost
nano-banana-2-lite	0.14	Gemini 3.1 lightweight image model, supports only 1K, low-latency editing
nano-banana-2	0.28	Significant improvement in quality and detail
nano-banana-pro	0.35	The flagship of the series, best preservation of structure, text, and style

Important: Supported Parameter Range Nano Banana connects to the OpenAI protocol through an adapter layer and only supports the following parameters: model, prompt, image, n.

• image can be uploaded as a file via multipart/form-data (local files will be automatically converted to base64), or it can be directly passed as a string of the image URL through a form field.
• Parameters such as mask, size, response_format, etc., are not supported; if filled, they will be ignored. n > 1 is supported (1–10) and will return and charge for the corresponding number of edited results.
• The return structure follows the OpenAI format (data[].url), but created is fixed at 0, and b64_json will not be returned; revised_prompt will always equal the original prompt.

¶ Calling via Form + Image URL

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

The return result is as follows:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

Edited image:

¶ Calling via Form + Local File

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

¶ Asynchronous Callback

The callback_url asynchronous callback mechanism is also effective for nano-banana, and the calling process is completely consistent with other models. For details, see the section Asynchronous Callback.

¶ Basic Usage

Next, you can use code to make calls. Below is a call using CURL:

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

When using this interface for the first time, we need to fill in at least four pieces of information: one is authorization, which can be selected directly from the dropdown list. The other parameter is model, which is the category of the OpenAI model we choose to use; here we mainly have one model, details can be found in the models we provide. Another parameter is prompt, which is the input prompt for generating the image. The last parameter is image, which requires the path of the image to be edited, as shown in the image below:

The equivalent Python sample call code is:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Save the image to a file
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

To use Python for the call, we first need to import two environment variables: one OPENAI_BASE_URL, which can be set to https://api.acedata.cloud/openai, and another credential variable OPENAI_API_KEY, which is the value obtained from authorization. On Mac OS, you can set the environment variables with the following commands:

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

After the call, we find that an image gift-basket.png will be generated in the current directory, and the specific result is as follows:

Thus, we have completed the image editing operation. Currently, the Edits interface supports two models: gpt-image-1 and gpt-image-2, with gpt-image-2 being the recommended model to use, as detailed in the section GPT-Image-2 Model.

¶ Asynchronous Callback

Since the OpenAI Images Edits API may take a relatively long time to edit images, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks.

The overall process is: when the client initiates a request, an additional callback_url field is specified. After the client initiates the API request, the API will immediately return a result containing a task_id field, representing the current task ID. When the task is completed, the result of the edited image will be sent to the client-specified callback_url in the form of a POST JSON, which also includes the task_id field, allowing the task result to be associated by ID.

Let’s understand how to operate specifically through an example.

First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For convenience, we use a public Webhook sample site https://webhook.site/. By opening this site, you can get a Webhook URL, as shown in the image:

Copy this URL, and it can be used as a Webhook. The sample here is https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.

Next, we can set the callback_url field to the above Webhook URL and fill in the corresponding parameters, as shown in the following code:

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

After the call, you will find that an immediate result is obtained, as follows:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

After a moment, we can observe the result of the image editing at the Webhook URL, as follows:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

It can be seen that the result contains a task_id field, and the data field includes the same image editing result as the synchronous call, allowing for task association through the task_id field.

¶ Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:

• 400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token: Unauthorized, invalid or missing authorization token.
• 429 too_many_requests: Too many requests, you have exceeded the rate limit.
• 500 api_error: Internal server error, something went wrong on the server.

¶ Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

¶ Conclusion

Through this document, you have learned how to easily use the official OpenAI image editing features with the OpenAI Images Edits API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team.