Blogue

Tutorial

Como chamar flux-1-fill-pro via HiAPI API: curl, Python e polling assíncrono

Nov 12, 2026
Imagem de capa do blog HiAPI: sobre um fundo azul-índigo profundo, três setas largas aninhadas avançam progressivamente na horizontal, com a borda frontal em laranja-damasco, em estilo de diagrama plano de fluxo de sinais.
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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API