Tutorial

Como usar a API do FLUX.1 Fill Pro? Faça a primeira repintura com máscara em 5 minutos

Os quatro requisitos rígidos da máscara, 4 passos para o teste online e 4 passos para a integração via API, com curl e Python prontos para executar.

Oct 28, 2026

TL;DR

O que é: o modelo de repintura local com máscara da Black Forest Labs. Envie a imagem original, uma máscara preto e branco do mesmo tamanho e o prompt; apenas a área branca é repintada, e a área preta é preservada como está. Já está disponível na HiAPI; abra a página do modelo para testar, e novos usuários ganham 200 créditos ao se cadastrar.
Quanto custa: US$ 0,0715 por imagem (143 créditos), cobrado apenas por geração bem-sucedida; steps, guidance, seed e formato de saída não têm acréscimo, e falhas estornam o valor pré-cobrado. Com US$ 10 dá cerca de 139 imagens.
Como chamar mais rápido: POST https://api.hiapi.ai/v1/tasks, com model definido como flux-1-fill-pro e input contendo os três campos image, mask e prompt; após obter o taskId, faça polling ou aguarde o callback e baixe data.output[0].url.

O maior problema da repintura com máscara não são os parâmetros, mas os materiais: a máscara precisa ter exatamente o mesmo tamanho da imagem original, e o branco deve cobrir apenas o que você quer alterar. Vamos esclarecer esses dois pontos primeiro e depois fazer a primeira execução.

O que é o FLUX.1 Fill Pro?

É um modelo de edição que altera "apenas a área que você delimita". O escopo da alteração é definido pela máscara, não pelo texto, então móveis, sombras e o horizonte ao redor não mudam.

A máscara cobre apenas um pequeno trecho da parede onde está o relógio, e a saída é 1440 × 810. A tapeçaria à esquerda, o prato de fibra, o crânio de bisão, as plantas, o sofá e a iluminação não foram repintados.

Três entradas. Imagem original (JPEG / PNG / GIF / WebP), máscara preto e branco do mesmo tamanho e prompt (até 4.000 caracteres).
Limite controlável. Branco é repintado e preto é preservado; a alteração para na borda da máscara, ideal para retoque de produtos, troca de fundo e mudança de cor de peças de roupa — trabalhos em que "só se mexe em um ponto".
A saída acompanha a imagem original. Não há parâmetro de proporção; a proporção segue a imagem original. Uma imagem de 1600 × 900 retorna 1440 × 810, com ajuste fino para múltiplos de 32.
Parâmetros suficientes e simples. steps de 15–50, padrão 50; guidance de 1,5–100, padrão 60; seed opcional e saída 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.

Gerar com este prompt → O link apenas preenche o prompt: o campo da imagem original fica vazio e o campo da máscara vem com a máscara de exemplo. Substitua pela sua própria imagem original e por uma máscara do mesmo tamanho, e então clique em executar.

Como preparar a máscara?

Quatro pontos, nesta ordem:

Apenas dois valores, preto e branco. Branco é a área a repintar e preto é a área a preservar. Bordas cinzentas deixam o limite borrado; procure criar bordas nítidas.
Tamanho exatamente igual ao da imagem original. Imagem original de 1600 × 900 exige máscara de 1600 × 900. Não tire captura de tela e redimensione; exporte a máscara diretamente do mesmo arquivo. Se largura e altura não coincidirem, a tarefa falha.
A área branca deve aderir ao alvo. Pare quando cobrir o que precisa ser alterado; não inclua móveis, bancadas ou sombras ao redor.
Exporte PNG na resolução da imagem original. PNG não tem ruído de compressão e deixa a borda mais limpa; coloque a máscara e a imagem original em endereços acessíveis publicamente, pois a API recebe URLs, não upload de arquivos.

Preto preserva, branco repinta. Esta máscara de 1600 × 900 deixa apenas um retângulo branco na posição do relógio, então somente aquela área da parede será repintada.

Teste online: 4 passos para a primeira imagem

A página do modelo não permite desenhar máscara; prepare a máscara na sua própria ferramenta e faça o upload.

Abra a página do modelo FLUX.1 Fill Pro, cadastre-se ou faça login; novas contas já vêm com 200 créditos.
Envie a imagem original e, em seguida, a máscara preto e branco do mesmo tamanho.
Cole o prompt, descrevendo apenas o que deve aparecer na área branca e deixando claro o que precisa ser preservado.
Clique em executar. O padrão é steps 50, guidance 60 e saída jpg; faça a primeira execução funcionar antes de ajustar parâmetros.

Ao clicar em "Gerar com este prompt" para abrir a página, o prompt é preenchido automaticamente. O campo da imagem original fica vazio e o campo da máscara vem com a máscara de exemplo; substitua pela sua máscara antes de executar.

Integração via API: 4 passos

Crie uma API Key no console (sk-...).
Use POST /v1/tasks para criar a tarefa, com image, mask e prompt dentro de input.
Consulte com GET /v1/tasks/{taskId} ou adicione callback.url na requisição e aguarde a notificação.
Quando data.status virar success, baixe a imagem de data.output[0].url e salve imediatamente no seu próprio armazenamento.

A tabela completa de campos, os códigos de erro e a descrição dos parâmetros estão na documentação em chinês.

Primeira repintura com máscara: versão 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"
    }
  }'

O ID da tarefa retornada fica em data.taskId:

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

Consultar o resultado:

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

As duas imagens acima são materiais de comparação um para um: a imagem original de 1600 × 900 e a máscara do mesmo tamanho; execute diretamente para obter o efeito do quadro pendurado da primeira imagem deste artigo.

Primeira repintura com máscara: versão Python

Criação, polling e download em um único código; basta trocar pela sua chave para executar:

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"))

Como ajustar os parâmetros?

Altere apenas um por vez; só assim você saberá qual item causou a diferença.

steps (15–50, padrão 50): quanto maior, mais detalhes; o valor padrão já é adequado para entrega, e reduzir só vale a pena quando precisar de velocidade.
guidance (1,5–100, padrão 60): quanto maior, mais próximo do prompt. Se o estilo desviar, aumente primeiro; se a imagem ficar rígida, reduza de volta.
seed: depois de definir o resultado, fixe um valor; com a mesma imagem, máscara e prompt você volta a um resultado semelhante, o que facilita reversão e padronização em lote.
output_format: padrão jpg; use png se quiser preservar o máximo de detalhes ou se ainda for processar a imagem depois.
prompt_upsampling: padrão false. Ativá-lo reescreve automaticamente seu prompt; se quiser controle total da redação, mantenha desativado.

4 pontos de atenção antes de ir para produção

A página não desenha máscara. Tanto a página do modelo quanto a API recebem apenas a imagem de máscara pronta, e o tamanho precisa ser igual ao da imagem original. Prepare a máscara no Photoshop, Figma ou ferramenta de segmentação antes de enviar; na página só é possível fazer upload, não pintar.
No servidor, use callback. Adicione ao corpo da requisição "callback": {"url": "https://yourapp.com/webhook", "when": "final"} para ser notificado automaticamente ao fim da tarefa, o que dá menos trabalho que polling; mantenha o polling como fallback.
Em caso de timeout, não repita o POST. Cada POST /v1/tasks cria uma nova tarefa e é cobrado separadamente. Guarde o taskId primeiro e, ao tentar novamente, reutilize a mesma tarefa para consultar.
O endereço de saída expira. Baixe e salve o arquivo imediatamente ao obter o resultado; não trate a URL como endereço permanente. Além disso, a proporção da saída segue a imagem original e não há parâmetro de proporção; se precisar de um formato fixo, recorte você mesmo na proporção desejada.

Perguntas frequentes

Dá para usar sem enviar máscara? Não. image, mask e prompt são todos obrigatórios, e a máscara deve ser uma imagem preto e branco do mesmo tamanho da imagem original.

Qual deve ser o tamanho do prompt? Até 4.000 caracteres, mas o suficiente é o melhor: uma frase sobre o que deve aparecer na área branca e uma frase sobre o que deve ser preservado. Quanto mais específica a descrição dos detalhes, mais estável o resultado.

O tamanho da saída é igual ao da imagem original? A proporção é a mesma, e os pixels são ajustados para múltiplos de 32. Uma imagem original de 1600 × 900 retorna 1440 × 810; para sobrepor à imagem original, unifique primeiro o tamanho.

Falhas na geração são cobradas? Não. O valor pré-cobrado de tarefas com falha é devolvido integralmente de forma automática.

Gere a primeira imagem agora

Os dois materiais de comparação acima (imagem original + máscara) servem para praticar diretamente: copie o corpo da requisição do curl e execute uma vez com a sua API Key, ou abra a página do modelo, envie essas duas imagens; o prompt já está preenchido e clicar em executar gera o mesmo resultado. Esta imagem custa US$ 0,0715, e os 200 créditos de boas-vindas do cadastro bastam para uma imagem.

Série de artigos do FLUX.1 Fill Pro

Etiquetasintegracao-api Tutorial Integração via API Tutorial