Black Forest Labs

FLUX.1 Fill Pro

flux-1-fill-pro

专业级局部重绘与外扩模型，按二值掩码定点替换、移除或延展画面，并保持光照与透视一致；需掩码输入，适合精修而非整图生成

flux-1-fill-pro

试用 flux-1-fill-pro

输入

作品灵感

查看全部作品

输出

image

填写参数并生成，结果会显示在这里。

价格

flux-1-fill-pro 每张

单价	$0.0715

定位简介

flux-1-fill-pro 是一款面向定点编辑的图像修复模型：输入原图与黑白蒙版，配合文本提示，仅重绘蒙版白色区域，黑色区域保持不变。适合产品图精修、电商素材局部换件、效果图调整与画幅延展等需要在既有构图上做外科手术式修改的场景。开发者通过 HiAPI.ai 统一接口调用，按张计费，无需自建图像编辑流水线。

核心亮点

蒙版驱动，定点重绘——只改动蒙版白色区域，其余像素保持原样，适合替换、移除、增补元素的精细修改。
同一接口覆盖修复与扩图——不改结构时做局部修复，需要时延展画布调整画幅，两类需求共用一套输入参数。
可复现的生成控制——通过 seed、steps、guidance 与 prompt_upsampling 控制随机性与提示词贴合度，便于批量出图与回归验证。

能力说明

蒙版局部重绘：传入原图、等尺寸黑白蒙版与提示词即可替换或新增指定区域内容，黑色区域原样保留，适合做局部换件与缺陷修补。

画幅延展与构图补全：可对图像边界外区域进行生成式延展，用于调整宽高比或补全画布，适配不同投放渠道的尺寸要求。

参数化质量控制：扩散步数 15–50、引导强度 1.5–100 可按需调节，步数越高细节越精细但耗时更长，引导强度越高越贴近提示词。

结果可复现与格式选择：固定 seed 可复现相近结果，便于批量任务与效果对比；输出可选 jpg 或 png，直接进入后续素材流程。

提示词自动改写开关：prompt_upsampling 默认关闭，开启后自动改写提示词以增加创意；需要严格按原文生成时保持关闭。

适用场景

电商运营：商品图局部换件与瑕疵修补——用蒙版圈定待替换的商品部件或污点，输入新描述，产出可上架的商品主图，减少重拍与整图重生成。
设计团队：效果图局部调整与画布延展——对建筑、室内等效果图的特定区域做修改或向外延展画布，产出适配不同版式的成图，保持光照与透视一致。
素材处理：去除干扰元素并自然填补——在原图上用蒙版标记不需要的物体，提示词描述填补内容，产出干净的图片用于后续排版与投放。

限制与选型建议

使用前必须准备与原图同尺寸的黑白蒙版，多一道区域标注或分割工序。它是编辑模型而非通用文生图模型，不适合从零生成完整图像；效果依赖蒙版质量与提示描述，复杂文字和精细结构可能需要多次调整。大面积或高分辨率编辑会显著增加耗时与调用成本，预算敏感或需要自部署权重的场景应另行评估。

近期更新

查看更新日志 →

模型上新新增 flux-1-fill-pro 蒙版局部重绘文档 Oct 19, 2026

常见问题

查看全部常见问题 →

什么是 FLUX.1 Fill Pro？

FLUX.1 Fill Pro 是面向蒙版局部重绘的图像编辑模型：上传原图、同尺寸黑白蒙版和提示词，只重绘白色区域，黑色区域保持不变。
蒙版的黑白分别代表什么？

黑色区域保留原图，白色区域由提示词重绘；蒙版必须与原图尺寸一致。
image 和 mask 都必须上传吗？

是。当前公开接口要求同时提供原图和黑白蒙版，缺一不可。
提示词应该写什么？

只描述蒙版白色区域里要出现的新内容，并说明必须保留的元素；不要重复描述蒙版外的画面。

提交生成任务

POST https://api.hiapi.ai/v1/tasks

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：flux-1-fill-pro

routestring可选

当前固定值：default

inputobject必填

flux-1-fill-pro 和线路 default 的业务参数对象，见下方参数表。

maskstring必填

黑白蒙版图，用于指定重绘区域：黑色区域保持不变，白色区域由提示词重绘。支持 JPEG、PNG、GIF、WebP 格式，尺寸必须与原图一致。

seedinteger可选

随机种子，固定该值后可复现相近结果；不传则随机生成。

imagestring必填

要编辑的原图，支持 JPEG、PNG、GIF、WebP 格式，可包含 alpha 蒙版。若使用独立蒙版，请确保其与原图尺寸一致。

stepsinteger可选默认值: 50min 15max 50

扩散步数，取值范围 15–50，默认 50；数值越高细节越精细，耗时也越长。

promptstring必填minLength 1maxLength 4000

描述要在蒙版白色区域生成或替换的内容，最多 4000 个字符。

guidancenumber可选默认值: 60min 1.5max 100

提示词引导强度，取值范围 1.5–100，默认 60；数值越高越贴近提示词，但可能降低画面自然度。

output_formatstring可选默认值: "jpg"

输出图片格式，取值为 jpg 或 png，默认 jpg。

可选项：jpgpng

prompt_upsamplingboolean可选默认值: false

是否自动改写提示词以增加创意，默认 false；需要严格按原文生成时应关闭。

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux-1-fill-pro",
  "input": {
    "mask": "…",
    "image": "…",
    "steps": 50,
    "prompt": "…",
    "guidance": 60,
    "output_format": "jpg",
    "prompt_upsampling": false
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "flux-1-fill-pro",
    input: {
      "mask": "…",
      "image": "…",
      "steps": 50,
      "prompt": "…",
      "guidance": 60,
      "output_format": "jpg",
      "prompt_upsampling": false
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "flux-1-fill-pro",
        "input": {
          "mask": "…",
          "image": "…",
          "steps": 50,
          "prompt": "…",
          "guidance": 60,
          "output_format": "jpg",
          "prompt_upsampling": False
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

获取任务详情

GET https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}