教程
如何通过 HiAPI API 调用 flux-1-fill-pro:curl、Python 与异步轮询
本页内容
flux-1-fill-pro 的作用与适用场景
flux-1-fill-pro 是一个填充类图像编辑模型。你向它提供一张源图和一个标记待重生成区域的蒙版,它会输出一张该区域已被替换的新图像。蒙版之外的区域理应保持不变,这正是它与纯文生图模型或全图风格化模型的区别所在。
当编辑是局部的、且周围上下文很重要时,就该用它:
- 物体移除 —— 用蒙版圈出不需要的元素,让模型重建其背后理应存在的内容。
- 物体替换 —— 用蒙版圈定区域,在提示词中描述新内容,同时保持场景其余部分不变。
- 局部修补 —— 修复纹理、反光或小的瑕疵,而无需重新生成整个画面。
- 流水线插入 —— 以程序方式修补商品图、缩略图或生成素材,其中只有一个区域需要二次处理。
当你希望根据提示词得到一幅全新构图,或者你的蒙版区域大到模型实际上是在从零生成图像时,它就不是合适的工具——那种情况下,标准生成端点会表现得更加可预测。
本指南余下部分讲的是如何通过 HiAPI API 把 flux-1-fill-pro 接入代码:请求结构、curl 调用、Python 等价写法,以及大多数初次集成都容易搞错的异步任务处理。
准备工作与身份验证设置
在发出第一个请求之前,先确认三件事。
API 密钥
在你的 HiAPI 账户中创建一个密钥,并让它远离源码控制。下面的示例从环境变量中读取它,因此这些代码片段可以安全复制:
export HIAPI_API_KEY="your_key_here"
在 Python 中通过 os.environ 以同样的方式加载。如果你在 CI 中运行,请将其作为密钥注入,而不是提交一个 .env 文件。
模型标识符
每个请求都按名称指定模型。本指南中该标识符为 flux-1-fill-pro。请把它作为常量保留在代码中,而不是散落字符串字面量——这样以后更换模型只需改一行。
基础 URL
所有调用都发往平台参考文档中记录的 HiAPI API 基础 URL。请把它与密钥一起放在配置中,这样预发与生产环境无需改代码即可不同。
开始之前有一条结构性提醒:填充请求携带图像数据。请以 JSON 形式发送 base64 编码的图像,而不是试图强行通过表单上传;同时让客户端的请求超时保持充裕——编码大图会在请求离开你的进程之前就增加延迟。请查阅平台文档了解当前载荷大小限制;如果你的源图超过文档上限,请在编码前先缩小它,而不是让请求在边缘处失败。
局部重绘请求的结构
无论用什么语言编写,每次 flux-1-fill-pro 调用都有相同的逻辑构成。
源图
你要编辑的图像,编码为字符串。它定义了画布:其尺寸决定了蒙版所处的坐标空间,其内容为模型提供使填充显得可信的上下文。
蒙版
蒙版标记哪些区域会被重生成。这是最常见的混淆来源,因此请明确你的载荷采用哪种约定:被蒙版标记的区域就是模型允许改动的区域。把蒙版构建为一张单独的图像,让待填充区域与待保留区域在视觉上明显区分。把蒙版反相是经典 bug——你会得到一张模型编辑了除你想要的区域之外所有内容的结果。
蒙版必须与源图尺寸完全一致。以不同分辨率绘制的蒙版要么被拒绝,要么被静默错位,两种结果都会浪费一次往返。
提示词
对蒙版内应出现内容的文字描述。请保持具体且局部:描述内容及其与周围环境在光照或纹理上的关系,而不是整个场景。“一条木质长椅,延续店面的饰边,左侧柔和的午后光线”比“更好看的背景”能给模型更多依据。
可选控制项
视文档化的参数集而定,你可能还可以传入诸如用于可复现的 seed,或控制填充可偏离原始像素程度的强度类参数。对于当前参考文档中不存在的参数,请按不支持处理,而不要猜测其名称。
这四者——模型、提示词、源图、蒙版——都在同一个 JSON 体中传递。接下来的两节发送的就是这个体。
一个可用的 curl 请求
先从 curl 开始,这样你能在任何客户端库将其遮蔽之前看到原始信封。
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
其中 request.json 如下所示:
{
"model": "flux-1-fill-pro",
"prompt": "一条木质长椅,延续店面的饰边,左侧柔和的午后光线",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
构建该文件有两个实用技巧。第一,用命令生成 base64 载荷,而不是手动粘贴:
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
然后用一小段 jq 或 Python 步骤把它们拼接进去,组装出 request.json。手动把多兆字节的 base64 数据块编辑进 JSON,正是导致载荷被截断和令人困惑的 400 错误的根源。
解读响应
响应信封会告诉你下一步该做什么。已完成的任务返回编辑后的图像——通常以 URL 或 base64 字段形式,与当前参考文档规定的格式一致。已排队的任务返回一个标识符和一个状态,随后由你轮询(见下文)。不要假设第一次响应总包含像素;从第一天起就把解析器写成能处理两种形态,否则第一次在负载下任务排队时你就得重写它。
在解析响应体之前先检查 HTTP 状态码。4xx 意味着请求本身有误,重试无济于事;请改为修正载荷。
同样的调用用 Python 实现
Python 版本是同一个请求,但用起来更顺手。无需 SDK——用 requests 请求 HiAPI 端点就足够了。
import base64
import json
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"
def b64(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("ascii")
def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
payload = {
"model": MODEL,
"prompt": prompt,
"image": b64(source_path),
"mask": b64(mask_path),
}
resp = requests.post(
f"{BASE_URL}/v1/images/edits",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=120,
)
if resp.status_code >= 400:
raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
return resp.json()
timeout 是有意设置的。编码和上传大图比典型的 JSON 调用耗时更长,而无界请求正是脚本在批处理任务中静默挂起的原因。在 4xx 时抛出异常并附带响应体,能把神秘失败变成可读的失败。
把模型标识符和端点放在模块级配置中,这样版本升级只需改一处。如果你要处理大量图像,请复用一个 requests.Session,让连接被池化,而不是每次调用都重新建立。
解析出的字典要么是已完成的结果,要么是任务句柄——下一节处理后者。
处理异步任务与轮询
填充请求可能很慢,因此 API 可能返回任务句柄而不是成品图像。正确的模式是有界轮询循环,而不是固定 sleep 然后祈祷。
循环
def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
deadline = time.monotonic() + timeout
current = job
while time.monotonic() < deadline:
status = current.get("status")
if status in {"succeeded", "completed"}:
return current
if status in {"failed", "canceled", "cancelled"}:
raise RuntimeError(f"Job ended as {status}: {current}")
time.sleep(interval)
interval = min(interval * 1.5, 15.0) # 温和退避
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job 与上面的请求模式相同,使用任务 id 和你的认证头访问文档化的任务状态端点。
为何用退避而不是固定间隔
对队列进行紧密循环轮询会白白猛打 API 而无任何收益。从较短的间隔开始并逐次倍增直到上限,既能保持早期完成时的快速响应,又不会在慢任务上浪费成千上万次轮询。给间隔设上限,这样你仍能在数秒内察觉到完成。
为何超时与失败是两回事
超时意味着你停止了等待,而不是任务失败。抛出异常时保留任务 id,这样调用方可以稍后恢复轮询,而不必重新提交并为同样的工作付两次费。在你的流水线中把超时、任务失败和 HTTP 错误视为三种不同的异常——把它们压缩成一个通用错误会让生产事故的排查困难得多。
调试常见故障
大多数错误响应都落入几个类别。请按顺序检查这些。
401 / 403 —— 身份验证
首先检查:请求头是否恰好是 Authorization: Bearer <key>,没有引号,也没有来自从未导出的 shell 变量的多余空白?空的 $HIAPI_API_KEY 会产生一个只有 Bearer 一词的 Bearer 令牌,其失败方式与错误密钥相同。
400 —— 载荷格式错误
首先检查:在拼接 base64 字符串之后,请求体是否仍是合法 JSON?把 request.json 导出并用 python -m json.tool 跑一遍。图像字段上带有 data:image/png;base64, 前缀是常见原因——除非参考文档明确要求,否则请去掉它们。
蒙版/图像不匹配
首先检查:蒙版与源图的像素尺寸是否完全一致?然后验证极性——确认白色区域就是你希望模型重生成的区域。结果看起来与你要求相反,几乎总是蒙版反相,而不是提示词问题。
提示词溢出
如果未蒙版区域发生了变化,或填充看起来是全局的,你的蒙版可能太大,或提示词过于覆盖整个场景。两者都收窄:把蒙版收紧到实际编辑区域,只描述蒙版内的内容。
任务超时
首先检查:载荷大小。过大的源图是任务永不完成的最常见原因。先缩小、重试一次,如果仍然超时,用一张小测试图对照参考限制,再假定是服务问题。
结果字段为空或缺失
首先检查:你是否处理了排队响应的形态。只读取已完成形态的解析器在第一次调用时会什么也看不到。开发期间记录完整的响应信封,这样在编写防御性代码之前就能看清形态。