OpenAI Images Edits API Application and Usage

OpenAI image editing service allows you to input images and instructions, outputting modified images. The GPT Image series models can accept up to 16 reference images simultaneously. Currently, the interface supports gpt-image-1, 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 辰汐ai Console to obtain your API Token for future use.

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 after completion, you will be automatically returned to the current page.

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 experience; 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, or background almost does not damage 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 additionally supports inputting image URLs in JSON format, eliminating the need to download images locally, 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 enlarging the image during the editing process.

¶ Line Variants (:official / :reverse)

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

• gpt-image-2:official: Official channel, stable and compliant. Costs are determined by the text input tokens, image input tokens during editing, and image output tokens, with final billing based on actual usage in the response; the quality/size price displayed on the page is for estimation only; based on the maximum usage package, customer prices are approximately 80% of OpenAI's official standard price. The service will automatically failover between available channels, with capabilities and costs based on actual returned results.
• gpt-image-2:reverse: Completely equivalent to the default gpt-image-2, offering better cost-effectiveness, with unchanged pricing.

:official Billing Formula Final cost = text input tokens + image input tokens (editing only) + image output tokens. The quality × size price displayed on the page is an estimate before the request, with actual charges based on the successful response's usage. For example, the image output cost for low, 1024x1024 is typically about 0.0505 Credits, plus a small amount of input tokens; when using auto, the model may choose a higher quality, and the pre-authorization amount will be conservatively checked at a higher tier.

¶ Supported size Values

The format validation for size in the editing interface is consistent with the generation interface—gpt-image-2 only requires size to be auto, empty, or conforming to the WIDTHxHEIGHT format; any other form will return 400. By default, gpt-image-2 and :reverse charge uniformly per image; :official will calculate text input, reference image input, and image output tokens simultaneously, with the original image, size, and quality potentially affecting the final cost.

Size limits: Custom sizes must meet the criteria of both width and height being multiples of 16, long edge ≤ 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, when size is passed as 2048x2048, the model will redraw according to the editing instructions and output a 2K image; when size is passed as 3840x2160, it will output a 4K landscape image. The billing for the three sizes of default gpt-image-2 and :reverse is consistent; :official is based on actual token usage. Omitting the size field is completely equivalent to explicitly passing auto: gpt-image-2 will first read the explicit size intent in the prompt, including pixels, ratios, orientation, resolution tiers (e.g., 4K / high-res), or named canvases. When a size intent is recognized, the planned specific size will be adopted; if there are no size requirements in the prompt or automatic judgment is unavailable, it will revert to the size of the first reference image. The final specific size will be normalized to multiples of 16, with long edge and total pixel limits before the request is submitted; for absolute control, please directly pass WIDTHxHEIGHT. After generation is complete, it will not automatically retry due to different output pixels to avoid incurring duplicate generation costs. About the n parameter The gpt-image-2 editing interface supports n > 1: it can return the corresponding number of editing results in one request. By default, gpt-image-2 and :reverse are billed based on the number of successful images; :official is billed based on the actual Token usage for the entire response summary (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, and for n>1, please use the default URL return. If some images fail to generate, only the successful parts will be returned and billed.

Here are two real examples from different perspectives 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, and the model will fetch that 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. It can be called 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 returned 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 is acceptable, 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 (a wooden bookshelf generated using 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 original multipart/form-data upload method is still applicable, just change 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 also connects to /openai/images/edits in editing scenarios, just change model to any one from 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 at retaining structure, text, and style

Important: Parameter Support Range Nano Banana connects to the OpenAI protocol through an adaptation layer, supporting only 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 directly passed as an image URL string through form fields.
• Parameters like mask, size, response_format, etc., are not supported; if filled, they will be ignored. n > 1 is supported (1–10), and will return and bill for the corresponding number of edit 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, see the section Asynchronous Callback below for details.

¶ 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 contents, one is authorization, which can be selected directly from the dropdown list. Another parameter is model, which is the model category we choose to use from the OpenAI official website, here we mainly have 1 model, details can be found in the models we provide. Another parameter is prompt, which is the prompt we input to generate the image. The last parameter is image, which is the path of the image to be edited, as shown in the image below:

Tip: image[] can appear multiple times to upload multiple reference images, for example, -F "image[]=@a.png" -F "image[]=@b.png", the GPT Image series model supports up to 16 images (each not exceeding 50MB, formats are png/webp/jpg). Exceeding the number will return 400.

The equivalent Python sample call code for the same effect:

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)

When using Python to call, we need to import two environment variables first, one is OPENAI_BASE_URL, which can be set to https://api.acedata.cloud/openai, and the other is the credential variable OPENAI_API_KEY, this value is obtained from authorization, and can be set using the following command in Mac OS:

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, the specific result is as follows:

In this way, we have completed the editing operation on the image. Currently, the Edits API supports two models: `gpt-image-1` and `gpt-image-2`, among which `gpt-image-2` is the recommended model to use. For more details, see the section [GPT-Image-2 Model](#gpt-image-2-模型).

¶ 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 as follows: when the client initiates a request, an additional callback_url field is specified. After the client makes 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 image editing will be sent to the client's 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 demonstration purposes, we use a public Webhook sample site https://webhook.site/, where you can open the site to 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, which is 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. The task can be associated 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 this API. If you have any questions, please feel free to contact our technical support team.