> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routerbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT Image 2 — Edit
> Edit images with natural-language prompts using OpenAI GPT Image 2.
| | |
| ------------ | ------------------------- |
| **Model ID** | `openai/gpt-image-2-edit` |
| **Family** | `gpt_image_2` |
| **Task** | `edit` |
| **Provider** | OpenAI |
| **Modality** | Image |
## Parameters
Natural-language instruction describing the edit. Maximum 32,000 characters.
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](/openai-gpt-image-2-api/quickstart#pricing).
Optional mask image URL — transparent regions are repainted, opaque regions kept.
Render quality tier — directly affects cost. One of `low`, `medium`, `high`. Default: `medium`.
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`.
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).
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.
Output file format. One of `png`, `jpeg`, `webp`. Default: `png`.
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.
Stream the result over SSE instead of answering immediately. Default: `false`.
See [Getting the result](#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:
```json theme={null}
{ "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)
```bash theme={null}
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:
```json theme={null}
{ "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](/essentials/idempotency).
## Example
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
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.
```bash cURL theme={null}
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"
}'
```