教程
如何通过 HiAPI API 调用 gpt-image-2.6-sunburst/text-to-image:curl 与 Python 指南
认证、请求结构、可运行的 curl 与 Python 示例,以及故障排查
本页内容
端到端来看,这次集成是什么样子
HiAPI 上的每一次文本生图调用都遵循相同的生命周期,在写任何代码之前,理解这个生命周期是值得的。你的应用构造一个描述目标图像的 JSON 请求,将其连同 API 凭证发送到 gpt-image-2.6-sunburst/text-to-image 对应的 HiAPI 端点,然后收到一个包含生成图像数据或可获取 URL 的响应。理解这三个阶段之后,本指南的其余部分就只是补充细节。
各阶段拆分如下:
- 认证——将你的 HiAPI API 密钥附加到请求上,通常以 HTTP 请求头的形式。无需为每次调用进行令牌协商。
- 请求构造——组装一个 JSON 请求体,其中包含你的提示词,并可选地包含尺寸、图像数量等参数。
- 传输——将请求体 POST 到端点。该调用是同步的,因此客户端会等待图像生成完成。
- 响应处理——API 返回结构化 JSON。根据端点配置,图像数据以 URL 形式到达,或以编码图像内容的形式到达,你需要解码并写入磁盘。
有一个细节需要尽早注意:模型标识符 gpt-image-2.6-sunburst/text-to-image 包含一个斜杠。请将其视为不透明字符串。不要尝试把它拆分为提供商名称和模型名称,也不要自行进行 URL 编码或规范化。完全按照文档原样复制它,并将其放在代码中的一个位置,这样以后就不必再费力查找。
下文各节将按顺序逐一讲解每个阶段。curl 和 Python 部分刻意使用相同的请求载荷,方便你逐行对比;故障排查部分则将你最可能遇到的错误映射回需要修复的具体请求字段。
对 HiAPI 请求进行认证
HiAPI 使用基于 API 密钥的认证方案。你从账户仪表板获取密钥,并在每次请求时发送。标准形式是请求上的一个 HTTP 请求头:
Authorization: Bearer YOUR_API_KEY
有些客户端更愿意将密钥放在专用请求头中发送,但除非你的账户文档另有说明,否则应使用 Authorization: Bearer 形式,因为它开箱即用地匹配大多数 HTTP 工具。
将密钥排除在源代码之外
首次集成中最常见的安全错误,是将密钥硬编码到脚本中并提交。从第一天起就要避免这一点:
- 从环境变量读取密钥,例如
HIAPI_API_KEY,如果变量缺失,则在启动时快速失败。 - 在创建本地
.env文件之前,先将其加入.gitignore。 - 在 CI 或生产环境中,从平台的密钥存储注入密钥,而不是从已提交的文件中读取。
一个负责读取一次密钥、并在缺失时抛出清晰错误的小助手函数,将为你以后省去一次令人困惑的调试过程:
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
在请求时也把密钥当作机密
在排查失败的调用时,不要忍不住打印包含请求头的完整请求对象。改为记录端点、模型标识符和状态码。如果必须捕获请求头用于调试,请先对 Authorization 的值进行脱敏。泄漏到日志聚合器中的密钥,与提交到代码仓库中的密钥一样处于暴露状态。
如果你轮换密钥,旧密钥会在轮换完成后立即失效,因此请将轮换安排为定期操作,而不是紧急操作。
文本生图请求的结构剖析
请求体是一个 JSON 对象。对于 gpt-image-2.6-sunburst/text-to-image 而言,核心字段数量很少,这正是为什么值得确切理解每个字段的作用,而不是盲目复制请求载荷。
model 字段
"model": "gpt-image-2.6-sunburst/text-to-image"
该字段用于选择模型,且为必填。请保持该字符串与文档标识符逐字节一致。缺少斜杠、多出空格或更改大小写,都会导致请求因未知模型而被拒绝。
prompt 字段
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"
这是对图像的自然语言描述,为必填项。关于提示词本身的实用建议:
- 先写主体,再写场景,最后写风格或光线线索。
- 优先使用具体名词而非抽象概念;"木桌上的一只红色陶瓷马克杯" 胜过 "一个不错的杯子场景"。
- 如果你需要在多次调用中保持一致输出,请保持非变化部分的措辞稳定,只通过程序替换变化的部分。
可选参数
根据端点不同,你还可以发送控制输出形态和数量的参数,最常见的是:
- size——输出尺寸,采用文档规定的格式表示,例如
1024x1024。如果省略,则应用默认值;如果发送不支持的值,预期会得到校验错误。 - n——为一个提示词生成的图像数量。每张生成的图像单独计费,因此请将其保持在你的工作流所需的最低值。
只发送你确实需要的参数。未知字段可能引发严格的校验错误,而该错误会指向一个你根本无意发送的字段。
一个完整的请求体示例
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}
这就是全部约定。本指南中的其他内容都是围绕此载荷的传输、错误处理和生命周期管理。
用 curl 发出一个可工作的请求
在构建 Python 客户端之前,先用 curl 确认端点和凭证可用。这可以将认证问题与代码问题隔离开来。
调用命令
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}'
关于这些标志的几点说明:
-sS保持输出整洁,同时仍会显示传输错误。-X POST指定方法;请求体通过-d传递。- JSON 请求体外围的单引号可防止 shell 破坏它。在 Windows
cmd中,JSON 引号规则不同,因此请使用curl.exe和双引号,并转义内部引号,或者从 shell 脚本或 Python 中运行调用。
如果你使用账户文档中的确切端点路径,请在此处替换;请求的形态不会改变。
检查原始响应
出问题时,你需要状态码和响应体。添加 -i 以包含响应头,或添加 -w "\nHTTP %{http_code}\n" 以在末尾打印状态:
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
将载荷保存到 payload.json 并通过 @payload.json 引用它是值得的:你可以避免 shell 引号错误,并且可以编辑提示词而无需重写命令。如果提示词包含敏感文本,请将该文件排除在版本控制之外。
用 Python 发起同样的调用
Python 版本保持 JSON 请求体逐字节一致。只有传输方式改变。使用 requests 增加了一个依赖,但能让代码保持可读;对于任何不止于一次性脚本的用途,都值得安装它。
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
为什么使用 json=payload 而不是 data=json.dumps(payload):将 dict 传给 json 关键字参数会序列化它,并自动设置 Content-Type 请求头。将字符串传给 data 也可以,但很容易忘记设置请求头,这会在之后表现为令人困惑的校验错误。
如果你更愿意使用标准库
为了避免依赖,可以使用标准库中的 urllib.request。载荷字典保持不变:
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
无论哪种方式,图像生成都比典型的 JSON API 调用更慢。请将超时设置得宽松一些,否则你会在即将成功的请求上超时,并在重试时为其付费两次。
处理响应并保存图像
成功的响应是 JSON。图像输出通常以 URL(你需要单独获取)或载荷中的编码图像内容形式到达。查阅端点文档以确认适用哪种形式,然后防御性地处理两种形态,因为参数变化时,确切形态可能不同。
读取响应结构
响应是一个包含生成输出和元数据的 JSON 对象。在编写解析代码之前,先以交互方式检查一次:
print(json.dumps(data, indent=2)[:2000])
找到图像所在位置。如果看到 URL 字段,就下载它。如果看到 base64 内容,就解码它。避免假设 URL 是永久有效的——将其视为短期有效,并立即将字节复制到你自己的存储中。
保存基于 URL 的结果
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
保存编码结果
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
在实际工作负载中,为每次调用使用不同的文件名——时间戳、请求 ID 或从提示词派生的 slug。如果你打算以后重新生成或审计输出,请将提示词与图像一起保存在一个 sidecar JSON 文件中。
在一个地方处理成功响应
将响应解析封装在一个函数中,返回字节字符串列表,每张图像一个。这样每个调用方只需写入或上传字节,而无需知道它们来自 URL 还是编码内容。当你以后切换模型时,这种抽象会带来回报。
诊断常见错误
大多数首次集成失败都落入少数几个类别。在更改其他任何内容之前,将状态码和消息与下面的修复方法匹配。
认证失败
请求因凭证缺失或无效而被拒绝,意味着 Authorization 请求头缺失、格式错误或携带了已吊销的密钥。按以下顺序检查:
- 确认请求头名称和值格式,包括字面词
Bearer后跟一个空格。 - 确认运行调用的 shell 或进程中环境变量确实已填充——在一个终端中设置的密钥不会存在于另一个终端中。
- 确认密钥在复制时没有被轮换或截断。
请求体校验错误
API 会拒绝缺少必填字段或包含无效值的请求体。消息通常会指出有问题的字段:
- 缺少 model 或 prompt——两者都是必填的。每次调用都显式发送它们,而不是依赖默认值。
- 未知模型——重新检查标识符
gpt-image-2.6-sunburst/text-to-image,包括斜杠和大小写。不要在其周围插入空白字符。 - 无效尺寸——使用文档规定格式的受支持尺寸字符串。如果你有意省略 size,请将其移除,而不是发送
null。 - JSON 格式错误——通常是 curl 中的 shell 引号问题,或 Python 中的字符串编码问题。发送前用
json.dumps(payload)验证,并检查实际传输的内容。
速率限制和配额
如果你收到节流响应,请退避并使用抖动重试,而不是立即重试。如果消息表明配额问题,请检查账户的套餐和使用面板,而不是请求体——载荷很可能是正确的。
服务器错误
生成过程中的 5xx 通常是暂时性的。使用指数退避重试一两次。如果它在不同提示词和载荷下持续出现,那么问题不在你这边;请捕获响应体,并携带请求时间和模型标识符联系支持。
内容类型错误
发送请求体时未设置 Content-Type: application/json,可能会产生令人困惑的校验错误,因为服务器无法解析载荷。在 curl 中,显式设置请求头;在 Python 中,让 json= 参数来完成设置。
让集成达到生产就绪
第一次成功调用是容易的部分。以下调整可让集成在运行成本和变更成本上都保持低廉。
将模型标识符配置化
将模型标识符存储在一个常量或由环境驱动的配置值中,绝不要内联在多个调用点。当你以后评估不同模型时,只需更改一个值并重新运行测试。在日志中保留每个请求的字段,记录哪一模型生成了每张图像,这样你可以在切换模型时比较质量,而无需重新运行所有内容。
有策略地重试
对网络错误、超时和 5xx 响应使用指数退避和抖动进行重试。绝不要重试校验或认证错误——请求会以相同方式失败,你只会浪费速率限制。限制尝试次数,并记录每次尝试的编号和最终状态。
选择与工作负载匹配的超时
图像生成很慢。过短的超时会导致本可成功的请求失败,而且如果你重试,可能会为已经完成的生成付费。设置宽松的每请求超时,并将超过阈值的超时视为调查延迟的信号,而不是激进重试的理由。
将客户端分层
将三部分保持分离:一个载荷构建器,将应用输入转换为请求字典;一个传输函数,执行 HTTP 调用;一个处理器,将响应解码为字节。在没有网络调用的情况下测试构建器非常容易;将传输替换为 mock 也非常容易。这种分层还使模型变更成为一个文件的编辑,而不是在代码库中四处搜寻。
记录事故中你会需要的信息
记录时间戳、端点、模型标识符、HTTP 状态、提示词的哈希或截断形式,以及请求持续时间。绝不要记录 API 密钥或完整请求头。如果你存储生成的图像,请按请求 ID 设置存储路径,以便支持工单可以追溯回实际调用。
在认证由环境变量处理、载荷隔离在构建器函数中的情况下,你通过 gpt-image-2.6-sunburst/text-to-image 练习的模式可直接迁移到同一 HiAPI 端点上的任何其他图像模型。