GPT Image 2 / 2.5: generation and image editing

Choose the endpoint before writing the request: text-to-image uses /images/generations; image-to-image uses /images/edits with uploaded image files. Mentioning “reference image 1” in a prompt does not attach an image.

Models and endpoints

Model ID	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + image files
gpt-image-2.5-sunburst	/images/generations	/images/edits + image files
gpt-image-2.5-flare	/images/generations	/images/edits + image files

These are distinct model IDs. Change model explicitly when switching models; GPT Image 2.5 is not an alias of GPT Image 2. Check current availability and account pricing in the marketplace.

Operation	Method and endpoint	Request format
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / editing	POST https://apimaster.ai/v1/images/edits	multipart/form-data with actual image files
Asynchronous image editing	POST https://apimaster.ai/v1/images/edits/async	Same multipart files as edits; returns a task ID
Asynchronous text-to-image	POST https://apimaster.ai/v1/images/generations/async	JSON; returns a task ID
Query a task	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Bearer authentication

For a task response from image editing, use /images/edits/async. Upload the same files and fields as synchronous edits, then query /tasks/{task_id}. Do not move an editing request to generations/async. These task endpoints reuse the existing async contract: an asynchronous upstream can return its task promptly, while a synchronous upstream may finish the edit before the gateway returns a task ID. They are not a promise of immediate background execution. Do not use Chat Completions for these models.

Authentication and timeouts

Create an API key and send Authorization: Bearer YOUR_API_KEY. JSON generation requests use Content-Type: application/json. For file uploads, let cURL or your HTTP library generate the multipart boundary; do not manually set the Content-Type header.

Allow at least 180 seconds for basic requests, 300 seconds for higher resolution, and 600 seconds for demanding edits or high quality. A client timeout does not prove that the upstream request stopped. Avoid immediate duplicate submissions.

Text-to-image: JSON generation

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

For Sunburst or Flare, replace the model ID with gpt-image-2.5-sunburst or gpt-image-2.5-flare. Do not add reference images to this example; use the editing examples below.

Image-to-image: upload one reference

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Replace reference.png with an existing local image. The @ tells cURL to upload file bytes; image=reference.png sends only a filename string. This endpoint pattern also applies to gpt-image-2 and gpt-image-2.5-sunburst.

Image-to-image: upload multiple references

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Repeat the same image[] field for each file, in the order described by the prompt. n is the number of output images, not the number of references. Reference limits depend on the selected model and available route; do not assume a universal 16-image limit. Start with one reference and n=1, then add inputs as needed.

Python editing example

Install requests. This example uploads a real file and handles both URL and base64 image responses.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

For multiple files, pass a list of repeated ("image[]", (filename, file_object, mime_type)) entries to files. Keep each file open until the request completes.

Asynchronous image editing

Use this endpoint with GPT Image 2, Sunburst or Flare when your application consumes task IDs. File upload rules, reference ordering, capability limits and authentication are the same as synchronous edits.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

The submission returns data[0].task_id. Poll using the same model ID:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

A completed tracked task has this shape; every generated image is included:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

The task belongs to the submitting account. Query it with a valid API key for that account. A failed submission returns an error rather than a usable task; once a task ID has been returned, keep polling that task instead of submitting the edit again. See the polling status table below.

Existing URL or base64 integrations

If your input is a URL, download the image in your application and upload its bytes to /images/edits. If it is a base64 data URI, decode the payload into a file or byte buffer and upload it. Do not submit the URL or base64 text as if it were a file upload.

Some GPT Image 2 routes support the extension image_urls on generations. That is not a portable image-editing contract and must not be assumed to work with GPT Image 2.5. New integrations should use the multipart edits examples above. A JSON request containing image_urls, image or images is not equivalent to uploading files to edits.

Parameters and capability limits

Field	Usage
model	Required; use one exact model ID from the table above
prompt	Required; describe the result and reference order
image / image[]	Actual uploaded files for edits; use PNG or JPEG for the basic examples
n	Output image count; start with 1; maximum depends on the route
size	Optional; 1024x1024 is the basic example; other pixel dimensions or aspect ratios depend on the route
resolution	Optional route-specific extension such as 1k, 2k, 4k; not every model/route supports every tier
quality	Optional; accepted values and cost depend on the route
background, output_format, output_compression	Optional; transparency and output encoding require route support
mask	GPT Image 2 only, when an available edits route supports uploaded masks; not supported by the current GPT Image 2.5 multipart handler

For GPT Image 2, mask support must be checked separately from ordinary reference editing. A compatible PNG mask must match the input dimensions and include an alpha channel. The current GPT Image 2.5 multipart endpoint rejects uploaded mask files; do not add a mask to the Sunburst or Flare examples above. Do not assume a JSON mask_url workaround is supported without checking the chosen route.

Only send optional fields you need. They can change the eligible routes and price; setting a default explicitly is not always equivalent to omitting it. No fixed pixel-size table or advanced-parameter list applies uniformly to all three model IDs. Actual pricing and supported capabilities follow the marketplace and the request response.

Synchronous responses

A successful generation or edit returns image entries in data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Depending on the route and output format, an entry may instead contain b64_json. Decode it to image bytes. Download temporary result URLs promptly. An HTTP 200 response or an image count alone does not prove that reference details were preserved; inspect the result against the input.

Asynchronous tasks: submission and polling

For text-to-image, submit JSON without reference images to generations/async. For image editing, use the multipart edits/async example above. Both use the same task query endpoint:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

The submission envelope normally reports submitted; an upstream may already report a completion state. The first poll can already be complete. A task ID does not guarantee an immediate response: if the selected upstream is synchronous, the platform waits for generation to finish before returning the task. Keep a sufficient submission timeout.

Poll with the same model ID used for submission:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Task status	Action
pending, submitted, processing, in_progress	Wait; query again after 3–5 seconds
succeeded, success, completed	Read every entry in data.result.images; tracked tasks use a string url, while legacy upstream responses may use a URL array
failed, error, cancelled	Stop polling and inspect the error

Use a finite overall polling deadline, such as 10 minutes. If it expires, retain the task ID for later checks instead of creating another paid task automatically. Task query responses and synchronous image responses have different structures.

Troubleshooting reference images

1. Verify the actual request path is /v1/images/edits or /v1/images/edits/async, not generations or generations/async.
2. Verify multipart contains file bytes under image or repeated image[], with a generated boundary. Prompt text, filenames and reference counts do not replace files.
3. Check the exact model ID. A GPT Image 2 extension is not automatically supported by Sunburst or Flare.
4. If task/log details show no preview, do not conclude that no image was sent: logs can omit base64 data and uploaded file contents. Conversely, a logged reference count does not establish that an upstream used the images.
5. Test with a simple reference containing distinctive lettering or shapes, and ask for a background change without describing those details. Compare the output visually.
6. For support, retain the request ID (X-Oneapi-Request-Id), task ID if present, model, endpoint, timestamp, sanitized request fields and reference images. Never share your API key.

For a 400 response, inspect endpoint and parameter compatibility; 401 indicates authentication failure; 429 indicates a rate/quota limit. For timeouts or upstream failures, retain the request/task ID and check the existing task or usage record before resubmitting.