Documentação da API

Início rápido

O primeiro pedido precisa apenas de input.image_base64. Omita input.output para manter a saída transparente no tamanho original utilizada pelos clientes atuais.

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

Autenticação com uma chave Bearer

Crie uma chave de API na área Pessoal e envie-a no cabeçalho Authorization de cada pedido.

Authorization: Bearer rz_live_your_api_key

• Guarde as chaves numa variável de ambiente do servidor ou num gestor de segredos.
• Nunca coloque uma chave em código do navegador, aplicações móveis, extensões, URLs, repositórios públicos ou registos.
• Sempre que possível, use chaves diferentes para serviços ou ambientes distintos.
• Revogue e substitua imediatamente uma chave que possa ter sido exposta.

Chame a API a partir do seu servidor

Use o percurso navegador ou cliente → o seu servidor → API do RemoveZero. A chave Bearer pode autorizar processamento pago, por isso um cliente público não consegue mantê-la secreta. Os pedidos pagos do servidor devem omitir o cabeçalho Origin.

Envie um pedido de remoção de fundo

Envie um pedido JSON estrito a partir do seu servidor. Os cabeçalhos obrigatórios são validados antes da reserva de Créditos ou do processamento da imagem.

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Type deve ser application/json; é permitido um parâmetro charset.
• Content-Encoding deve ser omitido ou identity; corpos de pedido comprimidos são rejeitados.
• Não envie o cabeçalho Origin.
• Idempotency-Key deve ter entre 1 e 128 caracteres e usar letras, números, pontos, sublinhados, dois-pontos ou hífenes.
• image_base64 deve conter os bytes da imagem em Base64 padrão, sem o prefixo data:image/....

Personalize a saída

O objeto input.output é opcional. Altera a tela após a mesma e única inferência de remoção de fundo, pelo que a personalização não utiliza outro Crédito.

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

Comportamento fixo de contenção e centragem

O ajuste não é um campo do pedido. O RemoveZero preserva sempre a proporção do objeto e encaixa-o no espaço disponível da tela.

• O objeto completo permanece visível e centrado.
• O objeto não é cortado nem distorcido.
• O espaço restante da tela usa transparência ou a cor solicitada.
• Não são suportados preenchimento por cobertura, recorte inteligente, posições de gravidade ou coordenadas arbitrárias.

Compatibilidade com versões anteriores

Os clientes atuais podem omitir input.output e continuar a enviar apenas input.image_base64. Adicione output apenas quando precisar de um formato, fundo, tela ou margem personalizados.

Resposta bem-sucedida

Uma imagem concluída devolve HTTP 200 e utiliza 1 Crédito. A saída inclui o tipo de conteúdo e as dimensões exatas da tela, além dos dados Base64 que o seu servidor pode descodificar.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

Descodifique o resultado

1. Confirme HTTP 200, ok: true e status: COMPLETED.
2. Leia output.content_type e aceite apenas image/png ou image/webp.
3. Descodifique output.output_base64 uma vez e guarde os bytes com a extensão correspondente.
4. Quando forem solicitadas dimensões, confirme output.width e output.height.

O resultado é devolvido diretamente, não como URL permanente. Guarde os bytes descodificados na sua aplicação se precisar de conservar ou entregar a imagem.

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

Faturação e devolução de Créditos

Cada pedido processa uma imagem. O RemoveZero valida o pedido, reserva atomicamente 1 Crédito e só o liquida depois de a remoção de fundo e a saída solicitada serem concluídas. A personalização da saída nunca acrescenta outra inferência nem outro Crédito.

Ciclo de vida do Crédito

Se ainda não for possível confirmar o pedido ou a devolução, a API responde com REFUND_PENDING, o ID do pedido e Retry-After: 30. Mantenha a mesma Idempotency-Key e não envie a mesma imagem com uma chave nova.

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

Idempotência e novas tentativas

Idempotency-Key associa-se ao corpo JSON serializado exato, incluindo a imagem e todos os campos de saída fornecidos. Preserve os bytes originais do pedido, bem como a chave.

• Mesma chave e corpo exatamente igual: nova tentativa segura, sem segunda reserva nem segundo pedido de processamento.
• Mesma chave e corpo alterado: 409 IDEMPOTENCY_CONFLICT.
• Mesma chave depois de um pedido terminal: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; os resultados Base64 concluídos não são guardados para repetição.
• Chave nova: novo pedido que pode reservar outro Crédito.
• Um corpo JSON semanticamente igual pode ainda ser diferente se os espaços, a ordem das propriedades ou os valores predefinidos explícitos mudarem.

Orientações de Retry-After

429 RATE_LIMITED

Aguarde 60 segundos e repita o corpo exato com a mesma chave.

503 REFUND_PENDING

Aguarde 30 segundos e repita o corpo exato com a mesma chave.

503 UPSTREAM_BUSY

Aguarde 10 segundos. Use uma chave nova apenas para uma tentativa nova e intencional.

Tempo limite de rede ou API_UNAVAILABLE

Considere o resultado desconhecido e mantenha o corpo e a chave originais até à resolução.

Exemplos

Substitua os marcadores no seu servidor. A chave de API nunca deve ser exposta num pacote público do navegador.

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

Pontos de partida comuns para a saída

Estas configurações são pontos de partida, não garantias permanentes de conformidade com plataformas ou categorias. Os nomes das plataformas são etiquetas, não valores enum da API.

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

Erros e resolução de problemas

Os erros usam um estado HTTP estável e um código curto na resposta JSON.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

Resolução segura de problemas

1. Registe o estado HTTP, o código de erro, request_id quando existir, a data e hora e a Idempotency-Key.
2. Nunca registe nem envie a chave Bearer, o image_base64 completo ou uma resposta completa com dados de imagem.
3. Corrija os erros 4xx de pedido, credenciais, saldo ou cabeçalhos antes de tentar novamente.
4. Respeite Retry-After e preserve o corpo e a chave originais para pedidos por resolver.
5. Contacte o suporte com identificadores não secretos se um estado por resolver persistir.

Limites do pedido

Envie uma imagem JPG, PNG ou WebP por pedido em Base64 padrão. A entrada descodificada pode ter no máximo 5 MiB e o corpo JSON completo no máximo 7 500 000 bytes. A saída personalizada está limitada a 4 096 px por lado e 4 194 304 píxeis. Se o resultado exato não couber no limite da resposta direta, o processamento falha e o Crédito reservado é devolvido; a API nunca altera silenciosamente o tamanho ou o formato pedido.