教程
如何通过 HiAPI API 调用 fibo-2.0/image-to-image:curl 与 Python 实践
本页内容
fibo-2.0/image-to-image 在流水线中的定位
文生图模型从一句提示词开始,图生图模型则从你已有的图像开始。这个差异看似不大,却决定了模型在流水线中的位置:fibo-2.0/image-to-image 不再是一开始产出素材的第一步,而是改造既有图像的编辑步骤。
典型的工作流是这样的:你获取或生成一张基础图像,用描述所需改动的指令将它送入 fibo-2.0/image-to-image,再把返回结果交给后续环节——审核、合成、存储,或另一次模型调用。由于模型同时接收输入图像和提示词,它能在重绘风格、调整或改造你描述的部分的同时,保留构图、主体位置和整体结构。
何时选择图生图而非文生图
当输出需要与现有图像保持可辨识的关联时,就选图生图:在保留主体的前提下为照片重绘风格、调整光照或色彩处理、为已批准的素材生成变体,或在最终使用前清理粗糙的底图。若你手头没有起始图像、只有一段描述,则选文生图。
该接口对你的要求
这次调用是一次作业提交:你发送输入图像、提示词以及想控制的参数,API 返回一个可追踪的作业。应把这个接口看作更大链路中一个定义清晰的阶段,而非完整的编辑应用——如何准备输入图像、如何处理结果,都由你负责。
由于请求本质上是异步的,集成设计也应围绕这一点展开:提交、保存作业标识符、轮询直至作业完成,然后获取输出引用。本指南余下部分正是构建这套流程。
发送请求前的准备
首次调用前需备好三件事:凭证、对接口形态的正确理解,以及一张准备好的输入图像。
凭证
所有发往 HiAPI API 的请求都用 API 密钥认证。密钥必须保存在服务端——绝不要嵌入浏览器代码或提交到代码仓库。最干净的做法是从环境变量读取,让同一套代码在本地和部署环境中通用:
export HIAPI_API_KEY="your-api-key"
如果还没有密钥,请先在 HiAPI 账户控制台创建,再继续操作。
接口形态
该模型在 HiAPI API 中的标识为 fibo-2.0/image-to-image。所有模型调用共用同一基础 URL 和请求约定,这意味着一旦你有一个可用的调用,改用其他模型主要就是修改模型标识和载荷字段。
准备输入图像
图生图请求需要真实的图像,而不是一个你希望它能解析的 URL。事先想好如何提供:作为随请求上传的本地文件,还是 API 接受的引用;并在编写应用代码前确认格式可用。首次请求最常见的两类失败是:发送只存在于你笔记本上的路径,以及发送接口不接受格式的文件。
构建调用前的实用检查清单:
- 该图像是你所用语言能读取的真实文件。
- 提示词用平实语言描述想要的编辑,而不只是关键词堆砌。
- 你清楚要传哪些参数、哪些保持默认。
- 发起请求的环境中能找到你的 API 密钥。
这些就绪后,就可以进入请求本身。
逐行解析可用的 curl 请求
从 curl 开始。它消除了你与 HTTP 请求之间的所有抽象,一旦出错,你能确定问题在请求而非客户端库。
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
下面逐项说明各部分的作用。
请求行
-X POST 设置方法。URL 是 HiAPI API 基础地址加上图像生成路径。应把基础地址放在变量或配置值中,避免在多处硬编码,这样将来改动只需编辑一处。
请求头
Authorization: Bearer $HIAPI_API_KEY 携带你的凭证;shell 会展开你先前导出的环境变量,因此密钥不会以字面形式出现在命令历史中。Content-Type: application/json 告诉 API 将请求体按 JSON 解析。发送 JSON 请求体却漏掉该请求头,是导致难懂错误的常见原因。
载荷
model 标识 fibo-2.0/image-to-image。prompt 是你的指令——描述编辑,而非整张输出图像,因为输入图像已经承载了结构。image 是接口可接受的输入图像形式;若直接内嵌,即对文件内容做 base64 编码。n 控制请求的输出数量,保持默认是最安全的起点。
如果图像较大,直接嵌入 shell 命令会变得笨重。先将其编码到文件再引用,或直接改用下一节的 Python 方法——在那里读取文件并编码只需一行。
读取响应
不要假设响应中包含已完成的图像字节。运行 curl 调用并检查 JSON:你要找的是作业标识符或状态字段,以判断任务是已完成还是仍在运行。在写任何解析代码前先捕获结构,因为响应的形态决定了你如何轮询。
将请求移植到 Python
Python 让请求更易维护,并可将它封装成能在整个代码库中复用的函数。下面是同一请求实现的轻量客户端:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
为什么采用这种结构
把 encode_image 与 submit_image_edit 分离,让文件处理和 HTTP 处理相互独立,各自更易测试。在导入时从环境读取密钥,缺失时会立即失败,而不是在若干层之后才产生 401。显式设置 timeout 可避免连接停滞导致工作进程无限挂起。
处理响应体
raise_for_status() 将 HTTP 层失败转为可捕获并附带响应体日志的异常——这远比默默把错误对象当成功解析要有用。拿到解析后的 JSON 后,记录其中包含的作业标识符,并在开发期间记录完整响应,以便看清到底有哪些字段。不要基于假设编写解析器;要基于你实际观察到的响应来写。
保持可复用
两个小改进很快就能带来回报:将基础 URL 和模型名放入常量,让其他模型调用共用该客户端;让提交函数返回类型化结构(小型 dataclass 或已知键的 dict),使轮询代码有稳定的契约可依赖。
处理异步生命周期与轮询
图像作业不是瞬时完成的。集成应将提交与完成视为两个独立事件。
步骤 1:提交并持久化
提交作业后,将作业标识符存到持久位置——数据库行、队列消息,或至少一行日志。如果进程在提交与完成之间崩溃,未记录的作业就是丢失的工作。将标识符与你系统中拥有该结果的实体绑定,以便日后对账。
步骤 2:带退避的轮询
以合理间隔轮询作业状态接口。紧循环反复轰击状态接口既浪费资源,也是最常见的异步错误:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
从较短间隔开始并逐步增长,既能保持早期检查的响应性,又避免长期高频请求。硬性截止时间防止对永不完成的作业无限等待。
步骤 3:把失败当作正常结果
完成的作业不一定是成功的作业。读取输出前先检查状态,并显式分支处理失败:记录作业返回的错误详情,向调用方发出可重试信号,并决定重试应复用同一输入还是重新生成。客户端侧已超时的作业可能仍在服务端运行,因此不要未经检查就盲目重新提交。
步骤 4:获取并存储结果
作业报告成功后,读取它提供的输出引用并及时下载。若要长期存储结果,请复制到你自己的存储中,而不要依赖引用永久有效。
常见错误及修复方法
大多数失败可归入几类可预测的情形。请按顺序过一遍这份清单。
身份验证失败
401 或 403 几乎总意味着请求头错误或密钥缺失。确认请求头严格为 Authorization: Bearer <key>,Bearer 后有一个空格;并确认环境变量确实设置在发起请求的进程中——而不只是你的交互式 shell 里。粘贴密钥时带尾随空白或多余引号,占了这类问题的相当大比例。
载荷格式错误
400 或 422 通常意味着 API 无法解释请求体。按顺序检查三件事:Content-Type: application/json 是否存在、JSON 是否真能解析(尾随逗号会破坏它)、必需字段是否以正确名称存在。若发送 base64 图像数据,确认它是合法 base64 且底层文件格式受支持——截断或双重编码的字符串会产生令人困惑的校验错误。
轮询错误
如果作业似乎永不完成,确认你轮询时使用的是提交响应实际返回的标识符,且读取的是正确的状态字段。忽略 failed 状态的紧循环看起来会像挂起。加入硬超时并记录观察到的状态变化;该日志通常能立刻揭示问题。
响应解析陷阱
若代码在读取结果时抛异常,不要猜测响应形态。先记录原始响应体。常见问题包括:把引用误当字节、把仅在成功时才有的字段当作始终存在、用失败路径解析器解析成功响应。基于你实际见过的响应来构建提取逻辑。
快速分诊习惯
出问题时,先隔离层级:用相同载荷运行 curl 命令。若 curl 成功而 Python 失败,错误在客户端;若两者都失败,错误在请求。这一简单测试比任何其他调试习惯都省时间。
有了可用的调用和稳健的轮询循环,fibo-2.0/image-to-image 就成为可靠的编辑步骤——从 HiAPI 的模型页面开始,将上述请求适配到你自己的图像。