教程

如何通过 hiapi API 使用 gpt-image-2.5-sunburst：curl、Python 与可用的请求示例

最小请求、完整参数参考，以及上线生产前必须具备的 callback/幂等模式。

2026年11月3日

要使用 gpt-image-2.5-sunburst 生成或编辑图像，请将带有提示词的任务提交到 POST /v1/tasks，然后轮询 GET /v1/tasks/<id>（或接收回调），直到任务完成，并从 data.output[0].url 读取图像 URL。本指南涵盖最小请求、完整参数集，以及上线前所需的生产模式（回调、幂等、错误处理）。

前置条件

你需要一个 hiapi API 密钥。请从控制台创建一个——每个请求都使用 Authorization: Bearer sk-<your-key> 进行认证。没有免费层级的方式可以从浏览器调用它，也没有无需密钥的方式；下面的所有示例都假设你已经拥有一个密钥。

最小可用示例

gpt-image-2.5-sunburst/text-to-image 在 input 中仅需 prompt。宽高比默认为 auto，分辨率默认为 1K。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

它会立即返回一个任务 id：

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

轮询结果：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

相同往返流程的 Python 版本：

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url 指向临时存储——响应中包含 expireAt（Unix 秒）。请在该截止时间之前下载字节并持久化（你自己的存储、S3、R2 等）；不要把它当作永久链接。

完整参数参考

gpt-image-2.5-sunburst 有两个模型 id：gpt-image-2.5-sunburst/text-to-image 用于根据提示词生成，gpt-image-2.5-sunburst/image-to-image 用于编辑或合成参考图像。两者接受相同的字段，区别在于 image_urls 在 image-to-image 上是必填的，而在 text-to-image 上不使用：

字段	类型	默认值	说明
`prompt`	string，1–8000 字符	—	必填。对于编辑，请描述应更改什么以及必须保持完全一致什么。
`image_urls`	URL 数组	—	仅 image-to-image，必填，1–16 张 JPEG、PNG 或 WebP 图像，每张最多 20 兆像素且不超过 30 MB。必须是可公开下载的 URL 或 data URI。
`aspect_ratio`	枚举	`"auto"`	`auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`27:16`、`16:27`、`9:8`、`8:9`。
`resolution`	枚举	`"1K"`	`1K`、`2K`、`4K`。这决定了价格。
`background`	枚举	无	`transparent`、`opaque`、`auto`。`transparent` 仅在 `1K` 下生效，此时会返回带 alpha 通道的 PNG。

编辑示例——传入一张或多张参考图像，并只描述你想要的更改：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

该 schema 是严格的（additionalProperties: false）——未知字段会被拒绝，因此不要沿用其他图像模型的参数（例如 size、strength、n）。

生产模式

在真实后端中使用回调而不是轮询。 添加 callback 块以跳过轮询循环：

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" 在任务达到终态（success 或 fail）时恰好触发一次。你的端点应快速返回 2xx，并异步执行实际工作（下载输出、更新你自己的数据库）——hiapi 会重试未获得快速确认的回调。

使重试具备幂等性。 如果客户端请求超时，你无法确定任务是否已创建。在创建请求中发送 Idempotency-Key 头（最多 255 字节），并在重试时复用同一密钥：同一账户和密钥只会创建一个任务，重试会返回原始 taskId。没有它，重复处理同一提示词会被计费两次。

处理你实际会遇到的终态：

success — 读取 data.output[0].url 并及时下载（遵守 expireAt）。
fail — 在重试前检查 data.error 了解失败原因；不要对每次失败都盲目重试，有些是提示词层面的问题（例如违反策略），原样重试仍会失败。
轮询不存在的任务 id（拼写错误、已过期）会返回 HTTP 404，内容为 {"code":404,"message":"task not found"}。

认证失败是 HTTP 401，而不是任务级错误：

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

在假定任务失败之前，请在错误处理中检查这一点——无效或已撤销的密钥根本不会进入任务创建阶段。

常见问题

gpt-image-2.5-sunburst 支持图像编辑，还是仅支持文生图？ 两者都支持，通过两个模型 id 实现。使用 gpt-image-2.5-sunburst/image-to-image 搭配 image_urls（1–16 张参考图像）进行编辑或合成，使用 gpt-image-2.5-sunburst/text-to-image 仅根据文本生成。

如果我发送空的 image_urls 数组而不是省略它，会发生什么？ 不要这样做。在 image-to-image 上，image_urls 是必填的，并且至少需要一个 URL。对于纯文本生成，请改用 text-to-image 模型 id。

一张图像多少钱？ 取决于 resolution：1K 为 $0.05，2K 为 $0.08，4K 为 $0.12，text-to-image 和 image-to-image 相同。在程序员节优惠期间（截至 2026 年 11 月 9 日 00:00 UTC+8），所有档位均享 5 折优惠：$0.025、$0.04 和 $0.06。在扩大规模之前，请查看模型页面了解实时价格。

我可以获得固定像素尺寸而不是宽高比吗？ 可以——除了像 16:9 这样的比例字符串外，aspect_ratio 还接受像 1024x1024、1536x1024 或 3840x2160 这样的字面尺寸。

为什么我轮询任务时返回 404？ 要么 taskId 有拼写错误，要么你轮询的端点/区域没有该任务。请仔细检查你从创建响应中保存的 id——hiapi 在任何正常轮询窗口内都不会静默使任务记录过期。

我可以在没有 API 密钥的情况下调用它进行测试吗？ 不可以。每个 /v1/tasks 请求都需要 Authorization: Bearer sk-<key>；没有匿名或仅浏览器模式。