教程

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

2026年11月3日

gpt-image-2.5-sunburst@pro 是 hiapi 上 gpt-image-2.5-sunburst 模型的 Pro 路由。本指南带你从零走到一个可运行的请求：模型 id 到底是什么、它接受哪些确切的 input 字段、一个可直接运行的 curl/Python 示例，以及在无人值守运行之前你需要的生产模式（幂等性、回调、错误处理）。

你需要先准备什么

一个 hiapi 账户和一个来自控制台的 API key。下面每个请求都用 Authorization: Bearer sk-<your key> 进行认证。
就这些——不需要单独安装 SDK。hiapi 上的每个模型都通过同一个异步任务端点调用，所以如果你之前调用过任何其他 hiapi 模型，这个请求的结构对你来说会很熟悉。

这个模型特有的唯一一点：@pro 是路由后缀，不是昵称。hiapi 对某些模型暴露了不止一种调用模式，gpt-image-2.5-sunburst 就是其中之一——普通模型 id 和带 @pro 后缀的 id 接受不同的 input 字段，并按不同的定价档位计费。本指南专门针对 gpt-image-2.5-sunburst@pro；使用裸的 gpt-image-2.5-sunburst id 你会得到一个不同模式、不同 schema（见 FAQ）。

最小可运行示例

hiapi 的每个生成模型——图像、视频或音频——都通过同一个统一端点调用：POST /v1/tasks。你提交 model 和 input，立即拿到一个 taskId，生成则异步运行。

对于 gpt-image-2.5-sunburst@pro，input 接受：

字段	类型	是否必填	说明
`prompt`	string	是	1–32,000 个字符
`image_urls`	string[]	否	1–16 个公开的 JPEG/PNG/WebP URL；包含此项可做图生图而非文生图（不支持 SVG）
`aspect_ratio`	enum	否	例如 `1:1`、`16:9`、`9:16`，或显式尺寸如 `1536x1024`；默认 `1:1`
`quality`	enum	否	`low` / `medium` / `high` / `xhigh` / `max` / `auto`；默认 `medium`——提高之前请先看下面的生产注意事项
`background`	enum	否	`transparent`、`opaque` 或 `auto`；默认 `auto`
`output_format`	enum	否	`png`、`jpeg` 或 `webp`；默认 `webp`

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

这会立即返回一个 taskId：

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

然后轮询获取结果：

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

一旦 data.status 为 success，图片位于 data.output[0].url。立即下载它——该 URL 带有 expireAt，不适用于永久外链引用。

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

生产模式

轮询与回调。上面的循环对脚本和低流量使用没问题。对于任何服务端场景，优先用回调而非轮询：在同一个请求中添加一个 callback 对象——

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url 必须是 HTTPS，when: "final"（目前唯一支持的值）在成功和失败时都会通知你一次——没有轮询循环，没有浪费的请求。hiapi 可能多次投递回调，所以请在你这一端按 taskId 去重。

幂等性。在 POST /v1/tasks 上添加 Idempotency-Key 头（任意最多 255 字节的字符串，例如订单 id）。如果网络超时导致你的客户端重试同一次提交，平台会返回原始的 taskId（响应头带 Idempotent-Replay: true），而不是创建——并计费——第二个任务。该 key 的作用域是你的账户，24 小时后过期；用不同的请求体重用它，会返回 422 IDEMPOTENCY_KEY_MISMATCH，而不是静默创建新任务，所以不匹配是一个信号，提示你检查重试逻辑，而不是盲目重试。

认证错误。格式错误或错误的 API key 会快速失败，返回 401 和 permission_denied 错误码，且在任何任务创建之前：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

如果你看到这个，修复几乎总是 key 本身（环境变量写错、key 过期、缺少 sk- 前缀）——而不是请求体。在 key 修正之前，把它当作不可重试。

关于 quality。quality 默认是 medium，这是一个合理的默认发版值——提高它会同时增加成本和生成时间，所以只有在你自己测试中确认某个给定 prompt 在该档位仍能可靠成功后，才提升到 high/xhigh/max。

FAQ

gpt-image-2.5-sunburst@pro 与 gpt-image-2.5-sunburst 是不同的模型吗？ 是同一模型系列，不同路由。裸的 gpt-image-2.5-sunburst id（及其 /text-to-image 模式）接受一个 resolution 字段（1K/2K/4K），没有 quality 或 image_urls 字段。@pro 将其替换为 quality 档位，并增加了可选的 image_urls，所以当你想在同一次调用中控制质量档位或做图生图时，就用这个路由。