Skip to main content
OpenAI image editing service allows you to input any number of images and instructions, outputting modified images. This document mainly describes the usage process of the OpenAI Images Edits API, enabling us to easily utilize the official OpenAI image editing features.

​
Application Process

To use the OpenAI Images Edits API, you can first visit the OpenAI Images Edits API page and click the “Acquire” button to obtain the credentials needed for the request: If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. Upon the first application, there will be a free quota provided, allowing you to use the API for free.

​
Basic Usage

Next, you can use code to make calls; below is an example 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 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 official 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:

A Python example with the same calling 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, we need to import two environment variables: one OPENAI_BASE_URL, which can be set to https://api.acedata.cloud/openai, and another variable for the credential 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, with the specific result as follows:

Thus, we have completed the image editing operation. Currently, the official Edits task only supports two models: dall-e-2 and gpt-image-1.

​
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 POST JSON format, 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/; opening this site will give you 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 immediately receive a result, as follows: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
After a moment, we can observe the result of the edited image at the Webhook URL, with the content 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..."
      }
    ]
  }
}
You can see that the result contains a task_id field, and the data field includes the same image editing result as the synchronous call, allowing the task to 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 the API. If you have any questions, please feel free to contact our technical support team.