# GPT Image 2.5 Sunburst · 图生图

API 模型 ID 为 `gpt-image-2.5-sunburst`。本文说明平台的实际契约，调用前请核对实时目录中的可用性。

OpenAI 将文生图（Generations）和参考图编辑（Edits）分别组织。平台异步任务接口沿用同一端点，由输入内容区分两种场景。

| 文档 | 官方 Image API | 平台接口 |
| --- | --- | --- |
| [文生图](/zh/docs/models/gpt-image-2.5-sunburst/generations) | `POST /v1/images/generations` | `POST /v1/tasks` · `input.prompt` |
| [图生图](/zh/docs/models/gpt-image-2.5-sunburst/edits) | `POST /v1/images/edits` | `POST /v1/tasks` · `input.prompt` + `input.images` |

把 https://example.com/reference.png 换成可公开访问的参考图 URL。这里使用平台的 images 数组，不是官方 multipart 的 image 字段。

## 请求示例

平台地址在构建时填入，运行前设置 API_KEY 为服务端密钥。

```bash
curl "https://newrouters.com/v1/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  --data '{
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "quality": "medium",
    "resolution": "1k",
    "output_format": "jpeg",
    "prompt": "Keep the subject and replace the background with a quiet garden",
    "images": [
      "https://example.com/reference.png"
    ]
  }
}'
```

## 查询结果

创建响应表示任务已受理，不是最终结果。用返回的 ID 替换 TASK_ID，轮询至 succeeded 或 failed。

```bash
curl "https://newrouters.com/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

成功查看 result，失败查看 error。上游结果未知时保留原任务 ID，不盲目重复提交付费生成。

## 参数说明

| 字段 | 类型 | 要求 | 默认值 | 限制 |
| --- | --- | --- | --- | --- |
| `size` | string | 可选 | — | 原生尺寸参数，优先于 resolution 和 aspect_ratio；`auto` 或 `宽x高`。宽高为 16 倍数、最长边 ≤ 3840、长短边比 ≤ 3、总像素 655,360–8,294,400；详见[尺寸说明](#尺寸限制size) |
| `images` | array | 本场景必填 | — | 最多项数 20 |
| `prompt` | string | 必填 | — | 最大长度 100000 |
| `quality` | enum | 可选 | `"medium"` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` |
| `background` | enum | 可选 | — | `auto`, `transparent`, `opaque` |
| `resolution` | enum | 可选 | `"1k"` | `1k`, `2k`, `4k`; 传入 `size` 时不生效 |
| `aspect_ratio` | enum | 可选 | — | `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16` |
| `output_format` | enum | 可选 | `"jpeg"` | `png`, `jpeg`, `webp` |

<!-- gpt-image-size:start -->
## 尺寸限制（size）

以下官方输出尺寸规则适用于 GPT Image 2、GPT Image 2.5 Sunburst 和 Flare，文生图与图生图使用同一组规则。size 可为 auto，或 WIDTHxHEIGHT 格式的像素尺寸。

| 条件 | 官方限制 |
| --- | --- |
| 宽和高 | 均为 16 的正整数倍 |
| 最长边 | ≤ 3840 px |
| 长边 / 短边 | ≤ 3 |
| 总像素（宽 × 高） | 655,360–8,294,400 |

上述条件必须同时满足。官方将超过 2560x1440 的分辨率标为实验性。

### 尺寸示例

| size | 是否符合官方规则 | 说明 |
| --- | --- | --- |
| 1024x1024 | 合法 | 常用正方形 |
| 1536x864 | 合法 | 16:9 横图 |
| 2880x2880 | 合法 | 正方形总像素恰好达到上限 |
| 3840x2160 / 2160x3840 | 合法 | 横向 / 纵向 4K，总像素达到上限 |
| 1537x864 | 非法 | 宽度不是 16 的倍数 |
| 512x512 | 非法 | 总像素低于下限 |
| 3072x768 | 非法 | 长短边比为 4:1，超过 3:1 |
| 3840x3840 | 非法 | 总像素超过上限 |
| 4096x4096 | 非法 | 同时超过边长和总像素上限 |

[官方尺寸规范](https://developers.openai.com/api/docs/guides/image-generation#size-and-quality-options) · [GPT Image 2 规则](https://developers.openai.com/api/docs/guides/image-generation#earlier-gpt-image-models)

### 平台尺寸参数

传入 `size` 后，`resolution` 和 `aspect_ratio` 不生效。`size=auto`（包括同时省略 `size` 和 `aspect_ratio`）按 2K 计费，即使同时传入 `resolution=4k` 也不会按 4K 计费或保证 4K 输出。具体 `WxH` 按 `size` 推导计价档位。需要指定分辨率档位时，请省略 `size`，使用 `resolution` + `aspect_ratio`。

resolution 是平台档位名称，4k 不等于 4096x4096。当前共用换算中，4k + 1:1 对应 2880x2880，4k + 16:9 对应 3840x2160；实际产物尺寸以渠道结果为准。平台同步 /v1/images/generations、/v1/images/edits 的 size 会转换到现有分辨率档位及最接近的支持比例，不能保证任意自定义 size 都按原值输出。

| resolution | aspect_ratio | 共用换算后的 size |
| --- | --- | --- |
| 1k | 1:1 | 1024x1024 |
| 2k | 1:1 | 2048x2048 |
| 4k | 1:1 | 2880x2880 |
| 4k | 16:9 | 3840x2160 |
| 4k | 9:16 | 2160x3840 |

按平台推荐参数创建 4K 正方形任务时，input 中填写如下；不要同时传 size。

```json
{
  "resolution": "4k",
  "aspect_ratio": "1:1"
}
```

<!-- gpt-image-size:end -->

## 与官方的对应关系

对应官方 POST /v1/images/edits 场景。本文实际提交平台的异步 POST /v1/tasks 请求。 只使用平台 schema 支持的字段，不默认兼容全部官方参数。

[官方 Image API 指南](https://developers.openai.com/api/docs/guides/image-generation)











<!-- official-reference:start -->
## 官方来源与模型身份

核对日期: 2026-09-27 · 平台模型: `gpt-image-2.5-sunburst` · 官方对应: `gpt-image-2.5-sunburst`

- [gpt-image-2.5-sunburst official reference](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)
- [OpenAI Images API: generations / edits](https://developers.openai.com/api/docs/guides/image-generation)
<!-- official-reference:end -->

## 计费与排错

接入时核对当前可用性、契约和账号价格。排错时保留请求 ID 与消费凭据。 [完整 API 参考](/zh/docs/api)

## 多语言请求示例

### JavaScript

```javascript
const apiBaseUrl = "https://newrouters.com";
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY in your server environment");

const response = await fetch(apiBaseUrl + "/v1/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + apiKey
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "quality": "medium",
    "resolution": "2k",
    "output_format": "jpeg",
    "prompt": "Keep the subject and replace the background with a quiet garden",
    "images": [
      "https://example.com/reference.png"
    ],
    "size": "auto"
  }
})
});

const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
```

### Python

```python
import json
import os
from urllib.request import Request, urlopen

api_base_url = "https://newrouters.com"
api_key = os.environ["API_KEY"]
body = json.loads("{\"model\":\"gpt-image-2.5-sunburst\",\"input\":{\"quality\":\"medium\",\"resolution\":\"2k\",\"output_format\":\"jpeg\",\"prompt\":\"Keep the subject and replace the background with a quiet garden\",\"images\":[\"https://example.com/reference.png\"],\"size\":\"auto\"}}")

request = Request(
    api_base_url + "/v1/tasks",
    data=json.dumps(body).encode("utf-8"),
    headers={
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key
    },
    method="POST",
)
with urlopen(request) as response:
    print(json.load(response))
```

## 响应字段节选（示意值）

### HTTP 202

```json
{
  "id": "TASK_ID",
  "status": "pending",
  "model": "gpt-image-2.5-sunburst",
  "result": null,
  "error": null
}
```

### HTTP 200

```json
{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "gpt-image-2.5-sunburst",
  "result": {
    "assets": [
      "https://example.com/output.png"
    ]
  },
  "error": null
}
```