GPT Image 2.5 API 接入与迁移指南

HiAPI

在 HiAPI 接入 GPT Image 2.5，先选 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst，再通过 POST /v1/tasks 提交任务。两款模型都支持生成和编辑，是否传入 image_urls 决定请求有没有参考图。

从 Image 2 迁移时，需要同时修改模型名和输入参数。 旧版的 resolution、size、参考图字段和路由设置有不同约定，只替换一个模型字符串，容易留下不适用的参数。

以下代码按 2026 年 9 月 9 日的 HiAPI 在线文档编写，用于说明请求与异步处理流程，实际输出和费用以任务记录为准。参数更新以 Flare 文档和 Sunburst 文档为准。

一个模型 ID，覆盖生成和编辑

Flare 和 Sunburst 在 HiAPI 的请求字段相同。选定一个型号后，纯文本生成省略 image_urls；编辑时加入 1–16 张参考图，并在提示词里说明要修改和保留的内容。不要为纯文本生成发送空数组，也不需要自行拼接 /edit 或 /text-to-image 后缀。每个任务输出一张图片。

如果已有稳定的图片工作流，可以先挑一类任务迁移，保留原来的输入和验收标准。关于两个型号的定位，可先看 Image 2 与 2.5 的区别；这篇文章重点讨论请求如何落地。

提交一个生成请求

下面的例子生成一张方形杯子商品图。将 JSON 保存为 request.json。quality 明确设为 medium，方便后续复现参数；aspect_ratio 设为文档列出的像素尺寸 1024x1024。

{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

API Key 放在服务端环境变量 HIAPI_API_KEY 中。以下命令读取文件提交，并保存创建任务的响应。HIAPI_REQUEST_ID 由你的应用为这一次逻辑请求生成；同一次请求因网络问题重试时复用，修改输入或创建另一张图时使用新值。

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

创建成功后，从 created.json 的 data.taskId 读取任务 ID。此时图片仍在异步生成。Idempotency-Key 用于避免同一逻辑请求因重复提交创建多个任务，完整约定见创建任务文档。不要把提交成功当成图片已经完成。

用同一接口编辑图片

下面是独立的 Sunburst 编辑请求。将 image_urls 中的占位地址替换为服务可读取的真实参考图 URL，再保存为 request.json，使用一个新的请求 ID 提交。example.com 地址只说明字段结构，不能直接用来生成。

{
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

多个参考图按数组顺序说明用途，例如第一张提供商品，第二张提供背景。连续修改时，把上一步保存的输出作为下一次请求的参考图；每次仍是一个新任务，需要明确新的修改要求。不要假设接口会自动保留上一轮对话或图像。

透明背景需要将 background 设为 transparent，并选择 PNG 或 WebP。JPEG 不支持透明通道。模型输出后仍要检查边缘和主体，字段设置不能代替图片验收。

查询状态，再保存文件

GET /v1/tasks/:id 返回任务详情。queued、handling、archiving 都是非终态；只有 success 表示输出可用，fail 则通过 data.error 提供失败信息。外层 code: 200 只说明查询成功，必须继续判断 data.status。任务详情文档

下面的 Python 示例使用 requests，读取刚才的 created.json，先等待 3 秒，再每 4 秒查询。它会保存详情 JSON 和第一张图片。10 分钟是示例的本地等待上限，既不代表服务 SLA，也不会取消服务端任务。超时后保留 taskId，稍后继续查同一个任务。

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

临时输出需要在 output[].expireAt 前下载或转存。正式服务可在请求顶层配置 callback 接收终态通知，保留轮询作为兜底；回调字段不要放进 input。回调验签和重复通知处理按统一异步 API 实现。示例没有包含业务队列、回调服务或完整网络重试策略。

从 Image 2 迁移，逐项核对输入

旧版 Image 2 有不同路由，迁移时先确认当前使用的是哪一条。下面列的是 HiAPI 文档之间的参数差异，不适用于直接把其他提供商的 SDK 请求原样转过来。

旧工作流	Image 2.5 的调整
生成和编辑使用不同的 Image 2 模型 ID	改用完整的 Flare 或 Sunburst ID；用 `image_urls` 的有无区分
Standard 编辑使用 `input_urls`	改为 `image_urls`；旧 ext 编辑已使用这个字段
Standard / ext 使用 `resolution`	按目标尺寸重新选 `aspect_ratio` 中的比例或像素枚举，不保留 `resolution`
Beta 生成使用 `size`	改为文档支持的 `aspect_ratio` 像素枚举，不直接复制任意尺寸
显式 `route: "beta"` / `"ext"`，或模型名带路由后缀	按 2.5 模型文档重新构造请求，不沿用旧路由
旧版支持的 `4:5` 等比例	逐项核对；2.5 当前枚举没有 `4:5`，不要静默改成别的比例
依赖默认质量、尺寸或输出格式	显式指定，并重新检查输出、费用和下游文件处理

2.5 当前比例选项为 1:1、3:2、2:3、4:3、3:4、16:9、9:16 和 auto。此外，aspect_ratio 接受文档列出的 10 个像素尺寸。需要固定尺寸时选枚举值，不能仅根据字符串格式推断任意 widthxheight 都可用。特别是 auto，新文档描述为由模型选择合适构图，不应直接继承旧编辑路由“跟随输入图”的假设。

质量选项为 low、medium、high、xhigh、max、auto，默认 medium。同名质量档位不保证与旧模型有相同的费用或视觉表现。完整旧协议可对照 Image 2 生成和 Image 2 编辑文档。

出错与预算，放在同一条验收链路里

提交时的 400 应检查模型名、字段和枚举；402 检查余额；415 检查 Content-Type。任务已经创建后出现 fail，则保存 data.error 排查，不重复提交同一份无效输入。503 可以稍后退避重试；POST 因网络中断无法确定是否创建时，使用原来的幂等键，避免重复任务。创建任务错误说明

成本核对从 HiAPI 当前价格页和具体模型页开始。迁移验收记录完整型号、尺寸、质量、参考图数量、请求、输出和实际账单，不能沿用旧 Image 2 的单价，也不要把其他平台的起步价当成 HiAPI 报价。网页端样图可以帮助评估效果，API 耗时和账单需要各自的实际记录。

把一个生成任务和一个编辑任务接入、保存并验收后，再扩大到批量流程。可从 Flare 模型页或 Sunburst 模型页查看当前入口，再按对应 Docs 维护参数。