Como usar a API Bria Eraser: curl, Python e uma requisição que funciona

bria-eraser remove objetos de fotos. Você envia uma imagem e uma máscara em preto e branco, e ele preenche a área da máscara com o fundo correspondente. Não há campo prompt. Este guia mostra uma requisição completa e funcional, o código Python que a executa e os detalhes que determinam se a sua própria máscara vai funcionar. Você precisa obter uma chave HiAPI no painel.

Requisição mínima (curl)

O modelo usa o endpoint assíncrono unificado POST /v1/tasks. Ambas as URLs abaixo são públicas e estavam acessíveis na data de redação deste texto:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-eraser",
    "input": {
      "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
      "mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
      "mask_type": "manual"
    }
  }'

A chamada retorna imediatamente um id de tarefa, e não a imagem:

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

Faça polling em GET /v1/tasks/<taskId> até que data.status seja success e então leia data.output[0].url.

Python: enviar, fazer polling, baixar

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def erase(image_url: str, mask_url: str, out_path: str) -> str:
    r = requests.post(API, headers=HEADERS, timeout=30, json={
        "model": "bria-eraser",
        "input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: poll the SAME task id again
        if d["status"] == "success":
            img = requests.get(d["output"][0]["url"], timeout=60)
            img.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(img.content)
            return task_id
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(task_id)

Mantenha o id da tarefa. Se uma consulta de polling falhar, faça polling desse mesmo id novamente. Não reenvie, pois cada envio é uma tarefa cobrada separadamente.

Campos da requisição

Campo	Obrigatório	Descrição
input.image_url	Sim	URL http/https pública. JPEG, PNG ou WEBP.
input.mask_url	Sim	Imagem em preto e branco com a mesma proporção da imagem de origem. O branco é apagado, o preto é preservado.
input.mask_type	Não	manual (padrão) para máscaras desenhadas com pincel, automatic para máscaras geradas por ferramentas de segmentação.
input.preserve_alpha	Não	Padrão false. Defina como true para preservar a transparência de entradas com canal alpha.

Produção: usar callbacks

O polling é adequado para testes. Para serviços, passe um callback de nível superior para que a HiAPI notifique você quando a tarefa for concluída:

{
  "model": "bria-eraser",
  "input": { "image_url": "...", "mask_url": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

Mantenha o polling como fallback, caso o callback se perca. As URLs de saída expiram, então copie o arquivo para o seu próprio armazenamento o quanto antes após a tarefa ser concluída com sucesso.

O que eu realmente executei e vi

Executei a requisição da seção curl no dia em que escrevi este texto e fiz polling até a conclusão.

• Sequência de status: handling → archiving → success. archiving aparece depois que o trabalho termina e antes de output aparecer. Trate-o como “ainda não concluído” e continue o polling.
• Tempo: a tarefa levou 16 segundos da criação à conclusão. A URL de output apareceu alguns segundos depois disso.
• Saída: um PNG em temp.hiapi.ai, 1360 × 768, com canal alpha. É o mesmo tamanho da imagem de origem, consistente com a documentação sobre preservar a resolução original.
• Cobrança: quando consultei, os dados públicos de preços indicavam $0.0575 por imagem para este modelo. Consulte os preços atuais na página de preços.
• Erro de validação: testei de propósito enviando mask_type: "bogus". A API rejeitou com HTTP 400:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}

Verifiquei apenas uma requisição em uma única imagem. Não testei outros estilos de máscara, imagens muito grandes ou máscaras com proporção diferente da imagem. As observações abaixo sobre esses casos vêm da documentação do modelo, não dos meus testes.

Dicas de máscara (da documentação)

• Pinte um pouco além da borda do objeto. Máscaras justas ao contorno costumam deixar um halo ao redor do objeto original.
• Mantenha a máscara com a mesma proporção da foto. A documentação exige isso, mas não diz o que acontece caso contrário.
• Use automatic somente para máscaras vindas de ferramentas de segmentação ou recorte. Para máscaras de pincel, use manual.

Qual página devo ler?

Este guia aborda a remoção baseada em máscara usando o endpoint dedicado. Para edição orientada por prompt com um modelo genérico de imagem para imagem, consulte inpainting e remoção de objetos. Se quiser remover o fundo inteiro em vez de um único objeto, consulte o guia de remoção de fundo. A página do modelo está em bria-eraser, e a referência de campos está na documentação da API.

Perguntas frequentes

O bria-eraser precisa de prompt?

Não. A documentação informa que o prompt não é necessário, e a requisição que executei continha apenas a imagem, a máscara e o mask_type.

Qual cor da máscara é removida?

O branco é apagado e o preto é preservado.

A saída é menor que a entrada?

Na minha execução, a saída foi 1360 × 768, exatamente igual à imagem de origem.

Devo usar polling ou callbacks?

Polling durante testes. Em produção, use callback.url com when: "final" e mantenha o polling como fallback.