教程
如何通过 HiAPI API 调用 fibo-edit-1.5 图生图:curl 与 Python 指南
基于指令的图像编辑的可运行请求实操讲解
本页内容
fibo-edit-1.5 图生图端点能做什么
fibo-edit-1.5/image-to-image 是一个指令驱动的图像编辑端点。它并非从零描述场景,而是接收一张参考图和一段自然语言指令,返回一张应用了该编辑、同时保持其余构图不变的新图像。
这个定位会直接影响你设计请求的方式。参考图承载视觉上下文——主体、取景、光照、风格——指令承载变更。好的指令会明确说明什么要改,而对要保持不变的部分保持沉默。“把天空替换成多云的日落,保持建筑和前景不变”比“让它更好看”传达的信息更多。
一次成功的调用会产出一个编辑后的图像资源。根据端点的调用方式,响应会以你可以保存或获取的形式返回生成的输出——请查阅端点参考了解确切的响应结构和支持的参数。请将该参考视为字段名、可接受的图像格式和大小限制的唯一权威来源,因为这些细节可能会独立于本文档而演进。
典型用途包括产品照片修图、背景替换、风格调整,以及整图重生成会损失保真度的局部编辑。如果你的任务仅从文本生成而非编辑,那么这个端点不是合适的工具;请改用文生图模型。
需要尽早建立的一个预期是:编辑本质上是迭代的。你的第一条指令很少能完美命中,因此请围绕低成本的迭代来构建工作流——一次只改一个变量,保持参考图不变,在进入下一步前对比输出。
一个可用请求的构成
在写任何代码之前,先梳理清楚一个请求需要哪些输入。每次调用 fibo-edit-1.5/image-to-image 都会组合四类信息。
认证
所有请求都通过 HiAPI 统一接口,并在 Authorization 头中携带你的 API 密钥。请将密钥放在环境变量中而非源码里,并且永远不要提交它。
参考图
你需要提供编辑所作用的源图像。常见形式有两种:服务可抓取的公开 URL,或嵌入 JSON 请求体的 base64 编码数据。URL 更便于迭代;base64 则避免依赖外部托管。请查阅端点参考了解接受哪些形式以及任何尺寸或分辨率约束。
编辑指令
这是一段描述变更的通俗语言字符串。请将其写成祈使句,指明要更改的区域或元素,并说明应保留什么。避免把多个不相关的编辑堆进同一条指令——将它们拆分成多次调用,这样你才能判断是哪一个导致了糟糕的结果。
输出控制
可选旋钮,例如尺寸、输出格式或候选图像数量。首次调用时保持默认值,之后再有意识地调整。你设置的每一个参数,都是出问题时需要排除的又一个变量。
因此,一个最小请求体有两个实质性字段——图像和指令——被包裹在一个 JSON 对象中,可选地附带你的输出偏好。如果你能回答“哪张图、什么变更、我想要什么格式返回”,那么你就具备了编写该调用的一切条件。
用 curl 发起调用
从 curl 开始:它能隔离 HTTP 层,因此一旦出问题,你就知道问题出在请求而非应用代码。
先导出你的密钥:
export HIAPI_API_KEY="your-api-key"
然后发送包含参考图 URL 和指令的 JSON 请求体:
curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/input.jpg",
"prompt": "将平淡的天空替换为柔和的日落渐变;保持建筑和前景不变。"
}'
几点实用建议:
- 对照端点参考确认基础 URL 和路径,不要凭记忆复制。
- 使用
-sS,让 curl 在成功时保持安静,但仍会显示传输错误。 - 如果你不想依赖外部托管,请对文件进行 base64 编码,并将
image的值替换为编码后的字符串,并匹配参考中指定的字段名。 - 在探索阶段通过
jq .管道处理输出,让响应更易读。
要确认响应,请查找返回的图像载荷或 URL 并打开它。如果响应体包含的是错误对象,请记下其 type 和 message 字段——这些字段会告诉你问题出在图像、指令还是请求结构上。将一份成功的原始响应保存到文件;它将成为你编写 Python 客户端时的测试夹具,以及日后行为变更时的证据。
用 Python 发起同样的请求
Python 版本应与 curl 调用完全一致——相同的路径、相同的头部、相同的请求体——这样任何差异都是你代码中的 bug,而不是你所请求内容的差异。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"
payload = {
"image": "https://example.com/input.jpg",
"prompt": (
"将平淡的天空替换为柔和的日落渐变;"
"保持建筑和前景不变。"
),
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
发送本地文件
如果你编辑的是磁盘上的文件,请将其编码并发送字符串而非 URL:
import base64
with open("input.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"image": encoded,
"prompt": "将背景改成干净的中性灰;保持产品清晰。",
}
在依赖此方式之前,请先在端点参考中核实确切的字段名和预期编码。
存储输出
将返回的图像写入磁盘,以便你可以并排对比迭代结果,并记录哪条指令产生了哪个结果。一个小巧的辅助函数,按指令哈希派生出的名称保存输出,会让后续对比变得轻而易举。
务必设置显式的 timeout。图像编辑比简单的文本调用耗时更长,而无超时限制的请求会在网络停滞时让工作进程无限期挂起。
处理错误并安全重试
失败可归为几个大类,每一类都需要不同的应对方式。
客户端错误
请求本身有误:JSON 格式错误、缺少图像字段、不支持的图像格式、模型无法执行的指令,或认证问题。原样重试这些错误只会浪费时间和配额——它们会以完全相同的方式失败。请改为修正请求。遇到这类错误时,请记录完整的请求体(图像部分截断)和错误消息,然后修正输入。
速率限制
你发送请求的速度超过了允许的额度。正确的应对是退避并重试,而不是猛击端点。请遵循响应中提供的任何重试提示;否则使用指数退避。
服务端与瞬时错误
超时、连接重置和上游故障值得重试。这正是幂等重试逻辑的用武之地。
实用的重试策略
- 仅在超时、连接错误以及速率限制或服务端响应时重试。
- 使用带上限的指数退避——例如,从较短延迟开始,每次尝试翻倍,并在少量固定次数后停止。
- 为延迟添加抖动,以免并行工作进程在同一瞬间全部重试。
- 对于因 schema、格式或指令问题而被拒绝的请求,绝不重试。
- 记录每次尝试及其尝试次数和结果,以便你看出失败是否集中出现。
import random, time, requests
def edit_with_retry(payload, attempts=4):
delay = 1.0
for i in range(attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if r.status_code < 400:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
r.raise_for_status()
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 2, 30)
raise RuntimeError("重试后编辑仍然失败")
将此视为骨架:将可重试状态码与端点实际返回的内容对齐,并将策略集中在一处,让所有调用方共享。
上线之前的检查
在将端点接入生产环境之前,请完成一份简短的检查清单。
两次验证正常路径
针对相同输入重新运行你保存的 curl 调用和 Python 客户端,确认它们产生等效的结果。如果它们出现分歧,说明你的请求体实际上并不相同。
在真实输入上校准指令
用代表性图像测试你的指令,而不只是单个样本。编辑质量在很大程度上取决于指令的具体程度以及参考图对该变更的支持程度。保留一小套提示词-输出对作为回归测试套件;当你调整措辞时,就能看出哪些改进了、哪些退步了。
检查限制与格式
在端点参考中确认可接受的图像格式、最大尺寸以及任何请求大小上限。在发送前进行本地校验——在客户端拒绝一张糟糕的图像比一次往返更快也更便宜。
核实密钥与日志
确保 API 密钥来自环境变量,请求日志会截断图像载荷,并且没有任何密钥出现在错误报告中。
确认失败行为
在预发布环境中强制触发一次超时和一个格式错误的请求体,检查你的重试策略是否正确行事,以及永久性失败是否会暴露给调用方而非悄无声息地消失。
一旦这些都通过,这个集成就会以一种最好的方式变得平淡无奇。请从 fibo-edit-1.5 图生图端点参考获取权威参数列表,然后从可用的 curl 调用向外构建。