GPT Image 2 — Edit


Model ID	`openai/gpt-image-2-edit`
Family	`gpt_image_2`
Task	`edit`
Provider	OpenAI
Modality	Image

Parameters

string

required

Natural-language instruction describing the edit. Maximum 32,000 characters.

string[]

required

One to sixteen reference image URLs to edit. Must be publicly reachable HTTPS URLs. All references are sent to the model — combine several product shots into one scene, or ground an edit in multiple views of the same subject. Reference images are billed as input tokens ($8 / 1M, 5% off) — each is tokenized by its pixel dimensions. See Pricing.

string

Optional mask image URL — transparent regions are repainted, opaque regions kept.

string

Render quality tier — directly affects cost. One of low, medium, high. Default: medium.

string

Output dimensions. One of 1024x1024, 1024x1536, 1536x1024, 1024x2048, 2048x1024, 688x2048, 2048x688, 880x2048, 2048x880, 1152x2048, 2048x1152, 1360x2048, 2048x1360, 1536x2048, 2048x1536, 2048x2048, 2160x3840, 3840x2160, auto. Default: 1024x1024.

integer

Number of images to generate. Range: 1–10. Default: 1. Each image is billed its own output cost, so n images cost n× (you’re charged only for images actually returned).

string

Background style. One of transparent, opaque, auto. Default: auto. transparent renders a true alpha channel and requires output_format png (the default) or webp — JPEG has no transparency.

string

Output file format. One of png, jpeg, webp. Default: png.

string

HTTPS endpoint to POST the finished generation to. Delivered after the image is mirrored to storage, so it carries the final URL. Private and loopback addresses are rejected.

boolean

Stream the result over SSE instead of answering immediately. Default: false. See Getting the result.

Getting the result

Generation takes roughly 20-120 seconds, so the request does not return the image. It returns the generation id right away:

{ "id": "a62fc882-...", "object": "image.generation", "status": "pending", "model": "openai/gpt-image-2-t2i" }

Collect the result in whichever of these three suits you.

Poll (default)

curl https://routerbase.com/v1/images/generations/a62fc882-... \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx"

status becomes success (read data[0].url) or failed (read error_message).

Webhook

Pass callback_url and we POST it once the image is stored:

{ "task_id": "a62fc882-...", "status": "success", "result_urls": ["https://..."], "error_message": null }

The URL must be publicly reachable over HTTPS; loopback, private-range and cloud-metadata addresses are refused.

Stream

Pass "stream": true for text/event-stream:

data: {"type":"image_generation.created","id":"a62fc882-...","status":"pending"}

data: {"type":"image_generation.completed","id":"a62fc882-...","status":"success","data":[{"url":"https://..."}]}

data: [DONE]

The first event arrives immediately, so you hold the id even if the connection drops later. Streaming keeps the connection open for the whole generation — if your client or a proxy times out below ~2 minutes, prefer polling or a webhook. There is no progressive preview: the upstream sends the image only when it is finished, so partial_images has no effect.

Send an Idempotency-Key header with every request. If the connection drops, repeating the request with the same key returns the original generation instead of creating and charging a second one. See Idempotency.

Example

curl -X POST https://routerbase.com/v1/images/generations \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2-edit",
    "prompt": "Replace the sky with a starlit night",
    "image_urls": ["https://example.com/landscape.png"],
    "quality": "high"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-rb-xxxxxxxxxxxx",
    base_url="https://routerbase.com/v1",
)

# Edits go through images.generate with image_urls — RouterBase's edit
# endpoint takes reference URLs as JSON (client.images.edit posts
# multipart to /v1/images/edits, which this API does not serve).
img = client.images.generate(
    model="openai/gpt-image-2-edit",
    prompt="Replace the sky with a starlit night",
    extra_body={
        "image_urls": ["https://example.com/landscape.png"],
        "quality": "high",
    },
)
print(img.data[0].url)

Multiple reference images

Pass several URLs in image_urls and every one of them reaches the model — compose separate product shots into one scene, or ground an edit in multiple views of the same subject. Each reference is billed as input tokens by its pixel dimensions.

cURL

curl -X POST https://routerbase.com/v1/images/generations \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2-edit",
    "prompt": "Create a photorealistic gift basket containing all of these products",
    "image_urls": [
      "https://example.com/body-lotion.png",
      "https://example.com/bath-bomb.png",
      "https://example.com/soap.png"
    ],
    "quality": "high"
  }'

Get Started

API Reference

GPT Image 2 — Edit

Parameters

Getting the result

Poll (default)

Webhook

Stream

Example

Multiple reference images

​Parameters

​Getting the result

​Poll (default)

​Webhook

​Stream

​Example

​Multiple reference images

Parameters

Getting the result

Poll (default)

Webhook

Stream

Example

Multiple reference images