tokenfor.me

简体中文

English

简体中文

English

Appearance

GPT Image 2 / 2.5 接入说明 ​

本文介绍如何通过 OpenAI 兼容接口调用 GPT Image 2 / 2.5 系列生成图片，包括同步和异步两种方式。

支持的模型 ​

  • gpt-image-2-medium
  • gpt-image-2.5-flare
  • gpt-image-2.5-sunburst

以下同步和异步示例均使用 gpt-image-2.5-flare。切换模型时，将请求体中的 model 改为上面对应的模型 ID；使用 gpt-image-2-medium 时，删除 quality 字段即可，默认质量为 medium。接口路径、认证方式与异步轮询流程相同。模型可用性取决于 API Key 所属分组及所选站点的支持情况。

这三个模型在 CN GPT Standard 分组中使用相同的按张计费价格，详见模型报价；实际扣费以 API Key 所属分组的当前配置为准。

准备工作 ​

从控制台获取 API Base URL 和 API Key。下面的示例假设 Base URL 不包含末尾的 /v1：

bash
export API_BASE="https://<你的_API_Base_URL>"
export API_KEY="<你的_API_Key>"

所有请求都使用 Bearer Token 认证：

text
Authorization: Bearer <你的_API_Key>

如果控制台提供的 Base URL 已经以 /v1 结尾，请不要在请求地址中重复添加 /v1。

尺寸与质量控制 ​

同步和异步请求都可以在 JSON 请求体中设置 size。gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 可通过 quality 控制质量；gpt-image-2-medium 默认使用 medium，无需传 quality：

参数类型填写方式说明
sizestring宽x高，例如 1024x1024以像素指定目标尺寸，使用小写字母 x 分隔宽和高。
qualitystringlow、medium、high适用于 Flare / Sunburst，分别请求低、中、高质量档位；gpt-image-2-medium 无需传此参数。

size 可省略；需要指定尺寸时，请显式填写。Flare / Sunburst 的 quality 可省略，由所选渠道采用默认行为；下方 Flare 示例使用 quality: "high"。gpt-image-2-medium 默认质量为 medium，调用时无需填写 quality。

gpt-image-2-medium 请求体示例 ​

以下请求体可用于同步或异步生成，保留 size，无需传 quality：

json
{
  "model": "gpt-image-2-medium",
  "prompt": "一只戴着红色围巾的橘猫，坐在窗边看雪",
  "size": "1024x1024",
  "n": 1
}

标准尺寸表 ​

建议优先从下表选择 size。尺寸单位为像素，格式为 宽x高；请把单元格中的完整尺寸字符串填入请求体。

宽高比画布方向1K2K4K
1:1方形1024x10242048x20482880x2880
5:4横向1120x8962240x17923200x2560
4:3横向1152x8642304x17283264x2448
3:2横向1248x8322496x16643504x2336
16:9宽屏横向1280x7202560x14403840x2160
21:9超宽横向1456x6243024x12963696x1584
4:5纵向896x11201792x22402560x3200
3:4纵向864x11521728x23042448x3264
2:3纵向832x12481664x24962336x3504
9:16宽屏纵向720x12801440x25602160x3840

1K、2K、4K 是产品尺寸档位，最高档位名为 4K，不表示所有画布的长边都是 4096 像素。例如，4K 方图使用 2880x2880，4K 16:9 横图使用 3840x2160。

请求时传入具体尺寸，例如 "size": "2560x1440"，不要把档位名 2K 当作像素尺寸填写。任意非标准尺寸可能被拒绝或自动调整；如果业务要求精确像素，请核对下载图片的实际宽高。

质量与计费 ​

Flare / Sunburst 的 quality 用于请求质量档位；gpt-image-2-medium 默认使用 medium，无需传该参数。质量档位不会代替 size 设置图片分辨率；实际画质与耗时取决于模型、渠道和生成内容。CN GPT Standard 当前按图片尺寸档位计费，同一计费档位下，low、medium、high 使用相同的单张价格。其他分组以其当前报价为准。

同步生成 ​

同步接口会保持连接，直到图片生成完成或请求失败。适合调用端能够等待较长响应时间的场景。

接口 ​

text
POST /v1/images/generations

示例请求 ​

bash
curl "$API_BASE/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一只戴着红色围巾的橘猫，坐在窗边看雪",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

成功响应示例 ​

json
{
  "created": 1780000000,
  "data": [
    {
      "url": "https://<临时图片地址>"
    }
  ]
}

从 data[0].url 读取并下载图片。同步生成可能耗时较长；如果客户端、CDN 或反向代理容易发生长连接超时，建议改用异步方式。

异步生成 ​

异步接口会先创建任务并立即返回任务 ID，图片在后台继续生成。调用端随后轮询任务状态，不需要一直保持原请求连接。

第一步：提交任务 ​

text
POST /v1/images/generations/async
bash
curl "$API_BASE/v1/images/generations/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一只戴着红色围巾的橘猫，坐在窗边看雪",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

提交成功时返回 HTTP 202 Accepted：

json
{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "processing",
  "poll_url": "/v1/images/tasks/imgtask_example",
  "created_at": 1780000000,
  "expires_at": 1780086400
}

HTTP 202 只表示任务已被接受，不代表图片已经生成完成。请保存 task_id，并使用提交任务时的同一把 API Key 查询。

第二步：轮询任务状态 ​

text
GET /v1/images/tasks/{task_id}
bash
curl "$API_BASE/v1/images/tasks/imgtask_example" \
  -H "Authorization: Bearer $API_KEY"

建议每 3～5 秒查询一次。processing 表示仍在生成；遇到 completed 或 failed 后应停止轮询。查询任务状态不会重复计费。

完成响应示例 ​

json
{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "result": {
    "data": [
      {
        "url": "https://<24小时有效的签名图片地址>"
      }
    ]
  },
  "created_at": 1780000000,
  "completed_at": 1780000060,
  "expires_at": 1780086460
}

任务完成后，从 result.data[0].url 读取图片地址并立即下载。

异步结果的有效期 ​

  • 任务记录保留 24 小时：任务状态自最后一次更新起保留 24 小时，过期后可能无法继续查询。
  • 图片 URL 有效 24 小时：完成响应中的签名 URL 自生成后有效 24 小时；重复轮询不会刷新或延长该 URL。
  • 图片在 7 天后删除：平台存储中的异步结果图片会在生成 7 天后自动删除。
  • 请及时转存：应在 URL 有效期内下载图片，并保存到自己的对象存储或文件系统；不要把临时 URL 当作永久地址。

接入建议 ​

  • 请求可能已经被服务端接受时，不要盲目重复提交 POST，以免创建重复任务和重复计费。
  • 异步轮询必须使用提交任务时的同一把 API Key。
  • 生产环境建议为整个任务设置合理的总等待时间，并正确处理 failed 状态和 error 字段。
  • 下载成功后，应由业务系统保存自己的长期访问地址。