Tutorial
Como chamar flux-1-fill-pro via HiAPI API: curl, Python e polling assíncrono
Nesta página
O que flux-1-fill-pro faz e quando usá-lo
flux-1-fill-pro é um modelo de edição de imagem do tipo preenchimento. Você fornece uma imagem de origem e uma máscara que marca a região a ser regenerada, e ele devolve uma nova imagem com essa região substituída. As áreas fora da máscara devem permanecer inalteradas — é exatamente isso que o distingue de modelos de texto-para-imagem puros ou de estilização da imagem inteira.
Use-o quando a edição for local e o contexto ao redor importar:
- Remoção de objetos — delimite com a máscara o elemento indesejado e deixe o modelo reconstruir o que deveria estar por trás dele.
- Substituição de objetos — delimite a região com a máscara e descreva o novo conteúdo no prompt, mantendo o restante da cena intacto.
- Retoque local — corrija texturas, reflexos ou pequenas imperfeições sem regenerar a imagem inteira.
- Inserção em pipeline — retoque programaticamente imagens de produto, thumbnails ou assets gerados, nos quais apenas uma região precisa de um segundo tratamento.
Ele não é a ferramenta adequada quando você quer uma composição totalmente nova a partir do prompt, ou quando sua região mascarada é tão grande que o modelo está efetivamente gerando a imagem do zero — nesse caso, os endpoints de geração padrão se comportam de forma mais previsível.
O restante deste guia trata de como integrar flux-1-fill-pro ao seu código via HiAPI API: estrutura da requisição, chamada em curl, equivalente em Python e o tratamento de tarefas assíncronas que a maioria das primeiras integrações erra.
Preparação e configuração de autenticação
Antes de enviar a primeira requisição, confirme três coisas.
Chave de API
Crie uma chave na sua conta HiAPI e mantenha-a longe do controle de versão. Os exemplos abaixo a leem de variáveis de ambiente, então os trechos podem ser copiados com segurança:
export HIAPI_API_KEY="your_key_here"
Em Python, carregue-a da mesma forma via os.environ. Se você roda em CI, injete-a como secret em vez de commitar um arquivo .env.
Identificador do modelo
Cada requisição especifica o modelo pelo nome. Neste guia, o identificador é flux-1-fill-pro. Mantenha-o como constante no código, em vez de espalhar literais de string — assim, trocar de modelo depois exige mudar uma única linha.
URL base
Todas as chamadas vão para a URL base da HiAPI API documentada na referência da plataforma. Coloque-a na configuração junto com a chave, para que staging e produção possam diferir sem alterar código.
Um lembrete estrutural antes de começar: requisições de preenchimento carregam dados de imagem. Envie as imagens codificadas em base64 como JSON, em vez de tentar forçar um upload por formulário; e mantenha o timeout do cliente generoso — codificar imagens grandes adiciona latência antes mesmo de a requisição sair do seu processo. Consulte a documentação da plataforma para os limites atuais de tamanho de payload; se sua imagem de origem exceder o limite documentado, reduza-a antes de codificar, em vez de deixar a requisição falhar na borda.
A estrutura de uma requisição de inpainting
Independentemente da linguagem, toda chamada a flux-1-fill-pro tem a mesma composição lógica.
Imagem de origem
A imagem que você quer editar, codificada como string. Ela define a tela: suas dimensões determinam o espaço de coordenadas da máscara, e seu conteúdo fornece ao modelo o contexto que torna o preenchimento verossímil.
Máscara
A máscara marca quais regiões serão regeneradas. Esta é a fonte mais comum de confusão, então deixe explícita a convenção que seu payload usa: a região marcada pela máscara é a região que o modelo pode alterar. Construa a máscara como uma imagem separada, com distinção visual clara entre a área a preencher e a área a preservar. Inverter a máscara é o bug clássico — você obtém um resultado em que o modelo editou tudo, menos a região desejada.
A máscara deve ter exatamente as mesmas dimensões da imagem de origem. Máscaras desenhadas em resolução diferente são rejeitadas ou silenciosamente desalinhadas, e ambos os casos desperdiçam uma ida e volta.
Prompt
Descrição textual do que deve aparecer dentro da máscara. Seja específico e local: descreva o conteúdo e como ele se relaciona com o entorno em iluminação ou textura, não a cena inteira. "Um banco de madeira que continua o acabamento da fachada, com luz suave de fim de tarde vindo da esquerda" dá ao modelo muito mais base do que "um fundo mais bonito".
Controles opcionais
Dependendo do conjunto de parâmetros documentado, você também pode enviar itens como uma seed para reprodutibilidade ou parâmetros do tipo força que controlam o quanto o preenchimento pode se afastar dos pixels originais. Para parâmetros que não existem na documentação de referência atual, trate-os como não suportados em vez de adivinhar seus nomes.
Esses quatro — modelo, prompt, imagem de origem e máscara — trafegam no mesmo corpo JSON. As duas seções seguintes enviam exatamente esse corpo.
Uma requisição curl funcional
Comece com curl para ver o envelope bruto antes que qualquer biblioteca cliente o esconda.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Onde request.json se parece com isto:
{
"model": "flux-1-fill-pro",
"prompt": "um banco de madeira que continua o acabamento da fachada, com luz suave de fim de tarde vindo da esquerda",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
Dois truques práticos para montar esse arquivo. Primeiro, gere os payloads base64 por comando, em vez de colar manualmente:
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
Depois, use um pequeno passo com jq ou Python para inseri-los e montar o request.json. Editar manualmente blocos base64 de vários megabytes dentro de um JSON é a causa raiz de payloads truncados e erros 400 confusos.
Interpretando a resposta
O envelope de resposta diz qual é o próximo passo. Tarefas concluídas retornam a imagem editada — geralmente como URL ou campo base64, conforme o formato definido pela documentação de referência atual. Tarefas enfileiradas retornam um identificador e um status, que você então consulta por polling (veja abaixo). Não assuma que a primeira resposta sempre contém pixels; escreva o parser para lidar com as duas formas desde o primeiro dia, ou você terá que reescrevê-lo na primeira vez que uma tarefa for enfileirada sob carga.
Verifique o código de status HTTP antes de fazer o parse do corpo da resposta. 4xx significa que a requisição em si está errada e repetir não adianta; corrija o payload.
A mesma chamada em Python
A versão em Python é a mesma requisição, mas mais confortável de usar. Não é necessário SDK — requests contra o endpoint HiAPI é suficiente.
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()
O timeout é intencional. Codificar e enviar imagens grandes leva mais tempo do que uma chamada JSON típica, e requisições sem limite são a causa de scripts travarem silenciosamente em tarefas de processamento em lote. Lançar uma exceção em 4xx com o corpo da resposta transforma falhas misteriosas em falhas legíveis.
Mantenha o identificador do modelo e o endpoint na configuração em nível de módulo, para que a atualização de versão exija mudar um só lugar. Se você processa muitas imagens, reutilize uma requests.Session para que as conexões sejam reaproveitadas, em vez de reabrir a cada chamada.
O dicionário retornado é ou um resultado concluído, ou um handle de tarefa — a próxima seção trata do segundo caso.
Tratando tarefas assíncronas e polling
Requisições de preenchimento podem ser lentas, então a API pode retornar um handle de tarefa em vez da imagem pronta. O padrão correto é um laço de polling com limite, e não um sleep fixo seguido de reza.
O laço
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) # backoff suave
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job segue o mesmo padrão de requisição acima, usando o id da tarefa e seus cabeçalhos de autenticação para acessar o endpoint documentado de status de tarefa.
Por que backoff em vez de intervalo fixo
Fazer polling em loop apertado contra a fila martela a API sem nenhum ganho. Começar com um intervalo curto e multiplicá-lo até um teto mantém a resposta rápida para conclusões antecipadas, sem desperdiçar milhares de consultas em tarefas lentas. Coloque um limite superior no intervalo para que você ainda perceba a conclusão em poucos segundos.
Por que timeout e falha são coisas diferentes
Timeout significa que você parou de esperar, não que a tarefa falhou. Ao lançar a exceção, preserve o id da tarefa, para que o chamador possa retomar o polling depois sem reenviar e pagar duas vezes pelo mesmo trabalho. Trate timeout, falha de tarefa e erro HTTP como três exceções distintas no seu pipeline — condensá-los em um erro genérico torna a investigação de incidentes de produção muito mais difícil.
Depurando falhas comuns
A maioria das respostas de erro cai em algumas categorias. Verifique-as em ordem.
401 / 403 — autenticação
Verifique primeiro: o cabeçalho é exatamente Authorization: Bearer <key>, sem aspas e sem espaços extras vindos de uma variável de shell que nunca foi exportada? Um $HIAPI_API_KEY vazio produz um token Bearer contendo apenas a palavra Bearer, que falha da mesma forma que uma chave errada.
400 — payload malformado
Verifique primeiro: depois de concatenar as strings base64, o corpo ainda é JSON válido? Exporte request.json e rode python -m json.tool nele. Prefixos data:image/png;base64, nos campos de imagem são uma causa comum — remova-os, a menos que a documentação de referência exija explicitamente o contrário.
Incompatibilidade entre máscara e imagem
Verifique primeiro: as dimensões em pixels da máscara e da imagem de origem são exatamente iguais? Depois valide a polaridade — confirme que a região branca é a que você quer que o modelo regenere. Um resultado que parece o oposto do que você pediu quase sempre é máscara invertida, não problema de prompt.
Transbordamento de prompt
Se áreas não mascaradas mudaram, ou o preenchimento parece global, sua máscara pode estar grande demais ou o prompt cobre demais a cena. Estreite os dois: restrinja a máscara à área real de edição e descreva apenas o conteúdo dentro da máscara.
Timeout de tarefa
Verifique primeiro: o tamanho do payload. Imagens de origem grandes demais são a causa mais comum de tarefas que nunca terminam. Reduza, tente mais uma vez e, se ainda der timeout, teste com uma imagem pequena contra os limites de referência antes de presumir problema no serviço.
Campo de resultado vazio ou ausente
Verifique primeiro: você tratou o formato da resposta enfileirada? Um parser que só lê o formato concluído não verá nada na primeira chamada. Registre o envelope completo da resposta durante o desenvolvimento, para enxergar o formato antes de escrever código defensivo.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio