> ## 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.6 · Image-to-image

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

## Introduction

GPT-Image-2.6 **Flare** and **Sunburst** both edit reference images from text instructions. This page covers `POST /v1/images/edits` for recoloring, background replacement, restyling, inpainting, and blending multiple references.

Provide reference images and describe both what should change and what should stay in `prompt`. Guide local edits with either a **mask** or a transparent **markup overlay**, never both. You can also generate a GIF from still references. Requests accept JSON image references or multipart file uploads, as shown below.

Use Flare for quick iterations and Sunburst for detail, layout, and edit accuracy. Adjust rendering with `quality` and planning with the independent `complexity` setting. For focused edits, start with lower complexity and check that surrounding content remains as intended.

### Choose a model

| Model ID | Best suited for |
| - | - |
| `gpt-image-2.6-flare` | Fast iteration and interactive generation |
| `gpt-image-2.6-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.6-flare or gpt-image-2.6-sunburst |
| `prompt` | string | Required description or edit instruction; up to 32,000 characters |
| `quality` | string | auto / low / medium / high / xhigh / max; default auto |
| `complexity` | string | low / medium / high; default high. Planning effort independent of quality |
| `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 / gif |
| `output_compression` | integer | 0–100 for jpeg/webp only; unavailable for GIF |
| `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. Unsupported for GIF |
| `partial_images` | integer | Raster streaming only: 0–3, default 0. Requested preview count; fewer previews may arrive. Unsupported for GIF |
| `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 and GIF |
| `frame_count` | integer | GIF only: 2–16; default 9 |
| `frame_duration_ms` | integer | GIF only: default 200; guide recommends 20–2000ms rounded to 10ms |

### 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]
>
> JSON examples use the official OpenAI kitchen image; the markup example uses its matching official transparent overlay. Copy the JSON bodies directly. The multipart example downloads the same image before uploading it. The gateway does not support file\_id; testing returned HTTP 500 (convert\_request\_failed), so do not assume HTTP 400.

### 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.6-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "complexity": "low",
  "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.6-flare" \
  -F "prompt=Change the vase to blue. Keep everything else unchanged." \
  -F "image[]=@kitchen.webp" \
  -F "complexity=low"
```

### 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.6-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "complexity": "low",
  "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"
  }
}'
```

### Animated GIF

```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.6-flare",
  "prompt": "Animate the kitchen curtains gently moving in a breeze. Keep the camera still and make a seamless loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

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.6-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.6-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

GIF size describes each frame. Frame count, n, and model pixel budgets jointly constrain it. Prefer auto; reduce frames or dimensions if limits are exceeded.

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.

SVG output is not provided by this edit endpoint. Use the [generation endpoint](https://docs.gravitex.ai/en/api-reference/endpoint/gpt-image-2.6/generations.md) for SVG.

GIF requires preview access. Omit mask, stream, partial\_images, and custom output\_compression. Frame count, frame dimensions, and n share the request pixel budget; reduce them or use size=auto if limits are exceeded.

Complexity has no separate fee, but can affect latency and results. Lower complexity does not guarantee a fixed response time or per-image cost.

## 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.

Decode data\[].b64\_json into the selected file format. usage reports token consumption. Prices below are OpenAI standard rates, not a GravitexAI quote; 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.6-flare)
* [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.6-sunburst)
* [Pricing](https://developers.openai.com/api/docs/pricing)


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