# GPT-Image-2.5

This file is the focused AI-readable context for one UniAll documentation page.

URL: https://docs.uniall.ai/models/image/gpt-image-2-5
Locale: en
Markdown: https://docs.uniall.ai/ai/pages/models/image/gpt-image-2-5.md
Description: Generate or edit images with GPT Image 2.5 through UniAll synchronous image APIs.

Agent guidance:
- Use this page when the user is asking about this specific route or model capability.
- Preserve endpoint paths, JSON keys, model IDs, and placeholder values exactly.
- `{BASE_URL}` means `https://api.uniall.ai`; treat `sk-***` and `task_xxx` as safe placeholders, not real secrets.

## Page Markdown

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

GPT Image 2.5 provides two public model IDs:

- `gpt-image-2.5-flare`
- `gpt-image-2.5-sunburst`

Both IDs use the same OpenAI-compatible synchronous image contract. Use `/v1/images/generations` for text-to-image requests and `/v1/images/edits` whenever the request includes reference images.

The models returned by `GET /v1/models` for your API key are the models currently available to your account.

## When To Use It

Use GPT Image 2.5 when you need:

- synchronous text-to-image generation;
- image editing with one or more reference images;
- explicit output size, quality, and format controls;
- URL or Base64 image responses.

## Endpoint

```http
GET /v1/models
POST /v1/images/generations
POST /v1/images/edits
```

The image endpoints wait for the provider result and return the generated image in the same response. They do not create a task that requires polling.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

The compatibility header below can also be used for authenticated requests:

```http
x-api-key: sk-***
```

## Model Availability

```bash
curl "{BASE_URL}/v1/models" \
  -H "Authorization: Bearer sk-***"
```

A successful response includes the model IDs visible to the current API key:

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2.5-flare",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2.5-sunburst",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    }
  ]
}
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`. |
| `prompt` | string | Yes | Generation or editing instruction. Maximum length: 32,000 characters. |
| `size` | string | No | `auto` or `WIDTHxHEIGHT`. Default: `auto`. |
| `quality` | string | No | `auto`, `low`, `medium`, `high`, `xhigh`, or `max`. Default: `auto`. |
| `n` | integer | No | Number of output images. Default: `1`; range: `1` to `10`. |
| `output_format` | string | No | `png`, `jpeg`, or `webp`. Default: `png`. |
| `response_format` | string | No | `url` or `b64_json`. Default: `b64_json`. |
| `images` | array | Conditional | JSON reference images for `/v1/images/edits`. Each item uses `{"image_url":"..."}`. |
| `mask` | object | No | JSON mask for `/v1/images/edits`. Uses `{"image_url":"..."}` and applies to the first reference image. |

## Size Rules

For an explicit `WIDTHxHEIGHT` value:

- width and height must be positive multiples of `16`;
- the longest edge must not exceed `3840` pixels;
- the aspect ratio must not exceed `3:1`;
- total pixels must be between `655,360` and `8,294,400`.

Use `auto` when the output size should be selected from the request and reference-image context.

## Text-To-Image Example

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A red ceramic cup on a clean white table, studio product photo, no text",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## JSON Image Editing Example

Use `/v1/images/edits` when the request includes one or more reference images.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Keep the product shape and replace the background with a bright studio scene",
    "images": [
      {"image_url": "https://example.com/product.png"}
    ],
    "size": "auto",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

Each JSON reference uses an HTTP(S) image URL or a PNG, JPEG, or WebP Base64 Data URL. A request can include up to 16 reference images.

## Base64 Image Editing Example

For JSON editing requests, pass the reference image as a complete Base64 Data URL in `images[].image_url`.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Keep the product shape and replace the background with a bright studio scene",
    "images": [
      {
        "image_url": "data:image/png;base64,BASE64_IMAGE_DATA"
      }
    ],
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

The Data URL must include its MIME prefix, such as `data:image/png;base64,...`, `data:image/jpeg;base64,...`, or `data:image/webp;base64,...`.

## Multipart Image Editing

Use multipart when the source image is a local file. Repeat `image[]` for multiple references.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=Keep the subject and change the background to pale blue" \
  -F "image[]=@product.png" \
  -F "response_format=url"
```

A multipart mask can be sent as `mask=@mask.png`. The mask must be a PNG with an alpha channel, smaller than 4 MB, and have the same dimensions as the first reference image.

## Response Example

```json
{
  "created": 1789121337,
  "size": "1024x1024",
  "output_format": "png",
  "data": [
    {
      "url": "https://api.uniall.ai/generated-media/example.png"
    }
  ],
  "usage": {
    "prompt_tokens": 23,
    "completion_tokens": 425,
    "total_tokens": 448,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 23,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "usage_source": "upstream_response"
  }
}
```

When `response_format` is `b64_json`, each `data` item contains `b64_json` instead of `url`. The value is raw Base64 data without a `data:image/...;base64,` prefix.

## Base64 Response Example

Set `response_format` to `b64_json` when your application needs the image bytes in the JSON response.

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A red ceramic cup on a clean white table, studio product photo",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "response_format": "b64_json"
  }'
```

The response contains raw Base64 data without a `data:image/...;base64,` prefix:

```json
{
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

## Related Pages

- [Image Generation Overview](/models/image/overview)
- [GPT-Image-2](/models/image/gpt-image-2)
- [Models](/models)