Documentação da API de remoção de fundo

Envie uma imagem e receba um PNG transparente com uma única chave API.

POSThttps://api.remox.ai/v1.0/removebg

Início rápido

Guarde a chave emitida no servidor. Nunca a exponha no navegador ou aplicativo. A troca preserva a identidade e o saldo do cliente.

REMOX_API_KEY

Use JPG, PNG ou WebP estático. Redimensione antes do envio; a API não redimensiona imagens.

Exemplos de código →

Autenticação

Guarde a chave emitida no servidor. Nunca a exponha no navegador ou aplicativo. A troca preserva a identidade e o saldo do cliente.

Campo	Valor aceito
X-API-Key	remox_live_… / remox_test_…
Secret / X-Subuid / X-Platform-User / X-RapidAPI-User	—
image_url / Base64 / shadow / refine	—

Exemplos de código

cURL

# Set REMOX_API_KEY in your environment first.
curl 'https://api.remox.ai/v1.0/removebg' \
  -H "X-API-Key: $REMOX_API_KEY" \
  -H 'Idempotency-Key: image-0001' \
  -F 'image_file=@/path/to/input.jpg' \
  -F 'size=auto' \
  --max-time 75 --fail-with-body \
  -D response-headers.txt -o remox-result.png
# On non-2xx, the output file contains error JSON, not a PNG.

Use JPG, PNG ou WebP estático. Redimensione antes do envio; a API não redimensiona imagens.

input.jpg → image/jpeg · PNG → image/png · WebP → image/webp

Referência da requisição

POST /v1.0/removebg · multipart/form-data

Use JPG, PNG ou WebP estático. Redimensione antes do envio; a API não redimensiona imagens.

Campo	Obrigatório	Valor aceito
image_file	✓	JPG / PNG / WebP · ≤20 MiB (20 × 1024 × 1024 bytes) · max(width, height) ≤1920 px · min(width, height) ≤1080 px
size	—	auto
response_format	—	image / json
Idempotency-Key	—	8–128 · A–Z a–z 0–9 . _ : -

Respostas

200 · PNG

response_format=image · Content-Type: image/png

X-Request-ID · X-Task-ID · X-Idempotency-Key

200 · JSON

response_format=json

{
  "requestId": "req_…",
  "taskId": "task_…",
  "data": {
    "result_url": "https://storage.example/result.png?signature=…&expires=…"
  }
}

data.result_url ≠ result_b64

Tempo limite e novas tentativas

Após 60 segundos, um 504 pode indicar uma tarefa em andamento. Consulte o estado ou repita com a mesma imagem e Idempotency-Key para evitar cobrança duplicada.

GET /v1.0/tasks/{taskId}

{
  "requestId": "req_…",
  "taskId": "task_…",
  "status": "completed",
  "progress": null,
  "pollAfterMs": 2000,
  "result": {
    "downloadPath": "/v1.0/tasks/task_…/result",
    "mimeType": "image/png",
    "expiresAt": "2026-10-17T00:00:00.000Z"
  }
}

GET /v1.0/tasks/{taskId}/result
GET /v1.0/tasks/{taskId}/result?response_format=json

creating → queued → processing → completed / failed / timed_out

Retry-After · pollAfterMs: 2000 · X-API-Key

Conta e créditos

Os créditos são reservados na criação, consumidos no sucesso e liberados na falha ou expiração da tarefa. O tempo limite síncrono não os libera.

Campo	Valor aceito
credits	available / reserved / consumed
GET /v1.0/account	X-API-Key
POST → AI	300 ms
POST → 504	60 s
task → timed_out	35 min
task_expired	90 d
result_expired (Worker)	7 d

Erros

Verifique errors e o estado antes de repetir. Guarde requestId para suporte; nunca registre sua chave.

{
  "requestId": "req_…",
  "retryable": false,
  "errors": [
    {
      "code": "invalid_credentials",
      "title": "Invalid API key."
    }
  ]
}

HTTP	errors[].code	Erros
400	invalid_request, invalid_file	Requisição inválida
400	invalid_size, invalid_response_format	Requisição inválida
400	invalid_idempotency_key, invalid_subject	Requisição inválida
402	insufficient_credits	Créditos insuficientes
403	invalid_credentials	Acesso negado
403	platform_disabled, platform_paused, scope_denied	Acesso negado
404	not_found, upload_not_found	Não encontrado
409	idempotency_conflict	Conflito ou tarefa incompleta
409	result_not_ready	Conflito ou tarefa incompleta
410	task_expired, result_expired	Expirado
413	file_too_large	Arquivo muito grande
415	invalid_image, animated_image_unsupported	Imagem não suportada
422	image_dimensions_exceeded	Dimensões excedidas
429	rate_limit_exceeded, hourly_quota_exhausted, inflight_limit_exceeded	Limite de requisições
502	upload_failed, upstream_rejected, upstream_unavailable	Falha no serviço externo
502	create_result_unknown, remote_service_error, invalid_result, result_unavailable, task_failed, task_timeout	Falha no serviço externo
503	service_not_configured, credit_price_not_configured, server_error	Serviço indisponível
504	sync_timeout	Tempo limite síncrono

retryable: 429 / 5xx

Após 60 segundos, um 504 pode indicar uma tarefa em andamento. Consulte o estado ou repita com a mesma imagem e Idempotency-Key para evitar cobrança duplicada.

Compatibilidade

Apenas remoção de fundo com chave simples. Não implementa todas as opções do remove.bg. URLs de resultado JSON são uma extensão REMOX.

Solicitar acesso API →