博客

教程

如何通过 HiAPI 调用 fibo-gen-1.5/text-to-image:curl 与 Python 指南

2026年11月12日
封面艺术:薄荷绿半色调圆点在近黑色背景上形成安静的密度渐变。
本页内容

用 curl 构建一个可用的请求

fibo-gen-1.5/text-to-image 是一个托管式文生图模型,通过标准的 HiAPI 请求模式访问。这个细节比初看起来更重要:你无需下载权重、搭建 GPU 或学习模型专属 SDK。你只需发送一个带有模型标识和提示词的 HTTP 请求,然后收到图像结果。集成工作集中在三处——如何设计提示词、设置哪些参数,以及如何处理响应。

在编写任何代码之前,有几项假设你可以放心采纳:

  • 认证方式统一。 每次 HiAPI 调用都在请求头中携带你的 API 密钥。不存在针对各模型的认证流程。
  • 模型按名称选择。 fibo-gen-1.5/text-to-image 作为模型字段放入请求体,必须原样书写,包括 /text-to-image 后缀。
  • 从调用方视角看,生成是同步的。 你发送请求、等待、收到输出。超时预算应反映真实生成延迟,而不是假设即时返回。
  • 响应是结构化的。 你收到的是 JSON 封装,而非原始二进制数据块,因此需要先解析才能使用图像。

如果你已集成过任何其他 HiAPI 模型,这会让你感到熟悉。如果这是你的第一个,你在此学到的模式可直接迁移到平台上的其他所有内容。真正属于模型专属的知识在于参数选择,本指南后续会介绍。

在 Python 中执行同一调用

从能够成功的最小调用开始。导出密钥,避免它以明文进入 shell 历史记录:

export HIAPI_API_KEY="your_api_key_here"

然后发送请求:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-gen-1.5/text-to-image",
    "prompt": "a weathered fisherman mending a net on a wooden dock at dawn, overcast light, 35mm photograph",
    "size": "1024x1024",
    "n": 1
  }'

有三点值得特别指出,因为它们是“复制粘贴碰运气”式尝试通常失败的地方:

  1. 模型字符串必须精确。 fibo-gen-1.5/text-to-image——不是 fibo-gen-1.5,也不是大小写变体。稍有偏差会返回模型未找到类错误,而不会静默回退。
  2. 密钥以 bearer token 形式放入 Authorization 头。 不要放在请求体或查询字符串中。
  3. Content-Type: application/json 是必需的。 缺少它,某些代理和网关会在负载到达 API 之前将其破坏。

如果你想查看确切的返回内容——包括响应头——在 curl 调用中加入 -i。当响应看起来为空时,这是最有用的调试习惯:它能告诉你收到的是 200 但响应体形状异常,还是需要处理的非 2xx 状态。探索时,可用 jq . 管道美化输出 JSON。

一旦成功,更换提示词并重新运行。保持调用其余部分不变,可将提示词变更与结构变更隔离开来。

投入生产环境

从可工作的脚本迈向可靠的集成,主要在于那些枯燥的部分。检查清单:

  • 密钥不进入代码。 从环境变量或密钥管理器加载,绝不提交,并按你能真正坚持的周期轮换。开发和生产使用不同密钥,这样开发密钥泄露不会拖垮线上流量。
  • 超时明确且有依据。 根据自身工作负载中观察到的生成延迟设定上限,而非猜测。记录每次调用的实际耗时,以便为这个数字提供依据。
  • 重试有界且有选择性。 对瞬时故障——超时、限流状况——使用指数退避和硬性尝试上限进行重试。绝不重试格式错误的负载或认证失败;它们每次都会以相同方式失败,浪费你的配额。
  • 输出在信任前经过验证。 检查解码出的字节数是否达到合理数量,以及文件能否作为有效图像打开。到达 CDN 的零字节或截断文件,比生成阶段直接报错更糟。
  • 每次生成都有记录。 将提示词、参数、响应和时间戳一起存储。这使日后实现可复现性和成本归因成为可能。
  • 调用封装在函数之后,而非散落各处。 统一使用一个 generate(),意味着你只需在一个地方修补重试逻辑、超时和日志记录。

先用 curl 发起一个干净的 fibo-gen-1.5/text-to-image 请求,再移植到 Python,然后围绕它添加运维层。请求的形状始终不变——变的只是你包裹在它周围的保障。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档