> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT-Image-2.5 · Image-to-image

> GPT-Image-2.5 Flare / Sunburst · POST /v1/images/edits

## Introduction

GPT-Image-2.5 **Flare** and **Sunburst** edit reference images from text instructions. Use `POST /v1/images/edits` for background replacement, recoloring, restyling, inpainting, and multiple references.

Describe what should change and what should remain in prompt. Provide JSON image references or multipart uploads. Use either mask or a transparent markup overlay for local edits, never both. Choose Flare for quick iteration and Sunburst when detail and editing precision matter most.

### Choose a model

| Model ID | Best suited for |
| - | - |
| `gpt-image-2.5-flare` | Fast iteration and interactive generation |
| `gpt-image-2.5-sunburst` | Detailed visual work, complex layouts, and precise edits |

Both models use the endpoints, parameters, and response structure documented here. Examples use Flare; switch to Sunburst by replacing model. Set other fields for your workload.

## Authentication

**Authorization** `string` *required*

Bearer \$GRAVITEX\_API\_KEY

**Content-Type** `string` *required*

application/json / multipart/form-data

## Request parameters

| Parameter | Type | Description |
| - | - | - |
| `model` | string | Required: gpt-image-2.5-flare or gpt-image-2.5-sunburst |
| `prompt` | string | Required description or edit instruction; up to 32,000 characters |
| `quality` | string | auto / low / medium / high / xhigh / max; default auto |
| `size` | string | auto or WxH with dimensions divisible by 16; model size and pixel budgets apply |
| `n` | integer | 1–10; default 1 |
| `background` | string | auto / opaque / transparent; use png or webp for transparent raster output |
| `output_format` | string | png / jpeg / webp; default png |
| `output_compression` | integer | 0–100, default 100; JPEG / WebP only |
| `moderation` | string | auto / low; default auto |
| `safety_identifier` | string | Stable hashed end-user identifier, up to 128 characters; replaces user |
| `stream` | boolean | Default false. When true, read SSE events instead of parsing a single JSON response |
| `partial_images` | integer | Raster streaming only: 0–3, default 0. Requested preview count; fewer previews may arrive |
| `images` / `image[]` | array / file | Required for JSON: at least one reference via `images: [{"image_url": "HTTPS URL or base64 data URI"}]`. Use image\[] files for multipart |
| `markup` | object / file | Optional transparent PNG overlay for the first reference image; mutually exclusive with mask |
| `mask` | object / file | Optional PNG mask with the same dimensions as the first reference and an alpha channel. Fully transparent areas indicate the edit region. Applies to the first image only; incompatible with markup |

### images / markup / mask

For JSON, use `images: [{"image_url": "https://..."}]` or base64 data URIs. For multipart, upload files as `image[]`. According to the platform integration note, the gateway converts JSON edits to multipart and does not support OpenAI file\_id references.

Use a transparent PNG markup layer matching the first input image after orientation. Include transparent pixels. JSON uses markup.image\_url; multipart uploads a markup file. Cannot be combined with mask.

Use mask to identify the edit region, or markup, never both. JSON accepts image\_url; multipart accepts a file.

## Request examples

Examples read the platform token from GRAVITEX\_API\_KEY in your terminal environment. For uploads, curl -F generates Content-Type and boundary automatically; do not manually set a bare multipart/form-data header.

> [!NOTE]
>
> Use accessible HTTPS URLs or base64 data URIs. The multipart example downloads the official image first. Platform integration guidance does not support OpenAI file\_id references; historical 2.6 status codes are not a guarantee for 2.5.

### JSON

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

### multipart/form-data

```bash theme={null}
curl --fail --location "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp" -o kitchen.webp

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change the vase to blue. Keep everything else unchanged." \
  -F "image[]=@kitchen.webp"
```

### Markup-guided editing

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ],
  "markup": {
    "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/markup-vase-overlay-gpt-image-2-6.png"
  }
}'
```

user is deprecated and retained for compatibility. Use safety\_identifier; a non-empty value takes precedence, otherwise the API falls back to user.

### Mask-guided inpainting

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Add a pink flamingo float in the masked pool area. Keep the rest of the room unchanged.",
  "images": [
    {
      "image_url": "https://cdn.openai.com/API/docs/images/sunlit_lounge.png"
    }
  ],
  "mask": {
    "image_url": "https://cdn.openai.com/API/docs/images/mask.png"
  },
  "quality": "medium"
}'
```

### Streaming

```bash theme={null}
curl --no-buffer https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "stream": true,
  "partial_images": 1,
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

## Limits and notes

The default size is auto. Explicit WxH dimensions must be multiples of 16, with aspect ratios between 1:3 and 3:1. The image-2 guide specifies a maximum edge of 3840px and 655,360–8,294,400 pixels; the 2.5 reference also requires model-specific edge and pixel limits. Confirm the actual 2.6 budget, especially for GIF, rather than assuming older limits.

The official Images API accepts **1–16** JSON edit references in PNG, JPEG, or WebP, each under **50MB**. A mask is a PNG with an alpha channel matching the first reference. Transparent areas guide editing; masks do not guarantee a pixel-exact hard boundary. Lack of gateway validation does not remove upstream limits.

This page includes explicitly documented GPT-Image-2.5 workflows. It does not assume the 2.6-specific complexity, GIF, or SVG guidance applies to 2.5. A field in a shared API schema does not guarantee support on every model or channel.

## Response example

This is a schematic non-streaming response. Image data and token counts are illustrative, not an actual generation. Decode b64\_json to the selected file format; do not save the Base64 text directly as an image.

```json theme={null}
{
  "created": 1794268800,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>"
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 824,
    "total_tokens": 924
  }
}
```

With stream=true, read SSE events for previews and the final image. Do not parse the entire response as one JSON object.

## Response and billing

Non-streaming examples return image bytes as b64\_json. Do not request response\_format=url expecting a hosted image URL. Equal token rates do not imply equal cost per image; use actual usage.

Returns data\[].b64\_json and usage. Decode Base64 before saving images. The following are OpenAI standard rates, not a GravitexAI quote.

Cached rates are official reference rates. For GPT Image 2 / 2.5, the guide limits cached input discounts to the Responses image tool; they do not apply to direct Images API calls, including edits. Platform billing follows the console.

| Type | USD / 1M tokens |
| - | - |
| Text input | \$5.00 |
| Cached text input | \$1.25 |
| Image input | \$8.00 |
| Cached image input | \$2.00 |
| Image output | \$30.00 |

## Official references

* [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
* [API Reference](https://developers.openai.com/api/reference/resources/images/methods/edit)
* [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)
* [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)
* [Pricing](https://developers.openai.com/api/docs/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.