Documentación de API

Inicio rápido

La primera solicitud solo necesita input.image_base64. Omite input.output para conservar la salida transparente al tamaño original compatible con clientes existentes.

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 con una clave Bearer

Crea una API Key desde Personal y envíala en la cabecera Authorization de cada solicitud.

Authorization: Bearer rz_live_your_api_key

• Guarda las claves en variables de entorno o en un gestor de secretos del servidor.
• No pongas una clave en el navegador, apps móviles, extensiones, URLs, repositorios públicos o logs.
• Usa claves separadas para servicios o entornos distintos cuando sea posible.
• Revoca y sustituye una clave inmediatamente si pudo quedar expuesta.

Llama a la API desde tu servidor

Usa la ruta navegador o cliente → tu servidor → API de RemoveZero. La clave Bearer autoriza trabajo de pago y un cliente público no puede mantenerla secreta. Las solicitudes de servidor deben omitir Origin.

Envía una solicitud para quitar el fondo

Envía una solicitud JSON estricta desde tu servidor. Las cabeceras se validan antes de reservar Credits o procesar la imagen.

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 debe ser application/json y puede incluir charset.
• Content-Encoding debe omitirse o ser identity; no se aceptan cuerpos comprimidos.
• No envíes Origin.
• Idempotency-Key admite 1–128 caracteres: letras, números, puntos, guiones bajos, dos puntos y guiones.
• image_base64 debe contener Base64 estándar sin prefijo data:image/....

Personaliza la salida

El objeto output es opcional. Ajusta el lienzo después de una sola inferencia, por lo que la solicitud sigue usando solo 1 Credit.

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

Comportamiento fijo contain + center

fit no es un campo de la solicitud. RemoveZero conserva la proporción y encaja todo el sujeto en el lienzo disponible.

• El sujeto completo permanece visible y centrado.
• No se recorta ni se estira.
• El espacio restante usa transparencia o el color solicitado.
• No se admiten cover, recorte inteligente, gravedad ni coordenadas libres.

Compatibilidad anterior

Los clientes existentes pueden omitir input.output y seguir enviando solo input.image_base64. Añade output únicamente para personalizar formato, fondo, lienzo o margen.

Respuesta correcta

Una imagen correcta devuelve HTTP 200 y usa 1 Credit. La salida incluye el tipo de contenido, las dimensiones exactas y los datos Base64.

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
  }
}

Decodifica el resultado

1. Confirma HTTP 200, ok: true y status: COMPLETED.
2. Lee output.content_type y acepta solo image/png o image/webp.
3. Decodifica output.output_base64 una vez y guarda los bytes con la extensión correcta.
4. Si pediste dimensiones, comprueba output.width y output.height.

El resultado se devuelve dentro de la respuesta, no como URL permanente. Tu aplicación debe guardar los bytes si necesita conservarlos.

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"));

Facturación y devolución de Credits

Cada solicitud procesa una imagen. RemoveZero valida, reserva 1 Credit de forma atómica y lo liquida solo cuando el recorte y la salida solicitada terminan correctamente. Personalizar la salida no añade otra inferencia ni otro Credit.

Ciclo del Credit

Si todavía no se puede confirmar la solicitud o la devolución, la API devuelve REFUND_PENDING con el ID de solicitud y Retry-After: 30. Conserva la misma Idempotency-Key y no envíes la misma imagen con una clave nueva.

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

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

Idempotencia y reintentos

Idempotency-Key queda vinculada al JSON serializado exacto, incluida la imagen y cada campo output enviado. Conserva los bytes originales y la clave.

• Misma clave y cuerpo exacto: reintento seguro sin una segunda reserva.
• Misma clave y cuerpo distinto: 409 IDEMPOTENCY_CONFLICT.
• Misma clave tras un estado terminal: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; no se repite el Base64.
• Clave nueva: solicitud nueva que puede reservar otro Credit.
• Espacios, orden de propiedades o valores predeterminados explícitos pueden cambiar el cuerpo serializado.

Reglas Retry-After

429 RATE_LIMITED

Espera 60 segundos y reintenta el cuerpo exacto con la misma clave.

503 REFUND_PENDING

Espera 30 segundos y reintenta el cuerpo exacto con la misma clave.

503 UPSTREAM_BUSY

Espera 10 segundos; usa otra clave solo para un intento nuevo intencional.

Timeout de red o API_UNAVAILABLE

Trata el resultado como desconocido y conserva cuerpo y clave hasta resolverlo.

Ejemplos

Sustituye los marcadores en tu servidor. La API Key nunca debe aparecer en un paquete público del 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}}}'

Puntos de partida comunes

Estas recetas son puntos de partida, no garantías permanentes de cumplimiento. Los nombres de plataformas son etiquetas, no valores de la 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}

Errores y diagnóstico

Cada error usa un estado HTTP estable y un código breve en JSON.

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

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

Diagnóstico seguro

1. Registra el estado HTTP, código, request_id cuando exista, hora e Idempotency-Key.
2. No registres ni envíes la clave Bearer, image_base64 completo o respuestas con datos de imagen.
3. Corrige primero los errores 4xx de solicitud, credenciales, saldo o cabeceras.
4. Respeta Retry-After y conserva cuerpo y clave para solicitudes sin resolver.
5. Contacta con soporte usando solo identificadores no secretos si el estado persiste.

Límites de la solicitud

Envía una imagen JPG, PNG o WebP por solicitud como Base64 estándar. La entrada decodificada admite hasta 5 MiB y el cuerpo JSON hasta 7.500.000 bytes. La salida personalizada admite 4.096 px por lado y 4.194.304 píxeles. Si el resultado exacto no cabe en la respuesta, la solicitud falla y se devuelve el Credit reservado; la API no cambia el tamaño o formato en silencio.