GPT Image 2 / 2.5 API — 图像生成与图像编辑

配合 GPT Image 2、Sunburst 和 Flare，使用 generations 进行文生图，并使用 multipart edits 传入参考图像。包含单图、多图、Python 和异步示例。

GPT Image 2 / 2.5:图像生成与图像编辑

在编写请求之前先选择端点：文生图使用 /images/generations；图生图使用 /images/edits 并上传图像文件。 在提示词中提及“参考图 1”并不会附加任何图像。

模型与端点

模型 ID	文生图	图生图
`gpt-image-2`	`/images/generations`	`/images/edits` + 图像文件
`gpt-image-2.5-sunburst`	`/images/generations`	`/images/edits` + 图像文件
`gpt-image-2.5-flare`	`/images/generations`	`/images/edits` + 图像文件

这些是相互独立的模型 ID。切换模型时必须显式更改 model；GPT Image 2.5 并不是 GPT Image 2 的别名。请在模型广场中查看当前的可用性与账户定价。

操作	方法与端点	请求格式
文生图	`POST https://apimaster.ai/v1/images/generations`	JSON
图生图 / 编辑	`POST https://apimaster.ai/v1/images/edits`	`multipart/form-data`，包含实际图像文件
异步图像编辑	`POST https://apimaster.ai/v1/images/edits/async`	与编辑相同的 multipart 文件；返回任务 ID
异步文生图	`POST https://apimaster.ai/v1/images/generations/async`	JSON；返回任务 ID
查询任务	`GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID`	Bearer 认证

如果希望图像编辑返回任务响应，请使用 /images/edits/async。 上传与同步编辑相同的文件和字段，然后查询 /tasks/{task_id}。不要把编辑请求改发到 generations/async。这些任务端点复用现有的异步约定：异步上游可以立即返回其任务，而同步上游可能在网关返回任务 ID 之前就已完成编辑。它们并不保证立即在后台执行。请勿对这些模型使用 Chat Completions。

认证与超时

创建 API 密钥并发送 Authorization: Bearer YOUR_API_KEY。JSON 生成请求使用 Content-Type: application/json。对于文件上传，请让 cURL 或你的 HTTP 库生成 multipart boundary；不要手动设置 Content-Type 请求头。

基础请求请至少预留 180 秒，更高分辨率请预留 300 秒，高难度编辑或高质量生成请预留 600 秒。客户端超时并不能证明上游请求已停止。请避免立即重复提交。

文生图：JSON 生成

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

对于 Sunburst 或 Flare，请将模型 ID 替换为 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。不要在此示例中添加参考图像；请使用下方的编辑示例。

图生图：上传单个参考图

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

请将 reference.png 替换为一张实际存在的本地图像。@ 告诉 cURL 上传文件字节；image=reference.png 只会发送文件名字符串。该端点模式同样适用于 gpt-image-2 和 gpt-image-2.5-sunburst。

图生图：上传多个参考图

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

为每个文件重复相同的 image[] 字段，并按照提示词中描述的顺序排列。n 是输出图像的数量，而不是参考图的数量。参考图数量限制取决于所选模型和可用路由；不要假定存在统一的 16 张图像上限。先从一张参考图和 n=1 开始，再按需添加输入。

Python 编辑示例

安装 requests。此示例上传真实文件，并同时处理 URL 和 base64 两种图像响应。

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

对于多个文件，请向 files 传入由重复的 ("image[]", (filename, file_object, mime_type)) 组成的列表。在请求完成之前，请保持每个文件处于打开状态。

异步图像编辑

当你的应用需要处理任务 ID 时，可将此端点与 GPT Image 2、Sunburst 或 Flare 搭配使用。文件上传规则、参考图顺序、能力限制和认证均与同步编辑相同。

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

提交后会返回 data[0].task_id。请使用相同的模型 ID 进行轮询：

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

已完成且被跟踪的任务具有如下结构；其中包含每一张生成的图像：

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

任务归属于提交它的账户。请使用该账户的有效 API 密钥来查询。提交失败时会返回错误，而不是可用的任务；一旦返回了任务 ID，就应持续轮询该任务，而不是重新提交编辑。请参见下方的轮询状态表。

既有的 URL 或 base64 集成

如果你的输入是 URL，请在应用中下载图像，并将其字节上传到 /images/edits。如果输入是 base64 data URI，请将载荷解码为文件或字节缓冲区后上传。不要把 URL 或 base64 文本当作文件上传来提交。

部分 GPT Image 2 路由在 generations 上支持 image_urls 扩展。这不是一种跨模型通用的图生图协议，不得假定其适用于 GPT Image 2.5。 新的集成应使用上方的 multipart 编辑示例。包含 image_urls、image 或 images 的 JSON 请求并不等价于向 edits 上传文件。

参数与能力限制

字段	用法
`model`	必填；请使用上表中的某个确切模型 ID
`prompt`	必填；描述期望结果及参考图顺序
`image` / `image[]`	编辑时实际上传的文件；基础示例请使用 PNG 或 JPEG
`n`	输出图像数量；先从 `1` 开始；最大值取决于路由
`size`	可选；`1024x1024` 为基础示例；其他像素尺寸或宽高比取决于路由
`resolution`	可选的路由特定扩展，例如 `1k`、`2k`、`4k`；并非每个模型/路由都支持每个档位
`quality`	可选；可接受的取值与费用取决于路由
`background`、`output_format`、`output_compression`	可选；透明度和输出编码需要路由支持
`mask`	仅限 GPT Image 2，且需要可用的 edits 路由支持上传蒙版；当前的 GPT Image 2.5 multipart 处理器不支持

对于 GPT Image 2，蒙版支持必须与普通参考图编辑分开单独确认。兼容的 PNG 蒙版必须与输入尺寸一致，并包含 alpha 通道。当前的 GPT Image 2.5 multipart 端点会拒绝上传的蒙版文件；不要在上面的 Sunburst 或 Flare 示例中添加蒙版。在未核对所选路由之前，不要假定支持 JSON mask_url 的变通方案。

只发送你需要的可选字段。这些字段可能改变符合条件的路由和价格；显式设置默认值并不总是等价于省略该字段。没有任何固定的像素尺寸表或高级参数列表能够统一适用于全部三个模型 ID。实际定价与所支持的能力以市场和请求响应为准。

同步响应

成功的生成或编辑会在 data 中返回图像条目：

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

取决于路由和输出格式，条目也可能改为包含 b64_json。请将其解码为图像字节。临时结果 URL 请尽快下载。仅凭 HTTP 200 响应或图像数量并不能证明参考图细节得到保留；请对照输入检查输出结果。

异步任务：提交与轮询

对于文生图，请向 generations/async 提交不含参考图像的 JSON。对于图像编辑，请使用上方的 multipart edits/async 示例。两者使用相同的任务查询端点：

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

提交返回的信封通常会报告 submitted；上游也可能已经报告完成状态。第一次轮询时任务就可能已经完成。任务 ID 并不保证立即得到响应：如果所选上游是同步的，平台会等待生成完成后再返回任务。请保留足够的提交超时时间。

使用与提交时相同的模型 ID 进行轮询：

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务状态	处理方式
`pending`、`submitted`、`processing`、`in_progress`	等待；3–5 秒后再次查询
`succeeded`、`success`、`completed`	读取 `data.result.images` 中的每个条目；被跟踪任务的 `url` 为字符串，而旧版上游响应可能使用 URL 数组
`failed`、`error`、`cancelled`	停止轮询并检查错误

请设置一个有限的总体轮询截止时间，例如 10 分钟。如果超时，请保留任务 ID 以便之后核查，而不是自动创建另一个付费任务。任务查询响应与同步图像响应的结构并不相同。

参考图故障排查

确认实际请求路径是 /v1/images/edits 或 /v1/images/edits/async，而不是 generations 或 generations/async。
确认 multipart 中在 image 或重复的 image[] 下包含文件字节，并带有自动生成的 boundary。提示词文本、文件名和参考图数量都不能替代文件。
检查确切的模型 ID。Sunburst 或 Flare 不会自动支持 GPT Image 2 的扩展功能。
如果任务/日志详情中没有预览，不要断定没有发送图像：日志可能省略 base64 数据和已上传文件的内容。反过来，日志中记录的参考图数量也不能证明上游确实使用了这些图像。
使用一张包含醒目文字或形状的简单参考图进行测试，并要求修改背景但不描述那些细节。然后目视比对输出结果。
如需联系支持团队，请保留请求 ID（X-Oneapi-Request-Id）、任务 ID（如存在）、模型、端点、时间戳、脱敏后的请求字段以及参考图。切勿分享你的 API 密钥。

收到 400 响应时，请检查端点与参数的兼容性；401 表示认证失败；429 表示速率/配额限制。遇到超时或上游失败时，请保留请求/任务 ID，并在重新提交前先查询现有任务或用量记录。