API Recraft de remoção de fundo: um exemplo executável

A maioria das APIs de remoção de fundo exige que você escolha um modelo genérico de edição de imagem e depois o guie com o prompt certo para recortar o sujeito. O recraft/remove-background dispensa essa etapa: é um modelo dedicado que recebe uma URL de imagem e devolve um PNG transparente que preserva detalhes de borda no nível de fios de cabelo e pelos. Sem prompt, sem negative prompt, sem parâmetro de intensidade — basta a imagem de origem e você tem o recorte.

Este guia percorre uma chamada completa e testada: a estrutura da requisição, a resposta que você realmente recebe e os padrões de produção que impedem que um trabalho em lote trave por causa de um caso limite (callbacks, idempotência, tratamento de erros).

Pré-requisitos:

• Obtenha uma chave de API do hiapi no seu console
• Python 3.9+ com requests instalado (pip install requests), ou use curl diretamente
• Sua imagem de origem deve estar em uma URL pública — a API de tarefas do hiapi busca imagens por URL, não por upload de arquivo. Formatos PNG, JPG ou WEBP, no máximo 5MB, no máximo 16 milhões de pixels, com ambas as dimensões entre 256 e 4096 pixels.

Requisição

Como todos os modelos de geração no hiapi, o recraft/remove-background roda pela API de tarefas assíncronas compartilhada: POST /v1/tasks com model e input, e você recebe imediatamente um taskId, com o recorte processado em segundo plano. O contrato completo — cabeçalhos, chaves de idempotência, códigos de status — está documentado de forma unificada em Criar tarefa; a parte específica do modelo é o input, que para este modelo tem apenas um campo:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url é o único campo aceito por este modelo — não há format, response_format nem parâmetros de tamanho. Enviar qualquer outra coisa faz a API rejeitar a requisição inteira com um erro de schema antes mesmo de chegar ao modelo (veja Erros abaixo). A saída é sempre um PNG transparente.

Consulta do resultado

Pegue o taskId da resposta acima e consulte GET /v1/tasks/{taskId} até data.status atingir um estado terminal. A enumeração de status é consistente entre todos os modelos da plataforma: queued → handling → archiving → success (ou fail). A execução real deste modelo costuma concluir em menos de 10 segundos:

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

Quando o status é success, data.output é um array com um único elemento:

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

A url é um link temporário — expireAt é um timestamp Unix de cerca de uma semana depois, não um endereço permanente de CDN. Baixe os bytes e armazene no seu próprio storage assim que a tarefa concluir com sucesso:

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

Padrões para produção

Use callbacks em vez de polling em loop. Passe callback.url na criação e o hiapi enviará o resultado final por POST para você quando a tarefa terminar, em vez de você gastar requisições em um loop de polling:

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" significa que você recebe o callback apenas uma vez, disparado no estado terminal (success ou fail), e não uma vez por estado intermediário. Para um lote de fotos de produtos, essa é a configuração padrão adequada — você não precisa manter um loop de polling para cada imagem.

Idempotência. Se a requisição expirar do seu lado mas já tiver chegado ao hiapi, repetir com o mesmo cabeçalho Idempotency-Key (documentado em Criar tarefa) devolve a tarefa original, sem cobrar por um segundo recorte. Vale a pena definir isso em qualquer trabalho em lote que repita requisições em caso de erro de rede.

Erros — duas formas, não uma. Requisições malformadas e falhas de autenticação retornam envelopes diferentes, e um código que verifica apenas um deles engole o outro silenciosamente:

// Erro de entrada (validação de schema) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// Chave de API inválida ou expirada — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Verifique error_code primeiro e recorra a error.code depois — não presuma que todas as falhas têm as mesmas chaves de nível superior.

Preço. $0.01 por imagem (20 credits), com preço uniforme independentemente da resolução de entrada. O preço atual está sempre na página de preços.

Quando você precisa substituir o fundo, não apenas recortar

O recraft/remove-background gera apenas o recorte transparente — sem preenchimento, sem cenário. Se o objetivo é trocar por um fundo de estúdio ou uma cena de lifestyle na mesma chamada, essa é outra tarefa: use um modelo de imagem para imagem e instrua-o a regenerar o fundo ao redor do sujeito preservado. Veja Remover o fundo de imagens com API: edição baseada em prompt para conhecer essa abordagem e quando vale a pena pagar mais do que um recorte comum.

Perguntas frequentes

O recraft/remove-background aceita prompts ou parâmetros de intensidade? Não. O schema é estrito — image_url é o único campo aceito. Enviar campos extras como format ou response_format retorna 400 com a mensagem "additional properties not allowed".

Quais formatos e tamanhos de imagem são suportados? Entrada: PNG, JPG ou WEBP, no máximo 5MB, no máximo 16 milhões de pixels, com ambas as dimensões entre 256 e 4096 pixels. A saída é sempre um PNG com canal alfa.

Posso enviar um arquivo local em vez de uma URL? Não — image_url deve ser uma URL pública http(s):// que os servidores do hiapi possam buscar. Faça o upload para um object storage ou CDN primeiro.

Quanto tempo dura a URL de saída? O campo expireAt em cada item de saída é um timestamp Unix, geralmente cerca de uma semana depois. Trate-a como um link temporário e copie os bytes para o seu próprio storage assim que a tarefa concluir com sucesso — não guarde links temp.hiapi.ai a longo prazo.

Isso funciona para processar em lote centenas de fotos de produtos? Sim — envie uma tarefa por imagem, compartilhe um callback.url e deixe o hiapi enviar os resultados de volta, em vez de consultar uma por uma. A $0.01/imagem, processar um catálogo de 1.000 imagens custa $10 em geração.