FLUX.1 Fill Pro API
https://api.hiapi.ai /v1/tasks Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).
Model summary
| Model name | flux-1-fill-pro |
|---|---|
| Type | Image editing (mask-based inpainting) |
| Endpoint | POST /v1/tasks |
| Pricing | See HiAPI Pricing |
FLUX.1 Fill Pro repaints only the masked area of an image: upload a source and a black-and-white mask for product retouching, background replacement and local clean-up.
Production guidance
- For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
- GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
- Result URLs expire — copy the output to your own storage once the task succeeds.
Best suited for
Replace one area of a product while keeping packaging text, shape and studio lighting.
imagemaskpromptMask the background or clutter and let the prompt rebuild the scene without touching the subject.
maskpromptChange wall art, tabletop material or floor texture while keeping the room layout and light direction.
imagemaskRequest parameters
model string required Fixed value flux-1-fill-pro.
input object required Business parameters.
image string required Source image URL (http/https). JPEG, PNG, GIF or WebP. When a mask is used, both must have the same dimensions.
mask string required Black-and-white mask URL. Black keeps the source and white is repainted; must match the source dimensions. JPEG, PNG, GIF or WebP.
prompt string required Describe the new content inside the white mask. Up to 4,000 characters.
steps integer optional Diffusion steps from 15 to 50. Higher values add detail and take longer.
guidance number optional Prompt guidance from 1.5 to 100. Higher values follow the prompt more closely but may reduce naturalness.
seed integer optional Random seed. A fixed seed with the same inputs gives a consistent result.
output_format enum optional Output image format.
prompt_upsampling boolean optional Automatically rewrite the prompt for more creativity. Turn it off to follow the exact wording.
callback object optional Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.
url string required Required when callback is set; HTTPS URL that receives terminal task notifications.
when enum optional Callback trigger timing. Use final.
Example requests
The mask covers only the wall around the clock; the prompt describes the new painting while the sofa, furniture, floor and lighting stay unchanged.
{
"model": "flux-1-fill-pro",
"input": {
"image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
"mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/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",
"prompt_upsampling": false
}
}Keep the same source, mask and prompt and fix the seed to compare different steps or guidance combinations.
{
"model": "flux-1-fill-pro",
"input": {
"image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
"mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/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",
"prompt_upsampling": false,
"seed": 12345
}
}Getting the result
- The response returns a taskId immediately without waiting for generation to finish.
- In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
- When status=success, read the image URL from output and download it.
- When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.
FAQ
What do black and white mean in the mask?
Black keeps the source and white is repainted by the prompt. The mask must match the source dimensions.
Are both image and mask required?
Yes. The current public contract requires a source image and a black-and-white mask.
What should the prompt describe?
Describe only the new content inside the white mask and state what must be preserved; do not repeat the area outside the mask.
How should I choose steps and guidance?
steps ranges from 15 to 50 (default 50); guidance ranges from 1.5 to 100 (default 60). Higher values usually add detail and follow the prompt more closely, and may take longer.
Does the output keep the source size?
The output keeps the source aspect ratio. Actual pixels follow the task result; a 1600×900 source produced a 1440×810 image in this example.
Which input and output formats are supported?
The source and mask accept JPEG, PNG, GIF and WebP; choose jpg or png for the output.
How can I make results more stable?
Fix seed and reuse the same source, mask and prompt. Changing steps or guidance changes detail and adherence.
How is it billed?
Per output image, one image per request. See the live pricing page for the current rate.