How to Build an Image Editing Workflow with gpt-image-2 and URL Inputs

July 17, 2026

Image editing APIs are most useful when they fit into an existing product pipeline instead of forcing every input image through a manual upload step.

This guide walks through a practical workflow for editing images with Ace Data Cloud's OpenAI Images Edits API, focusing on gpt-image-2, URL-based image input, multi-reference editing, SDK compatibility, and a simple asynchronous callback pattern.

What you can do

The OpenAI Images Edits API accepts one or more images plus a natural-language instruction, then returns the modified image. According to the integration guide, the same interface currently supports dall-e-2, gpt-image-1, gpt-image-2, and the nano-banana series models.

The most useful capability for builders is that gpt-image-2 can take an image URL directly in JSON. That matters when your source images already live in object storage, a CDN, a CMS, or a user-uploaded media library. Your backend can pass the URL to the API without downloading the file first.

Change a visual style while preserving the original composition.
Convert posters or infographics to a different color theme while keeping text readable.
Use several product images as references for a single composed result.
Request a specific output size such as 1024x1536, 2048x2048, or another valid WIDTHxHEIGHT value.

How it works

The endpoint used in the document is:

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

For JSON-based calls, send Authorization: Bearer {token} and Content-Type: application/json. The core fields are:

model: for this workflow, use gpt-image-2.
image: an image URL string, a base64 image string, or an array of image URLs.
prompt: the editing instruction.
size: auto, empty, or a WIDTHxHEIGHT value.

The guide notes that custom sizes must use width and height multiples of 16, with long side no greater than 3840 and total pixels no greater than 8,294,400. Recommended examples include 1024x1024, 1024x1536, 1792x1024, 2048x2048, 3840x2160, and 2160x3840.

Make a URL-based edit

Here is the minimal server-side pattern. The image is already hosted, so the request body can stay small and easy to log safely, as long as you never log the bearer token.

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

A successful response follows this shape:

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

For UI-heavy assets, the important part is the prompt. Be explicit about what should change and what must remain stable. For example: “change only the color scheme,” “keep the layout identical,” or “preserve the number and arrangement of items.”

Use multiple reference images

The image field can also be an array. The document notes that up to 16 reference images can be passed at the same time. This is useful for workflows such as product bundles, moodboard-based visuals, or combining several source assets into one output.

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://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)

In production, I would usually store the returned task_id, trace_id, prompt, source image URLs, and final data[0].url. That makes it much easier to reproduce a result or debug a user report later.

When to use base64 or multipart uploads

URL input is convenient, but it is not the only supported path. The guide states that image can also be base64, either as data:image/png;base64,... or raw base64. This is helpful when the image should not be uploaded to separate image hosting before editing.

import base64
import 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}"}
)

If you already use the official OpenAI Python SDK, the document also shows a compatible multipart-style path. Set OPENAI_BASE_URL to https://api.acedata.cloud/openai and OPENAI_API_KEY to your token, then call client.images.edit with model="gpt-image-2".

Plan for async jobs and limits

Image edits can take time, so the API supports a callback_url field. With a callback, the initial response returns a task_id, and the final result is sent to your webhook as a POST JSON payload containing the same task_id. This is the safer pattern for queues, background workers, and user-facing applications where you do not want an HTTP request open for too long.

One practical limitation to design around: for the default and reverse gpt-image-2 route, n > 1 is ignored and a single request returns one image. If your UI needs several candidates, send multiple requests concurrently and treat each result as a separate candidate.

For Nano Banana models on the same endpoint, the supported parameter range is narrower: model, prompt, and image. Parameters such as mask, n, size, and response_format are ignored for that series according to the guide.

Wrap-up

The main trick is to treat image editing as a backend workflow, not a one-off prompt box. Keep source images addressable, write prompts that separate “change this” from “preserve that,” store task metadata, and choose synchronous or callback mode based on your product latency needs.

For the full integration details, examples, supported models, response shapes, and error codes, read the OpenAI Images Edits API Integration Guide.

Search This Blog

AceDataCloud