FLUX.1 Fill Pro API 怎么用？5 分钟上手

TL;DR

它是什么：Black Forest Labs 的蒙版局部重绘模型。上传原图、同尺寸黑白蒙版和提示词，只重绘白色区域，黑色区域原样保留。已在 HiAPI 上线，打开模型页就能试，新用户注册送 200 积分。
多少钱：每张 $0.0715（143 积分），按成功出图计费，steps、guidance、seed、输出格式都不加价，失败退还预扣。$10 约 139 张。
最快怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 flux-1-fill-pro，input 里放 image、mask、prompt 三个字段，拿到 taskId 后轮询或等回调，下载 data.output[0].url。

蒙版重绘最容易踩的坑不是参数，是素材：蒙版必须和原图同尺寸，白色只盖要改的地方。下面先把这两件事说清楚，再跑第一次。

FLUX.1 Fill Pro 是什么？

它是一个「只改你圈出来那块」的编辑模型。改动范围由蒙版决定，不由文字决定，所以旁边的家具、阴影和地平线不会跟着变。

蒙版只盖住挂钟那一小块墙面，输出 1440 × 810。左侧挂毯、编织盘、野牛头骨、绿植、沙发和光线都没被重绘。

三件输入。 原图（JPEG / PNG / GIF / WebP）、同尺寸黑白蒙版、提示词（最多 4,000 字符）。
边界可控。 白色重绘、黑色保留，改动停止在蒙版边缘，适合商品精修、背景替换、服装换色这类「只动一处」的活。
输出跟随原图。 没有画幅参数，比例照搬原图；1600 × 900 的原图返回 1440 × 810，按 32 的倍数微调。
参数够用不复杂。 steps 15–50 默认 50，guidance 1.5–100 默认 60，可选 seed 和 jpg / png 输出。

A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.

用这个提示词生成 → 链接只预填提示词：原图位是空的，蒙版位默认放着示例蒙版。换成你自己的原图和同尺寸蒙版，再点运行。

蒙版怎么准备？

四个要点，按这个顺序做：

只有黑白两值。 白色是要重绘的区域，黑色是保留的区域。灰边会让边界发虚，尽量做出硬边。
尺寸和原图完全一致。 1600 × 900 的原图配 1600 × 900 的蒙版。不要截屏再缩放，直接从同一个文件导出蒙版，宽高对不上任务会失败。
白色区域贴紧目标。 盖住要改的东西就停手，不要把旁边的家具、台面、阴影带进来。
按原图分辨率导出 PNG。 PNG 不带压缩噪点，边界最干净；把蒙版和原图放在能被公网访问的地址上，接口收的是 URL，不是文件上传。

黑色保留、白色重绘。这张 1600 × 900 的蒙版只在挂钟位置留了一个白框，所以只有那块墙面会被重绘。

在线试用：4 步出第一张

模型页不能画蒙版，蒙版要在你自己的工具里做好再上传。

打开 FLUX.1 Fill Pro 模型页，注册或登录，新账号自带 200 积分。
上传原图，再上传同尺寸的黑白蒙版。
粘贴提示词，只描述白色区域里要出现的内容，并写清必须保留什么。
点运行。默认 steps 50、guidance 60、jpg 输出，先跑通再调参。

点「用这个提示词生成」打开页面时，提示词会自动填好。原图位是空的，蒙版位默认放着示例蒙版，换成自己的蒙版再运行。

API 接入：4 步

在控制台创建 API Key（sk-...）。
POST /v1/tasks 创建任务，input 里带 image、mask、prompt。
用 GET /v1/tasks/{taskId} 查询，或在请求里加 callback.url 等通知。
data.status 变成 success 后，从 data.output[0].url 下载图片，立刻存到自己的存储。

完整的字段表、错误码和参数说明见中文文档。

第一次蒙版重绘：curl 版

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
      "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
      "steps": 50,
      "guidance": 60,
      "output_format": "png"
    }
  }'

返回的任务 ID 在 data.taskId：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

查询结果：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

上面这两张图就是一比一的对照素材：1600 × 900 的原图和同尺寸蒙版，直接跑就能得到本文第一张挂画效果。

第一次蒙版重绘：Python 版

创建、轮询、下载一次写完，换上自己的 Key 就能跑：

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-fill-pro",
    "input": {
        "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
        "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
        "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
        "steps": 50,
        "guidance": 60,
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(3)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("fill-pro-edit.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

参数怎么调？

一次只改一个，出了差别才知道是哪一项起的作用。

steps（15–50，默认 50）：数值越高细节越细，默认值已经适合出片，往下调只在赶速度时用。
guidance（1.5–100，默认 60）：数值越高越贴近提示词。风格跑偏先往上加，画面僵硬再往回收。
seed：定稿后固定一个值，同图同蒙版同提示词能回到相近结果，方便回退和批量统一。
output_format：默认 jpg；要保留最多细节、或者后续还要再处理一遍，写 png。
prompt_upsampling：默认 false。开启会自动改写你的提示词，想完全控制措辞就保持关闭。

上线前注意这 4 件事

页面里画不出蒙版。 模型页和 API 都只收做好的蒙版图，尺寸还必须与原图一致。蒙版在 Photoshop、Figma、分割工具里做好再上；页面上只能上传，不能刷。
服务端用回调。 请求体加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务结束自动通知，比轮询省事；保留轮询做兜底。
超时不要重复 POST。 每次 POST /v1/tasks 都会新建任务、单独计费。先存 taskId，重试时复用同一个任务去查。
输出地址会过期。 拿到结果立刻下载存文件，别把 URL 当成永久地址；另外输出比例跟随原图、没有画幅参数，要固定版位就自己按比例裁切。