# GPT-Image-2.5

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

URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2-5
Locale: zh-CN
Markdown: https://docs.uniall.ai/ai/pages/zh-CN/models/image/gpt-image-2-5.md
Description: 通过 UniAI 同步图像接口调用 GPT Image 2.5 生成和编辑图片。

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

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

GPT Image 2.5 提供两个公开模型 ID：

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

两个模型使用相同的 OpenAI 兼容同步图像契约。文生图使用 `/v1/images/generations`；请求包含参考图时，使用 `/v1/images/edits`。

当前 API Key 可用的模型，以 `GET /v1/models` 返回的模型列表为准。

## 适用场景

GPT Image 2.5 适合：

- 同步文生图；
- 使用一张或多张参考图进行图片编辑；
- 调整输出尺寸、质量和格式；
- 获取 URL 或 Base64 图片响应。

## 接口

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

图片接口会等待上游结果，并在同一个响应中返回生成图片，不会创建需要轮询的任务。

## 鉴权

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

也可以使用以下兼容 Header：

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

## 模型可用性

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

成功响应会列出当前 API Key 可见的模型 ID：

```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"
    }
  ]
}
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。 |
| `prompt` | string | 是 | 生成或编辑指令，最长 32,000 个字符。 |
| `size` | string | 否 | `auto` 或 `WIDTHxHEIGHT`，默认 `auto`。 |
| `quality` | string | 否 | `auto`、`low`、`medium`、`high`、`xhigh` 或 `max`，默认 `auto`。 |
| `n` | integer | 否 | 输出图片数量，默认 `1`，范围为 `1` 到 `10`。 |
| `output_format` | string | 否 | `png`、`jpeg` 或 `webp`，默认 `png`。 |
| `response_format` | string | 否 | `url` 或 `b64_json`，默认 `b64_json`。 |
| `images` | array | 条件必填 | `/v1/images/edits` 的 JSON 参考图数组，每项使用 `{"image_url":"..."}`。 |
| `mask` | object | 否 | `/v1/images/edits` 的 JSON 蒙版，使用 `{"image_url":"..."}`，作用于第一张参考图。 |

## 尺寸规则

显式传入 `WIDTHxHEIGHT` 时：

- 宽和高必须是正整数，且都是 `16` 的倍数；
- 长边不能超过 `3840` 像素；
- 宽高比不能超过 `3:1`；
- 总像素必须在 `655,360` 到 `8,294,400` 之间。

如果希望根据请求和参考图上下文自动选择尺寸，使用 `auto`。

## 文生图示例

```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": "白色桌面上的红色陶瓷杯，棚拍产品照片，不要文字",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## JSON 图片编辑示例

请求包含一张或多张参考图时，使用 `/v1/images/edits`。

```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": "保留产品主体，将背景替换为明亮的摄影棚场景",
    "images": [
      {"image_url": "https://example.com/product.png"}
    ],
    "size": "auto",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

每张 JSON 参考图使用 HTTP(S) 图片 URL，或 PNG、JPEG、WebP Base64 Data URL。单次请求最多可以传入 16 张参考图。

## Base64 图片编辑示例

使用 JSON 编辑请求时，将参考图作为完整的 Base64 Data URL 传入 `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": "保留产品主体，将背景替换为明亮的摄影棚场景",
    "images": [
      {
        "image_url": "data:image/png;base64,BASE64_IMAGE_DATA"
      }
    ],
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

Data URL 必须包含 MIME 前缀，例如 `data:image/png;base64,...`、`data:image/jpeg;base64,...` 或 `data:image/webp;base64,...`。

## multipart 图片编辑

本地文件建议使用 multipart。多张参考图可以重复传入 `image[]`。

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保留主体，将背景改成浅蓝色" \
  -F "image[]=@product.png" \
  -F "response_format=url"
```

multipart 蒙版可以使用 `mask=@mask.png`。蒙版必须是带 Alpha 通道的 PNG，小于 4 MB，并且与第一张参考图尺寸一致。

## 响应示例

```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"
  }
}
```

当 `response_format` 为 `b64_json` 时，每个 `data` 项返回 `b64_json` 而不是 `url`。该值是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀。

## Base64 响应示例

如果应用需要在 JSON 响应中直接获取图片字节，将 `response_format` 设置为 `b64_json`。

```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": "白色桌面上的红色陶瓷杯，棚拍产品照片",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "response_format": "b64_json"
  }'
```

响应中的 `b64_json` 是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀：

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

## 相关页面

- [图像生成概览](/zh-CN/models/image/overview)
- [GPT-Image-2](/zh-CN/models/image/gpt-image-2)
- [模型列表](/zh-CN/models)