教程
如何通过 HiAPI API 调用 gpt-image-2.6-flare/text-to-image:curl、Python 及可运行的请求
本页内容
本教程构建的内容
大多数文生图教程止步于一张成功响应的截图。这不足以让任何东西上线。本教程带你从零开始,通过 HiAPI 统一 API 与 gpt-image-2.6-flare/text-to-image 模型建立一套可复用、可运行的集成。
到结束时你将拥有三样东西:
- 一个经过确认可正常工作的请求,先以
curl命令形式呈现,再以等价的 Python 脚本呈现。 - 对 HiAPI 如何组织文生图调用有清晰的心智模型——端点路径、认证头、提示词载荷和响应体——这样你就能把示例改编成自己的提示词,而不是死记硬背。
- 将该单次调用扩展为批处理的模式,以及判断哪些失败应重试、哪些应修复的方法。
我们会让代码保持精简、依赖最少。Python 示例只使用标准库,因此你可以在任何安装了 Python 的环境中运行;等你熟悉请求结构后,再改编为 requests 或异步客户端。如果你想直接跳到可运行的调用,请跳到 curl 部分,之后再回来阅读解释。
前置条件与凭据
在第一次调用之前,确认你已具备以下条件:
- 一个 HiAPI 账户。 登录仪表盘,以便生成和管理凭据。
- 一个 API 密钥。 在仪表盘的 API 密钥区域创建一个。请像对待密码一样对待它:它授权每一个计费到你账户的请求。
- 一种发送 HTTP 请求的方式。 要么是安装了
curl的 shell,要么是带标准库的 Python 3(urllib和json都随 Python 一起提供)。
通过环境变量处理密钥
永远不要把密钥直接粘贴到会被提交的源文件中。改为在 shell 中导出它:
export HIAPI_API_KEY="your-api-key-here"
在 Windows PowerShell 中,使用 $env:HIAPI_API_KEY = "your-api-key-here"。在 CI 中,将其作为密钥注入。在长时间运行的服务中,启动时从密钥管理器加载。
了解基础 URL 所在位置
HiAPI 提供单一的统一 API 表面,因此基础 URL 在各模型之间保持稳定。将其保存在一个配置值中——环境变量就很合适——而不是散布在代码各处。这样在预发布和生产之间切换,或让测试指向 mock 服务器,都只需改一行。
你将调用的模型标识符是 gpt-image-2.6-flare/text-to-image。注意它包含一个斜杠;保持标识符完整,并让它位于请求构建器所期望的路径位置,完全如下面的示例所示。
密钥已导出、基础 URL 已记录,你就可以查看请求本身了。
文生图请求的剖析
每次 HiAPI 文生图调用都有相同的四个组成部分。一旦理解它们,切换模型或提示词就变得机械化了。
1. 端点路径
请求将模型标识符作为路径的一部分:gpt-image-2.6-flare/text-to-image,附加到你的基础 URL 之后。这是将你的调用路由到统一接口背后正确模型的地址。
2. 认证头
认证是 Authorization 头中的 bearer 令牌:
Authorization: Bearer $HIAPI_API_KEY
每个请求都必须包含此头。缺失或格式错误是首次调用失败最常见的原因。
3. 请求体
文生图调用是一个带 JSON 体的 POST。核心是提示词——你想要图像的自然语言描述。请求体还携带生成设置。由于 HiAPI 在模型之间规范化请求结构,你可以复用请求构建器,并在想比较输出时更改模型标识符。
4. 响应体
成功的响应返回生成的图像(或其引用)以及关于生成的元数据。你的客户端应在尝试解析图像之前检查 HTTP 状态。将响应视为数据,而不是用来肉眼查看的东西——对于自动化,你需要图像字节或 URL,并且需要将任何请求标识符与它们一起存储,以便将文件关联回产生它的调用。
这就是整个模型。此后的一切都是这四个部分的具体实例化。
用 curl 发出可运行的请求
这是完整调用。将提示词替换为你自己的文本并运行:
curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
}' \
--output response.json
逐行解释:
-X POST——生成是改变状态的调用,因此使用 POST。- URL——来自环境变量的基础 URL,后跟模型标识符和
/text-to-image。加引号可防止 shell 误读特殊字符。 Authorization: Bearer ...——凭据。$HIAPI_API_KEY形式可让字面密钥不出现在 shell 历史中。Content-Type: application/json——告诉服务器将请求体解析为 JSON。省略它是导致令人困惑的 4xx 错误的常见原因。-d '{...}'——JSON 载荷。prompt字段是你最常更改的字段;在优化输出时,在此添加生成设置。--output response.json——将响应体写入文件,这样二进制图像载荷不会淹没终端。打开它,或者如果响应是 JSON 编码的,用jq管道处理。
快速健全性检查
如果命令迅速返回且 response.json 非空,你就拥有了一个可工作的集成。如果反而得到 4xx,请检查响应体——HiAPI 返回描述性错误,下面的错误处理部分涵盖了常见嫌疑对象。
一旦这能运行,将命令保存在项目旁边的 shell 脚本中。这是测试凭据更改或确认故障是否在你这边的最快方式。
用 Python 发出同样的请求
curl 调用可以直接转换为 Python。此脚本只使用标准库,从环境变量读取密钥,并将图像响应写入磁盘:
import json
import os
import urllib.error
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"
def generate_image(prompt: str, settings: dict | None = None) -> bytes:
payload = {"prompt": prompt}
if settings:
payload.update(settings)
request = urllib.request.Request(
f"{BASE_URL}/{MODEL}",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
if __name__ == "__main__":
body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
with open("output.bin", "wb") as f:
f.write(body)
print(f"wrote {len(body)} bytes")
几个有意的选择:
- 超时设置得较宽裕。 图像生成比文本补全慢;120 秒的上限可避免永远挂起,同时仍能容忍缓慢但成功的调用。
- 函数返回字节,而不是路径。 这使其可复用——你可以将字节上传到对象存储,或从 Web 处理程序返回它们。
- 错误被包装并附带响应体。 出错时,消息会告诉你服务器说了什么,而不仅仅是状态码。
- 载荷构建器接受可选设置。 当你添加生成参数时,扩展
settings字典,而不是硬编码到函数中。
导出两个环境变量后,用 python generate.py 运行它。如果你更喜欢 requests,将请求构建替换为 requests.post(url, json=payload, headers=headers);结构完全相同。
批处理与并发模式
一个提示词是演示;许多提示词是工作。这一转变引入两个问题:吞吐量和可调试性。
从文件迭代提示词
将提示词放入以换行分隔的文件或 JSON 数组中。为每个提示词分配一个 ID(slug、索引或哈希),并用该 ID 命名输出文件。当一批数百张图像完成时,你可以将每个文件映射回其提示词而无需猜测。
prompts = [
("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
body = generate_image(text)
with open(f"out/{prompt_id}.bin", "wb") as f:
f.write(body)
显式控制并发
生成调用是 I/O 密集型的,因此并发有助于吞吐量——但无界并发会触发速率限制并让你陷入错误泥潭。先串行,测量单次调用耗时,然后用有界工作池提高并发。一个简单线程池,使用少量固定工作线程(一开始四到八个)通常就足够了。
对于更大的任务,使用异步客户端或带工作线程队列的队列。关键纪律相同:有界并行、每个提示词 ID 一个输出文件、每个请求一行日志记录 ID、状态和耗时。
保留清单
在批处理运行时写一个小的 JSON 清单,记录每个提示词 ID 及其结果。如果进程中途死亡,清单会告诉你从何处恢复,而不是重新计费整批。这一实践比任何聪明的优化都节省更多时间。
处理错误与重试
失败分为两类:你修复的和重试的。混淆它们会浪费时间,在重试风暴中还会浪费金钱。
修复这些
- 401 / 403——认证。 密钥缺失、过期或缺少访问权限。检查
HIAPI_API_KEY是否确实在运行命令的 shell 中导出——常见陷阱是在一个终端导出,在另一个终端运行脚本。 - 400——载荷格式错误。 无效 JSON、缺少
prompt或意外的字段类型。错误体通常会指出有问题的字段。在 curl 调用中小心引用你的 JSON。 - 404——路径错误。 验证模型标识符拼写与文档完全一致,并且你的基础 URL 没有重复或缺失的路径段。
重试这些,使用退避
- 429——速率受限。 放慢速度。尊重响应中的任何 retry-after 提示,并使用带抖动的指数退避。长期来看,限制你的并发。
- 5xx——服务器错误。 通常是暂时性的。重试有限次数(三次是合理默认值),延迟递增,然后大声失败。
一个最小重试包装器
import random, time
def with_retries(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except RuntimeError as exc:
if i == attempts - 1:
raise
time.sleep((2 ** i) + random.uniform(0, 0.5))
用它包装 generate_image。关键是从你这边使操作幂等:因为输出文件以提示词 ID 为键,重试会覆盖而不是重复。记录每次失败及提示词 ID 和服务器消息——当你确实需要升级时,该日志正是支持团队复现问题所需的。
后续步骤
你现在有了一个可工作的请求、一个值得保留的 Python 函数,以及大规模运行它的模式。要为生产加固,请添加带请求 ID 的结构化日志,将清单持久化到持久存储以便批处理作业在崩溃后恢复,并在发送前验证提示词,以便格式错误的输入快速且廉价地失败。
最有用的下一步是在 HiAPI API 上的其他模型上复用这个确切的客户端。由于端点路径、认证头和载荷结构是共享的,将脚本改编为新模型通常意味着更改模型标识符,偶尔更改一两个设置——小小的代码更改就能带来有意义的不同输出。
从一个提示词开始,确认文件生成,然后让批处理运行器处理其余部分。