如何通过 hiapi API 使用 gpt-image-2.5-flare@pro：curl、Python 与一个可运行的请求

gpt-image-2.5-flare@pro 是通过 hiapi 统一任务 API 提供的图像模型之一。本指南先用 curl 和 Python 演示一个最小可运行请求，然后介绍生产环境所需的参数与模式：回调、幂等性和错误处理。

你需要准备什么

• 一个 hiapi API 密钥。可以从 hiapi 控制台 获取——每个密钥都以 sk- 开头。
• 以 https://api.hiapi.ai 作为基础 URL。每个请求都需要 Authorization: Bearer sk-<your-key> 请求头。

hiapi 上的图像生成（以及所有其他异步模型——视频、TTS、音乐）都通过同一个端点运行：POST /v1/tasks。你先创建一个任务，然后可以轮询 GET /v1/tasks/:id，或者在任务完成时接收回调。完整参考见：统一异步 API。

最小可运行示例

curl

创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

这里返回的是任务 ID，而不是图像——图像生成是异步的：

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

轮询结果：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status 的变化顺序为 queued → handling → archiving → success（或 fail）。当状态为 success 时，图像位于 data.output[0].url：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt 是 Unix 时间戳——在它过期前下载文件或重新托管，过期后该 URL 将停止工作。

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

用 pip install requests 安装唯一的依赖，导出 HIAPI_API_KEY，然后运行即可。

关键参数

gpt-image-2.5-flare 提供两条路由：默认路由（直接使用模型 ID gpt-image-2.5-flare）和 pro 路由（追加 @pro，如上面所有示例所示）。不存在显式的 @default 后缀——传入它会返回 MODEL_UNAVAILABLE。

input 接受以下字段：

• prompt（字符串，必填）——唯一必填字段。
• aspect_ratio——1:1、3:2、2:3、4:3、3:4、16:9、9:16、auto，或像 1536x1024、2048x2048、3840x2160 这样的显式像素尺寸。
• quality——low、medium、high、xhigh、max 或 auto。
• output_format——png、jpeg 或 webp。
• background——auto、transparent 或 opaque。与 output_format: png 或 webp 搭配使用 transparent 可获得抠图素材。

该 schema 是严格的——未知字段（size、n，或任何未列出的字段）会返回 400 INVALID_REQUEST 及 additional properties '<field>' not allowed，而不是被静默忽略。如果你需要编辑现有图像而不是从空白提示词生成，hiapi 将其作为单独的模型 ID 提供——图生图变体请见 模型页面。

生产环境模式

使用回调而不是轮询。 在创建请求中添加 callback 对象：

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" 目前是唯一支持的值——当任务达到 success 或 fail 时，hiapi 会向你的 URL 发送一次 POST 请求。回调体与 GET /v1/tasks/:id 返回的 data 字段完全相同。

发送 Idempotency-Key 请求头。 如果你这边请求超时并重试，幂等键可以阻止 hiapi 为同一请求创建（并计费）第二个任务。

显式处理错误。 无效或已撤销的密钥返回 HTTP 401：

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

格式错误的 input 返回 HTTP 400，附带 error_code: "INVALID_REQUEST" 和指明问题字段的 message——重试前先检查它，用同样的请求体重试 400 只会再次失败。

gpt-image-2.5-flare@pro 的定价（按成功生成的图像计费，依据分辨率和质量档位）见 定价页面。

相关文档

• 统一异步 API 参考——完整任务生命周期、所有模型类型
• 创建任务——POST /v1/tasks 的请求/响应结构
• 获取任务详情——轮询 GET /v1/tasks/:id
• 身份验证——API 密钥格式与请求头
• gpt-image-2.5-flare@pro 模型页面

常见问题

默认路由和 @pro 有什么区别？ 它们是同一模型系列的两条独立路由，通过你发送的模型 ID 选择（gpt-image-2.5-flare 与 gpt-image-2.5-flare@pro）。选择前请查看 模型页面 和 定价，了解当前的成本与能力差异。

我可以生成透明 PNG 吗？ 可以——设置 "background": "transparent" 并搭配 "output_format": "png"（或 "webp"）。

为什么我收到 additional properties 'size' not allowed？ schema 是严格的。请使用 aspect_ratio（它也接受像 1024x1024 这样的显式像素尺寸），而不是 size 字段。

输出 URL 的有效期是多久？ 直到 output[0] 对象上的 expireAt Unix 时间戳。在此之前下载或复制到你自己的存储——hiapi 之后不会继续提供该文件。

设置了回调还需要轮询吗？ 不需要，但你仍然可以轮询——无论是否配置了回调，GET /v1/tasks/:id 都可以正常使用，如果你的回调端点漏掉了一次投递，这可以用于手动复查。

如果我的请求同时包含 input_urls 和错误的 prompt 会怎样？ 验证会在创建任务前对整个请求体运行——任何无效字段（包括格式错误的媒体数组）都会返回 400，且不会创建任务（也不会扣费）。