API de QuitarFondo

Inicio rápido

1. Crea una clave en Configuración → API Keys (solo la gestión de claves requiere iniciar sesión).
2. Guárdala como QUITARFONDO_API_KEY en tu servidor.
3. Envía una foto y descarga el resultado de image_url.

export QUITARFONDO_API_KEY="TU_API_KEY"

curl --fail-with-body "https://quitarfondo.studio/api/v1/remove-background" \
  -H "Authorization: Bearer $QUITARFONDO_API_KEY" \
  -F "image_file=@foto.jpg"

¿Solo quieres comprobar que el servicio responde? GET /api/ping no requiere clave ni consume créditos.

Autenticación

Incluye la clave en cada petición. No se necesitan cookies ni una sesión del navegador. Crea, revoca o sustituye tus claves desde la configuración de tu cuenta.

Authorization: Bearer TU_API_KEY

No publiques la clave en el frontend, URLs, repositorios o capturas. Si se filtra, revócala y crea otra. Usa HTTPS y llama a la API desde tu backend.

Solicitud

Envía una sola imagen con una de estas dos opciones. No envíes ambos campos. No se admiten URLs remotas ni ajustes de modelo.

{
  "image_base64": "data:image/png;base64,BASE64_DE_TU_IMAGEN"
}

Máximo 1,5 MB de imagen y 1536 px por lado. El cuerpo completo, incluido base64 o multipart, no puede superar 2,1 MB. Ajusta la imagen antes de enviarla.

Respuesta

Una solicitud correcta devuelve HTTP 200 y JSON. El resultado es una URL HTTPS temporal del PNG transparente; descárgalo y almacénalo en tu propio sistema.

{
  "image_url": "https://…/resultado.png",
  "credits_used": 1,
  "credits_remaining": 5,
  "request_id": "0c0fd8e6-…"
}

• credits_used: coste de esta operación.
• credits_remaining: saldo justo después del débito; otras peticiones concurrentes pueden cambiarlo.
• request_id: identificador que debes facilitar a soporte si hay un problema.

Lotes de imágenes

POST/api/v1/remove-background/batch

Envía de 1 a 10 imágenes en una sola solicitud: repite el campo image_files en multipart/form-data o usa images_base64 (lista de data URLs) en JSON. Cada imagen sigue los mismos límites que una solicitud individual. Si alguna es inválida, el lote completo se rechaza con HTTP 400 antes de cobrar nada.

curl --fail-with-body "https://quitarfondo.studio/api/v1/remove-background/batch" \
  -H "Authorization: Bearer $QUITARFONDO_API_KEY" \
  -F "image_files=@foto-1.jpg" \
  -F "image_files=@foto-2.png"

El lote cobra 1 crédito por imagen al empezar y devuelve en un solo reembolso los créditos de las imágenes que fallen. La respuesta indica el resultado de cada imagen en el mismo orden en que la enviaste.

{
  "results": [
    {
      "index": 0,
      "image_url": "https://…/resultado-1.png"
    },
    {
      "index": 1,
      "error": {
        "code": "processing_failed",
        "message": "Procesamiento fallido; crédito devuelto."
      }
    }
  ],
  "images_processed": 1,
  "images_failed": 1,
  "credits_used": 1,
  "credits_remaining": 9,
  "request_id": "0c0fd8e6-…"
}

Compatible con remove.bg

Si ya usas la API de remove.bg, cambia solo el host: los mismos endpoints, la cabecera X-API-Key y los parámetros image_file, image_file_b64 e image_url (multipart, JSON o x-www-form-urlencoded). La respuesta es el PNG en binario, o {"data":{"result_b64":…}} con Accept: application/json, e incluye X-Credits-Charged, X-Width, X-Height y X-Foreground-*. Los errores usan el formato {"errors":[{"title","code"}]}.

curl -H "X-API-Key: $QUITARFONDO_API_KEY" \
  -F "image_file=@foto.jpg" -F "size=auto" \
  -F "bg_color=ffffff" -F "crop=true" -F "crop_margin=5%" \
  -o producto.jpg https://quitarfondo.studio/v1.0/removebg

• size: preview (hasta 0,25 MP, cuesta 0,25 créditos), small/regular (0,25 MP), medium (1,5 MP), hd (4 MP) y full/4k/auto (resolución original, hasta 10 MP). Todos menos preview cuestan 1 crédito.
• format: auto (PNG si hay transparencia, JPG si el fondo es opaco), png, jpg, webp o zip (color.jpg + alpha.png). channels=alpha devuelve solo la máscara.
• Fondo: bg_color (hex como 81d4fa, 81d4fa77 con transparencia, o nombres como white), bg_image_url o bg_image_file; add_shadow=true añade una sombra suave (shadow_opacity 0–100).
• Encuadre: crop=true recorta al sujeto, crop_margin (30px, 10%, 1, 2 o 4 valores), scale (10%–100%), position (center, original o x% y%) y roi (x1 y1 x2 y2 en px o %) para detectar solo dentro de una zona.
• GET /v1.0/account devuelve tu saldo de créditos con la misma estructura que remove.bg. Archivos de hasta 22 MB; type se detecta siempre automáticamente.

Créditos y límites

Cada imagen procesada cuesta 1 crédito. Se comprueba el saldo antes de llamar al procesador. Si falla el procesamiento, se devuelve el débito; si el reembolso no puede confirmarse, recibirás refund_pending para contactar con soporte.

Cada clave puede procesar hasta 500 imágenes por minuto, como remove.bg: cada imagen cuenta 1 por megapíxel iniciado (1600 × 1200 cuenta 2) y se suman las solicitudes individuales, los lotes y el endpoint compatible. Si un lote no cabe en lo que queda del minuto, se rechaza completo con HTTP 429 sin cobrar créditos. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un 429 añade Retry-After en segundos.

Evita reintentar automáticamente una petición que haya agotado el tiempo: si ya se procesó, reenviarla crea otra operación y puede consumir más créditos.

Errores

{
  "error": {
    "code": "invalid_api_key",
    "message": "Clave inválida o caducada."
  },
  "request_id": "0c0fd8e6-…"
}

Siguientes pasos