Como usar 851-labs/background-remover via API hiapi: curl, Python e requisições executáveis

851-labs/background-remover transforma fotos de produtos, retratos ou animais de estimação em PNG transparente com apenas uma chamada de API — sem prompt, sem máscara, sem configuração de proporção. Este artigo apresenta a estrutura exata da requisição, um comando curl executável, um script Python pronto para colocar no backend e um erro de schema que é o mais fácil de todos de se tropeçar.

Preparação

• Uma conta hiapi e uma API key obtida no console.
• Uma imagem hospedada em uma URL HTTPS pública. A API de tarefas recebe uma URL, não um upload de arquivo — se sua imagem de origem existe apenas localmente, primeiro coloque-a em qualquer CDN ou armazenamento de objetos.

Todas as requisições vão para o endpoint unificado de tarefas:

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Estrutura da requisição (e a única regra que você deve memorizar)

O id do modelo é 851-labs/background-remover, passado diretamente como está. Seu schema de input tem apenas um campo:

Campo	Tipo	Obrigatório	Descrição
image_url	string	Sim	Deve corresponder a ^https?://[^\s]+$ — uma URL http(s) acessível diretamente.

Esse é o schema inteiro. Antes de escrever qualquer código, vale saber duas coisas:

1. Não há campo prompt, mask, background-color ou aspect-ratio. Este endpoint faz apenas uma coisa — separação de primeiro plano/fundo — e nada mais. Se você precisar recolorir ou redimensionar depois, será necessário chamar outro modelo.
2. Campos extras são rejeitados, não ignorados. Se você trouxer um campo format ou size do payload de outro modelo, a tarefa retornará 400 INVALID_REQUEST: <root>: additional properties 'format' not allowed antes mesmo de começar.

Exemplo mínimo executável: curl

Criar a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "851-labs/background-remover",
    "input": {
      "image_url": "https://your-cdn.example.com/product-shot.jpg"
    }
  }'

Após o envio bem-sucedido, retorna um id de tarefa, localizado em data:

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

Consultar o resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer sk-<your-key>"

Durante a execução, data.status passa por queued → handling → archiving. Ao concluir, muda para "success" e o PNG transparente aparece em data.output:

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

A URL de saída é válida por curto prazo (observe expireAt). Baixe os bytes do arquivo imediatamente após o sucesso da tarefa — não faça hotlink nem armazene a URL original de forma persistente.

Python pronto para produção: enviar, consultar, baixar

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def remove_background(image_url: str) -> bytes:
    # 1. Criar tarefa
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "851-labs/background-remover",
        "input": {"image_url": image_url},
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Consultar até atingir o estado terminal
    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Baixar imediatamente — a URL expira
            png = requests.get(outputs[0]["url"], timeout=120)
            png.raise_for_status()
            return png.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(3)
    raise TimeoutError(f"task {task_id} still running after 300s")


if __name__ == "__main__":
    png = remove_background("https://your-cdn.example.com/product-shot.jpg")
    with open("cutout.png", "wb") as f:
        f.write(png)
    print(f"saved cutout.png ({len(png)} bytes)")

A remoção de fundo é uma tarefa de imagem leve e geralmente é concluída bem antes do prazo de 300 segundos — esse timeout é apenas uma rede de segurança, não o tempo de execução esperado.

Usar callback em vez de polling

Para um backend web, recomenda-se registrar um callback ao criar a tarefa, em vez de fazer polling no manipulador de requisições. O objeto callback fica no nível superior, no mesmo nível de model:

{
  "model": "851-labs/background-remover",
  "input": { "image_url": "https://your-cdn.example.com/product-shot.jpg" },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

callback.when só aceita "final" — você receberá exatamente um POST quando a tarefa entrar em success ou fail, e não receberá eventos de progresso. O manipulador deve usar taskId como chave para evitar processar webhooks duplicados repetidamente, e verificar periodicamente com GET /v1/tasks/<id> os ids que seu endpoint nunca confirmou.

Tratamento de erros: os erros que realmente importam

400 INVALID_REQUEST na criação — a mensagem de erro indica o campo exato:

Mensagem	Causa
invalid input: image_url: missing required field "image_url"	input vazio ou nome de chave com erro de digitação
image_url: 'not-a-url' does not match pattern '^https?://[^\s]+$'	O valor não é uma URL http(s) bem formatada
<root>: additional properties 'format' not allowed	Você enviou um campo que o modelo não aceita

Esses erros são permanentes — repetir o mesmo payload falhará para sempre. Corrija o campo e reenvie.

401 permission_denied na criação — o problema está na própria key, não no corpo da requisição:

{"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}

Verifique as permissões de modelo dessa key no console.

A tarefa retorna status: "fail" — a criação foi bem-sucedida, mas a execução em si falhou (normalmente o backend não consegue obter a image_url). Leia data.error.code / message; esse tipo de falha pode ser repetido com segurança uma vez com backoff.

Consultar um id de tarefa desconhecido ou expirado retorna 404 com {"code": 404, "data": null, "message": "task not found"} — em qualquer varredura de reconciliação, isso deve ser tratado como estado terminal, e não como "ainda aguardando".

Próximos passos

• Página do modelo 851-labs/background-remover — exemplos ao vivo e preço atual.
• Remover o fundo de imagens com edição baseada em prompt — alternativa baseada no Seedream, para cenários em que você não apenas remove o fundo, mas também o altera.
• Documentação da API de tarefas assíncronas da hiapi — referência completa de criação/consulta/callback.
• Documentação de autenticação da hiapi — configuração da API key e formato do cabeçalho.
• Preços — tarifa atual por imagem.

Perguntas frequentes

Preciso de um prompt? Não. Basta fornecer uma image_url, e o modelo separa o primeiro plano do fundo por conta própria.

A saída é realmente transparente? Sim — o resultado é um PNG com canal alfa, pronto para ser composto sobre qualquer fundo.

Posso alterar a proporção, a cor ou o fundo na mesma chamada? Não. Esse endpoint apenas remove o fundo. Se precisar recolorir, redimensionar ou substituir o fundo, use esse PNG transparente como entrada e encadeie outro modelo de edição de imagem.

Por que recebo "additional properties '...' not allowed"? O schema aceita apenas um campo, image_url. Qualquer campo trazido do payload de outro modelo — format, size, background_color, qualquer campo — é rejeitado diretamente, e não ignorado silenciosamente.

Como devo salvar o resultado? Baixe imediatamente após a tarefa atingir status: "success". A URL de saída é uma URL assinada e tem expireAt; ela não é adequada para hotlink de longo prazo.

Quanto custa? A cobrança é feita por uso, por imagem. Consulte a tarifa atual na página de preços.