教程
如何通过 HiAPI API 调用 fibo-2.0/text-to-image:curl 与 Python 实战
本页内容
本教程构建的内容
这是一篇动手实战指南,带你从 HiAPI 上的 fibo-2.0/text-to-image 真正拿回一张图片。到结束时,你将拥有两样可以立即运行的东西:一条能生成有效图像生成请求的 curl 命令,以及一个做同样事情并返回结果供后续处理的小型 Python 函数。
我们会按照大多数开发者实际工作的顺序推进。首先,确认环境和凭据已就位。然后逐个字段阅读请求体,让你清楚每个部分控制什么。接着用 curl 发送调用,以证明端点、密钥和请求负载三者一致。只有在这之后,我们才把同样的请求移植到 Python 中,在那里,真正有趣的工作——解析响应、处理失败、把它封装成函数——才开始。
目标不是枚举所有可能的参数,而是给你一个你完全理解的请求形态,让你能够调整提示词、输出尺寸和周边代码,适配你自己的用例,而无需猜测。
发送第一个请求之前
首次调用成功之前,需要满足三个条件。
HiAPI 账号和 API 密钥
对 fibo-2.0/text-to-image 的请求需要认证。在你的 HiAPI 账号中生成 API 密钥,并让它远离源代码管理。下面的示例从环境变量读取密钥,而不是硬编码——从第一天起就这样做,因为事后补上密钥处理会很繁琐。
export HIAPI_API_KEY="your-api-key-here"
一个能发送 HTTP 请求的工具
对于 curl 实战部分,你的机器上需要 curl。它随 macOS 和大多数 Linux 发行版一起提供;在 Windows 上,当前版本和 Windows Terminal 中也可用。对于 Python 部分,你需要 Python 3 和 requests 库,这是从脚本发起 HTTP 调用最常见的方式。如果你还没有安装:
pip install requests
清楚你想生成什么
准备好一个提示词。图像模型对具体、明确的描述反应强烈——主体、风格、光照和构图——所以一行想法通常就足以开始测试。看到第一个结果后你会继续优化它;这是正常的循环。
这三项就位后,剩下的一切都关于请求体。
逐字段解析请求
fibo-2.0/text-to-image 调用是一个带 JSON 请求体的 POST 请求。请求体很小:一个提示词和塑造输出的设置。与其死记完整负载,不如理解每个字段,这样你才能有意识地修改它。
模型标识符
端点路径本身就指明了模型:fibo-2.0/text-to-image。在大多数情况下,你不需要额外传递模型字符串——你调用的路由决定了运行哪个模型。如果你的集成支持通过共享端点路由,请把模型名称放在一个配置常量中,这样你就能在不改动调用点的情况下切换它。
提示词
这是核心输入:你想要图像的文本描述。把它当作规格说明,而不是愿望。说出主体、视觉风格和构图,比抽象概念能给模型更多可用的信息。把提示词放在变量或单独文件中,这样你可以快速迭代,而无需重写请求代码。
输出设置
图像请求通常携带一小套输出控制项——最常见的是生成图像的尺寸或宽高比,以及如果你想要多张结果时的数量。使用 HiAPI 模型参考中为 fibo-2.0/text-to-image 文档化的字段名;下面的示例负载使用这些规范名称。如果某个设置没有为该模型文档化,就省略它,而不是猜测——未知字段是验证错误的常见来源。
不要放进请求体的内容
不要把 API 密钥放进 JSON 请求体。认证属于请求头。让凭据远离负载意味着请求体可以安全地在调试时记录和对比,第一次请求失败时你就会体会到这一点。
一条可用的 curl 请求
下面是一个完整调用。替换你自己的提示词,并在已设置 HIAPI_API_KEY 的 shell 中运行它。
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "黎明时分宁静的港口,水面上笼罩着轻柔薄雾,宽幅构图,摄影风格",
"size": "1024x1024",
"n": 1
}'
每个部分的作用
-X POST设置 HTTP 方法。图像生成是创建操作,所以是 POST,不是 GET。- URL 指向 HiAPI API 主机上的
fibo-2.0/text-to-image路由。如果你的账号使用区域性或项目专用的基础 URL,请替换该主机并保留路径。 Authorization: Bearer $HIAPI_API_KEY从环境传递你的密钥。shell 会展开变量,所以密钥永远不会以字面字符串的形式出现在你的命令历史中。Content-Type: application/json告诉服务器请求体是 JSON。没有它,许多网关会在请求到达模型之前就拒绝它。-d '...'是 JSON 请求体:提示词、请求的尺寸和一张图像的数量。
验证结果
运行命令,先看原始输出。成功的调用返回描述生成图像的 JSON 文档;失败的调用返回错误对象。在你在此基础上构建任何东西之前,确认你能用肉眼区分这两者。如果响应很大,用 jq 之类的格式化工具处理,让结构可读:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"黎明时分宁静的港口","size":"1024x1024","n":1}' | jq .
一旦手动调用成功,你就排除了凭据和负载作为嫌疑对象。此后的所有问题都在你的代码里。
Python 中的同一调用
Python 版本做的正是 shell 命令所做的事,但为你提供了验证输入、重试和存储结果的地方。保持它小而明确。
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"黎明时分宁静的港口,水面上笼罩着轻柔薄雾,宽幅构图,摄影风格"
)
print(result)
为什么这样写
- 密钥在函数内部从环境读取,因此如果缺失,调用会在启动时大声失败,而不是发送未认证的请求。
json=payload让requests序列化请求体并正确设置内容类型。不要在 Python 中手工构建 JSON 字符串;这会引入直到运行时才发现的引号错误。timeout=60让缓慢的失败变得明确。图像生成不是瞬时的,所以选择一个你愿意等待的超时时间,但一定要设置一个。raise_for_status()把 4xx 和 5xx 响应变成异常。正是这一行阻止了失败的调用被默默当作成功处理。- 函数以
prompt、size和n为参数,这样你的程序其余部分可以像调用其他库函数一样调用它。
运行该文件,你应该会看到与 curl 调用返回相同的 JSON 结构。
读取响应并处理错误
成功的响应会给你一个描述生成输出的 JSON 对象。你关心的细节是生成的图像本身——通常是一个你可以下载或存储的 URL 或引用——以及 API 返回的关于请求的任何元数据。把响应当作数据来解析;不要用字符串操作来抓取它。如果你第一次检查实时响应时形状不符合预期,在调整解析器之前先检查模型参考,因为猜测字段名正是集成悄悄断裂的方式。
检测失败
有三层失败值得有意处理。
传输错误。 请求从未完成:DNS 失败、连接重置、超时。在 Python 中,这些会表现为 requests.exceptions,它们是安全的,可以带退避重试。
HTTP 错误状态。 服务器回答了但拒绝了请求。401 通常意味着密钥缺失或错误;4xx 验证错误通常意味着字段名或值不对;429 意味着你发送得太快;5xx 意味着服务器端出了问题。raise_for_status() 把所有这些都捕获为一种异常,所以在决定做什么之前,先检查响应体中的消息。
状态码 200 但响应体意外。 这就是为什么你要验证结构而不是假设。在使用之前检查你依赖的字段是否存在,即使状态码是 200,也要把缺少图像引用视为失败。
try:
result = generate_image("黎明时分宁静的港口")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
重要的习惯:永远不要默默吞掉错误。至少记录状态码和响应体,因为这一对信息能告诉你,是该修复负载,还是等待并重试。
走向生产环境
一旦单次调用可用且失败可见,几个小习惯就能让集成在真实流量下站得住脚。
只重试安全的重试
传输错误、超时、429 和 5xx 响应值得用指数退避和尝试上限来重试。验证错误和 401 不值得——重试格式错误的请求只会消耗配额。在错误处理中明确区分这两类。
让配置远离代码
把 API 基础 URL、模型路径、默认尺寸和超时放在配置中,而不是散落在函数里。当你从测试环境迁移到不同环境,或之后尝试同类模型时,只需改一个地方。
记录请求和响应,但去掉密钥
记录提示词、参数、状态码和截断的响应。永远不要记录 API 密钥。这样你才能在一周后回答“为什么这张图回来不对”,而无需复现。
发送前验证输入
检查提示词非空且在合理长度内,并检查 size 和 n 与模型文档化的值匹配。在本地捕获错误值比一次往返更快、更便宜。
存储结果,不要只是打印
生成的图像引用可能是临时的。作为同一作业的一部分,把输出下载或复制到你自己的存储中,并记录是哪个提示词和参数产生了它。那条记录使重新生成和审计成为可能。
把 fibo-2.0/text-to-image 封装在本教程的小型 generate_image 函数之后,让你的应用其余部分依赖该函数,而不是原始 HTTP 调用。当你准备大规模变化提示词时,HiAPI 模型参考是你在扩展接口之前确认支持参数的地方。