GPT Image 2 / 2.5 Image Editing API

¶ 1. Obtain an API Key

Open the WorldAi Application List, enter an available application, and copy the API Key.

¶ 2. Edit Using an Image URL

Original image:

curl https://api.worldai.chat/openai/images/edits \
  -H "Authorization: Bearer your API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://cdn.acedata.cloud/assets/examples/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0-18240dc44b9c.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"
  }'

Successful response:

{
  "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://cdn.acedata.cloud/assets/examples/gpt-image/49848451-c624-4df9-9dc2-494018daaf4c_0-b6d780a732ca.png"
    }
  ],
  "usage": {
    "input_tokens": 775,
    "output_tokens": 1372,
    "total_tokens": 2147
  }
}

This is the editing result actually completed through WorldAi on September 8, 2026. The mug was changed to orange, the background was changed to dark navy blue, and the original composition and 1024×1536 size were preserved:

¶ 3. Upload a Local Image

Use multipart/form-data:

curl https://api.worldai.chat/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"

You can repeatedly provide image; the GPT Image series supports up to 16 reference images. The image in a JSON request can be a single URL or an array of URLs; local files are uploaded using multipart.

¶ Models and Billing Methods

Model	Applicable Scenarios and Billing Methods
gpt-image-2	Default reverse channel, fixed billing per successfully generated image
gpt-image-2:reverse	Explicitly selects the reverse channel, fixed billing per successfully generated image
gpt-image-2:official	Official API channel, higher stability, billed by actual Token usage
gpt-image-2.5-flare	Focuses on generation speed, fixed billing per successfully generated image
gpt-image-2.5-flare:official	Official API channel, higher stability and focuses on generation speed, billed by actual Token usage
gpt-image-2.5-sunburst	Focuses on high fidelity and fine-grained control, fixed billing per successfully generated image
gpt-image-2.5-sunburst:official	Official API channel, higher stability and focuses on high fidelity and fine-grained control, billed by actual Token usage

The listed prices for the official API channel are estimates before the request; the final amount is based on the actual Token usage in the response and usage records.

quality supports auto, low, medium, and high; only gpt-image-2.5-flare and gpt-image-2.5-sunburst (including :official variants) additionally support xhigh and max. This field can be passed for both JSON image URL editing and multipart file editing; official channels are billed by actual Token usage.

¶ 4. Use a Mask for Local Editing

The official Images Edit API specifies the area allowed to be modified through mask. WorldAi's :official models follow the same multipart contract:

• mask must be a PNG with an Alpha channel and must not exceed 4MB;
• The mask dimensions must exactly match the first image;
• Transparent pixels with an Alpha value of 0 indicate areas allowed to be edited, while non-transparent pixels indicate areas that should be preserved;
• RGB images that are only black and white but have no transparent channel cannot be used as valid masks;
• The prompt should describe the complete desired image, while clearly specifying the local modifications and the content that needs to remain unchanged.

First, generate a mask from the original image below. The example makes the central rectangle transparent, allowing the model to modify only that area:

from PIL import Image, ImageDraw

source = Image.open("input.png").convert("RGBA")
mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
width, height = source.size
draw.rectangle(
    (width // 4, height // 4, width * 3 // 4, height * 3 // 4),
    fill=(0, 0, 0, 0),
)
mask.save("mask.png")

Then upload the original image and mask together:

curl https://api.worldai.chat/openai/images/edits \
  -H "Authorization: Bearer your API Key" \
  -F "model=gpt-image-2:official" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=Keep the composition, lighting, and all objects outside the transparent mask unchanged. Inside the masked area, replace the empty tabletop with a small blue ceramic vase."

You can also use the images.edit calling method from the official OpenAI Python SDK; simply point base_url to WorldAi:

from openai import OpenAI

client = OpenAI(
    api_key="your API Key",
    base_url="https://api.worldai.chat/openai",
)

with open("input.png", "rb") as image, open("mask.png", "rb") as mask:
    result = client.images.edit(
        model="gpt-image-2:official",
        image=image,
        mask=mask,
        prompt=(
            "Keep the composition, lighting, and all objects outside the "
            "transparent mask unchanged. Inside the masked area, replace "
            "the empty tabletop with a small blue ceramic vase."
        ),
    )

print(result.data[0].url)

When using mask, the original image and the mask must be uploaded in the same multipart request via image=@input.png and mask=@mask.png, respectively. Do not mix a URL original image with a local mask file; pure URL editing requests do not support attaching an additional local mask file. The mask constrains the editing area, but the generation model may still naturally blend the edges; when strict boundaries are required, use clear Alpha edges and repeatedly specify in the prompt which content must remain unchanged.

The above calling method is consistent with the mask examples in the OpenAI Image Edit API and the official GPT Image Cookbook.

¶ 5. Common Parameters

Field	Description
model	gpt-image-2, gpt-image-2.5-flare (faster), or gpt-image-2.5-sunburst (higher fidelity and control); all three can use their corresponding :official variants, and gpt-image-2 also supports :reverse
image	JSON uses a single URL or an array of up to 16 URLs; multipart uses one or more image file fields. When using mask, local image files must be uploaded
mask	Optional PNG mask, limited to multipart file uploads; must include an Alpha channel, have the same dimensions as the first image, and not exceed 4MB
prompt	Editing instruction
size	auto or a WIDTHxHEIGHT that meets the restrictions
n	1–10; only 1 is supported when response_format=b64_json
response_format	url or b64_json
callback_url	Optional asynchronous callback URL

The size rules are the same as those of the generation endpoint: width and height must be multiples of 16, the long side must not exceed 3840, total pixels must be 655,360–8,294,400, and the aspect ratio must not exceed 3:1. When size is omitted or auto is used, the model selects the canvas based on the prompt and the first reference image.

gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, and gpt-image-2:reverse are billed by the number of successfully generated images; gpt-image-2:official, gpt-image-2.5-flare:official, and gpt-image-2.5-sunburst:official are billed according to the actual Tokens for text input, reference image input, and image output, subject to the usage record.

¶ 6. Asynchronous Callbacks and Troubleshooting

For long-running tasks, add the following to the request:

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

The asynchronous 200 response is {"task_id": "..."}; the final result is sent through a callback after completion. Synchronous requests return created and data.

Status	Check
400	Image format/count, parameter combinations, and size format; when using mask, check the PNG Alpha channel, the 4MB limit, and whether its dimensions match the first original image
401	API Key and Bearer Header
429	Request frequency
504	Switch to asynchronous callbacks

Error responses include trace_id. Provide this ID when reporting an issue; do not provide your API Key.

For complete fields and real-time enumerations, refer to the OpenAI Images Edits API page. For pure text-to-image generation, see GPT Image 2 / 2.5 Image Generation.