GPT Image 2.5 图片接口

ReachAPI 同时通过 OpenAI 兼容的同步图片接口和 ReachAPI 异步任务接口提供 GPT Image 2.5 Flare 与 Sunburst。两个产品目前均处于内部预览阶段。

• gpt-image-2.5-flare：适合快速、高质量的日常图片生成。
• gpt-image-2.5-sunburst：适合更重视最高能力与编辑精度的工作流。

1. 选择接口

• 同步生成：POST https://direct.reachapi.ai/v1/images/generations
• 同步编辑：POST https://direct.reachapi.ai/v1/images/edits
• 异步任务：POST https://direct.reachapi.ai/v1/images/create
• 查询异步任务：GET https://direct.reachapi.ai/v1/tasks/{task_id}

调用方可以等待完整响应并希望使用 OpenAI 原生请求与响应结构时，使用同步 Image API。长耗时任务、URL 参考图、轮询、回调以及从 data[].url 获取托管结果时，使用异步任务 API。

两种方式使用相同的模型码和鉴权：

Authorization: Bearer YOUR_REACH_API_KEY

2. 同步 Image API

同步端点遵循 OpenAI Image API 契约。图片生成使用 JSON 请求；图片编辑使用一个或多个图片文件组成的原生 multipart 表单。

生成图片

curl -X POST "https://direct.reachapi.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "银色腕表置于深灰色石板上的精致产品摄影，柔和棚拍光线",
    "size": "1536x1024",
    "quality": "high",
    "background": "auto",
    "moderation": "auto",
    "output_format": "png"
  }'

编辑图片

curl -X POST "https://direct.reachapi.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保持腕表结构不变，只将背景替换为深色拉丝金属" \
  -F "image[]=@/path/to/watch.png" \
  -F "size=1536x1024" \
  -F "quality=xhigh" \
  -F "output_format=png"

不要手动设置 multipart boundary；客户端、SDK 或 curl -F 会自动生成。

同步接口契约

• 使用 model、prompt、size、quality、background、moderation、output_format 等扁平 OpenAI 字段，不要包在 input 中。
• 文生图使用 POST /v1/images/generations；基于文件的图片编辑使用 POST /v1/images/edits。
• 同步端点返回 OpenAI 原生 Images 响应，不返回 ReachAPI task_id，也不支持任务轮询或 callback_url。
• mask、多图编辑以及完整参数和响应契约以 OpenAI 兼容端点为准。

3. 异步任务 API

异步端点使用嵌套的 { "model": "...", "input": { ... } } 请求，并立即返回任务 ID。

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "callback_url": "https://example.com/reachapi/callback",
    "input": {
      "prompt": "银色腕表置于深灰色石板上的精致产品摄影，柔和棚拍光线",
      "resolution": "2k",
      "aspect_ratio": "3:2",
      "quality": "high",
      "background": "auto",
      "moderation": "auto",
      "output_format": "png"
    }
  }'

顶层参数

input 参数

background=transparent 不能与 output_format=jpeg 同时使用。

标准尺寸映射

所需组合不在表中时，请直接使用 input.size。

异步图片编辑

传入 input.image_urls 即可编辑或转换参考图：

{
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "prompt": "保持腕表结构不变，只将背景替换为深色拉丝金属",
    "image_urls": ["https://cdn.example.com/watch.png"],
    "resolution": "2k",
    "aspect_ratio": "3:2",
    "quality": "xhigh",
    "output_format": "png"
  }
}

任务结果与回调

提交成功后返回任务 ID：

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

轮询 GET /v1/tasks/{task_id}，直到状态变为 success 或 failed。成功任务会在 data[].url 返回图片，也可能附带 size 与 revised_prompt。

传入 callback_url 后，ReachAPI 会将终态响应发送至该 HTTPS 地址。单次投递超时 10 秒，首次失败后最多重试 2 次。

异步接口约束

• prompt 必填且不能为空。
• image_urls 最多接收 14 个 HTTPS URL；不支持 base64 图片输入。
• 该异步接口不开放 n > 1、mask、output_compression 和 user。
• 未传 size 时，resolution + aspect_ratio 必须命中标准映射表。

4. 价格

同步与异步方式使用相同的 GPT Image 2.5 Standard Token 价格。ReachAPI 仅计算以下三项：

Flare 与 Sunburst 使用相同的 Token 单价。模型、质量、尺寸、提示词和参考图都可能改变 Token 用量，因此单张图片的实际费用可能不同。

5. 可用性与官方参考

两个 GPT Image 2.5 模型码处于内部预览阶段，可能不会出现在 GET /v1/models。

• OpenAI 图片生成指南
• OpenAI Images API 参考
• OpenAI 价格