如何通过 HiAPI API 调用 gpt-image-2.5-sunburst/text-to-image：curl 与 Python

这个模型端点给你什么

gpt-image-2.5-sunburst/text-to-image 是通过 HiAPI 统一 API 暴露的图像生成模型。你通过模型 ID 来调用它，在与文本模型相同的 chat-completions 形状的请求体中发送提示词，然后在响应中获取生成的图像数据。

实际影响是：如果你的代码库已经通过 HiAPI 处理文本，就无需第二个 SDK、无需单独的身份验证方案，也无需学习新的端点系列。唯一变化的是模型 ID。

当你的任务是提示词到图像的生成——根据文本描述生成新图像，并可选地由请求中提供的参考图片引导——就选这个端点。如果你需要分析或描述现有图像而不是生成图像，具备视觉能力的聊天模型更合适；把图像生成留在这个端点上，把图像理解放在别处。

需要提前设定一个预期：图像调用比文本补全慢。响应耗时达到个位数秒数是正常的，你的客户端超时应针对这一现实调整，而不是从纯文本配置中继承。

发送第一个请求之前

需要准备好三样东西。

一个 API 密钥

在 HiAPI 账户中创建密钥，并将其存储为环境变量，而不是写在源代码中：

export HIAPI_API_KEY="your-key-here"

确切的模型 ID

字符串是 gpt-image-2.5-sunburst/text-to-image。把它当作不透明标识符——复制它，不要凭记忆重新输入。斜杠是 ID 的一部分。这里的拼写错误是首次调用失败最常见的原因，并且会以模型未找到之类的错误出现，而不是负载问题。

一个能发起 HTTPS 请求的客户端

首次验证只需要 curl，它预装在大多数系统上。对于应用代码，使用带 requests 库的 Python（或任何 HTTP 客户端）就足够了。这个端点不要求客户端使用专门的图像库；你只是发送 JSON 并读回 JSON。

在首次纯文本调用之前，你不需要预先上传图片或配置存储。从下面的最小请求开始，仅在基本往返可用之后再添加参考图片。

一个使用 curl 的最小可用请求

这是最小的正确调用：

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

逐字段说明：

• URL——标准的 HiAPI chat-completions 路径。图像模型与文本模型使用相同的路由。
• Authorization——带有 API 密钥的 bearer 令牌。如果此标头格式有误，会在调用模型之前就收到 401。
• Content-Type——必须是 application/json。
• model——上一节中的确切模型 ID。
• messages——标准的 role/content 对象数组。你的提示词是 user 消息的 content。

成功时你会收到一个 JSON 响应，其中包含生成的图像数据以及通常的补全元数据。先把原始响应保存到文件，检查后再把解析逻辑接入脚本：

curl -sS ... -o response.json

一旦这返回图像，你的凭据和负载形状就是正确的，之后的所有问题都属于应用逻辑，而不是配置。

用 Python 编写同样的请求

请求约定不变——只有客户端设置、超时和响应处理会变。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

有三个细节值得注意：

超时是显式且不对称的

元组 (10, 180) 设置了较短的连接超时和较宽松的读取超时。图像生成本来就需要一段时间；从文本客户端复制来的单一扁平超时会产生虚假失败。连接超时保持较短，以便网络问题快速失败。

用 json=payload 而不是 data=

通过 json= 传递字典会为你处理序列化并设置内容类型。如果你用 data= 传递预序列化的字符串，请手动设置标头。

防御性解析

响应是 JSON；在索引之前，对意外形状记录整个响应体。在看到真实响应之前，不要假设固定的嵌套深度——也绝不要对非 2xx 状态假设成功形状。

如果你更喜欢为 HiAPI 配置的客户端库，发送的负载完全相同；只是调用位置变了。

正确传入参考图片

参考图片应在消息内容内部提供，而不是作为顶层临时字段。这是集成中最容易微妙出错的部分，因为格式错误的参考通常不会报错——请求只是成功，而输出忽略你的图片。

保持跨语言负载结构一致：user 消息携带内容数组，其中文本部分保存提示词，图片部分携带参考数据。你在 Python 中构建的同一 JSON 请求体必须能逐字节地在 curl 中表达；如果你写不出 Python 负载的 curl 等价物，说明结构已经漂移。

当结果似乎忽略你的参考图片时，按以下顺序检查：

1. 位置。图片部分是在 messages[].content 内部，还是泄漏到了请求体顶层？模型只能看到消息中的内容。
2. 编码。参考图片以编码数据形式在请求中传输。确认数据完整且格式正确，而不是被手动拼接或糟糕的复制粘贴截断。
3. 提示词耦合。参考图片引导生成；它不会替代指令。明确说明图片扮演的角色——风格、构图、主体——而不是假设模型能推断出来。
4. 大小。非常大的参考会膨胀请求并拖慢往返。编码前将其缩小到任务实际需要的尺寸。

一个实用的调试习惯

构建一次参考图片负载，保存确切的可用 JSON 请求体，并将其作为固定样本复用。当之后调用出现异常时，将当前请求体与固定样本进行差异对比。大多数参考图片回归是结构性的，差异对比几秒钟就能找到。

处理错误、超时和重试

图像端点的失败方式与文本端点不同：它们更慢，因此更多调用会落入超时触发的窗口，而盲目重试的代价更高，因为工作更重。

区分客户端错误与瞬态失败

• 4xx（429 除外）——负载格式错误、模型 ID 错误、缺少认证。重试相同请求会同样失败。修复请求。
• 401/403——凭据问题。检查密钥和 Authorization 标头格式。
• 429——已限流。重试，但使用退避和抖动，而不是立即重试。
• 5xx 和连接错误——瞬态。重试。
• 读取超时——有歧义：生成可能已在服务器端完成。仅当你的工作流能容忍可能的重复时，才将超时视为可重试。

只重试安全的内容

使用带抖动的指数退避，并对尝试次数设置小上限——三次通常足够。一个简单模式：

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

不要在此循环内重试 4xx 负载错误——立即暴露它们，让错误请求大声失败，而不是浪费尝试次数。

根据模型调整超时大小

给图像调用设置的读取超时应是文本默认值的数倍，并按调用设置而不是全局设置，以免文本流量受到惩罚。如果你的平台有硬性请求上限，请将生成提示词和参考图片控制在你能实际完成的预算内。

发布前的生产检查清单

一份能预防大多数事故的简短清单：

• 模型 ID 放在一处。将 gpt-image-2.5-sunburst/text-to-image 定义为常量或配置值，而不是分散的字符串字面量。
• 密钥来自环境变量，绝不提交。像其他任何机密一样轮换它。
• 显式超时，具有宽松的读取窗口，设置在请求上而不是会话默认值上。
• 仅在 429/5xx/超时时重试，使用退避和抖动，并限制尝试次数。
• 失败时记录完整响应——在解析前记录状态、响应体和请求 ID，以便支持对话从证据开始。
• 保存可用的负载固定样本，涵盖普通情况和参考图片情况，在行为变化时用于差异对比。
• 参考图片放在消息内容内部，按任务缩小，并在提示词中说明其角色。
• CI 中的冒烟测试，针对模型 ID 发起一次真实调用，以便重命名或退役的模型在用户发现之前暴露。

这些习惯都不是图像生成特有的，但每一条都针对图像调用比文本调用更常遇到的失败模式。一次性接好它们，端点就会像你技术栈中的其他部分一样运行。关于模型当前参数和限制，请在最终确定配置前查看 HiAPI 上的模型页面。