Cómo quitar el fondo de una imagen con una API

Quitar un fondo a mano lleva unos minutos por foto. Hacerlo con cada producto que se sube, cada foto de perfil o cada miniatura de tu app requiere una API para quitar fondos: entra una petición HTTP y sale un recorte terminado.

Esta guía explica cómo integrarla bien. Tendrás código funcional en cURL, Python y JavaScript, las opciones de salida que conviene conocer, cómo gestionar imágenes lentas y trabajos masivos, y cómo reintentar sin pagar dos veces. Los ejemplos usan removebackground.dev, nuestro producto hermano, pero los patrones sirven para cualquier proveedor.

Cómo funciona una API para quitar el fondo

Envías una imagen, el proveedor ejecuta un modelo de segmentación que separa al sujeto del fondo y recibes una imagen nueva. El núcleo del resultado es un canal alfa: un valor por píxel que indica cuánto de cada píxel pertenece al sujeto. Los píxeles totalmente opacos son el sujeto, los totalmente transparentes son fondo y los valores intermedios resuelven bordes suaves como pelo, pelaje y cristal.

A partir de esa máscara, la API puede devolver varias cosas:

• Un recorte transparente, normalmente un PNG o WebP sin fondo
• El sujeto sobre un color sólido, aplanado en un JPG para marketplaces que exigen fondo blanco
• La propia máscara, una imagen en escala de grises que puedes usar en tu propio flujo de composición
• Una versión recortada o redimensionada, ajustada al sujeto y a un tamaño exacto

La petición es la parte fácil. Una integración en producción también tiene que lidiar con imágenes que tardan más de lo normal, lotes grandes, límites de uso, reintentos y mantener la clave de API lejos de los usuarios.

Qué buscar en una API para quitar fondos

Antes de escribir código, comprueba estos puntos con tus propias imágenes y tu tráfico.

Paso 1: Crea una clave de API

Regístrate en removebackground.dev y crea una clave en la página de tu cuenta. Las cuentas nuevas reciben 50 créditos gratis, suficientes para ejecutar los ejemplos de abajo y probar con tus propias imágenes.

Guarda la clave en una variable de entorno de tu servidor:

export REMOVEBG_API_KEY="your_api_key"

Cada llamada envía la clave en la cabecera x-api-key y cada llamada gasta los créditos de esa cuenta. Crea una clave distinta por app o entorno para poder revocar una sin romper las demás.

Paso 2: Quita un fondo con cURL

El endpoint en tiempo real es POST https://removebackground.dev/v1/remove. La prueba más rápida es subir un archivo:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

La mayoría de las imágenes individuales vuelven terminadas en la misma respuesta, normalmente en pocos segundos, como PNG transparente a resolución completa.

El endpoint acepta la imagen de cuatro formas. Envía una de ellas:

Si una petición lleva varias, gana image_file, luego image_file_b64, luego image_url y por último el cuerpo en bruto. Las opciones pueden enviarse como campos de formulario, claves JSON o valores de query string.

Un detalle a vigilar: -o guarda el cuerpo sea cual sea el estado. Si la clave es incorrecta o la imagen no es válida, tu "PNG" es en realidad un error en JSON. Comprueba el código de estado antes de fiarte del archivo.

Paso 3: Gestiona 200, 202 y errores en Python

Una API para quitar fondos no puede prometer que cada imagen termine dentro de una sola petición HTTP. Cuando la cola está más ocupada de lo normal y una imagen tarda más de unos 55 segundos, removebackground.dev responde 202 Accepted con un id de trabajo en lugar de la imagen. El trabajo sigue en marcha y recuperas el resultado con ese id.

La regla clave: nunca reenvíes la imagen tras un 202. Eso inicia un segundo trabajo y puede costar un segundo crédito. Esta es una versión completa en Python que envía la imagen una sola vez y solo reintenta las llamadas seguras:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY
    # One key per image: a retry with the same key returns the same job, never a second charge.
    idem = {"Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url},
                         headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)

    if res.status_code != 202:
        return save(res, stem)  # 200 is the image; anything else raises

    # 202: still processing. Wait for the same job.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check /v1/jobs/{job_id} later.")


print(remove_background("https://example.com/photo.jpg"))

Necesita Python 3 y requests (pip install requests). Hay dos detalles fáciles de pasar por alto. Primero, detener tu script no detiene el trabajo: puede terminar igualmente y cobrarse, y el resultado aparece en el Studio de tu cuenta. Segundo, GET /v1/jobs/:id/result responde 409 not_ready mientras el trabajo está en marcha, así que trátalo como "espera", no como un fallo.

El mismo flujo en JavaScript (Node.js)

El mismo flujo en Node.js 18 o posterior, con los fetch, FormData y Blob integrados, subiendo un archivo local:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

La API acepta peticiones CORS, algo práctico para herramientas y pruebas. Eso no hace que sea seguro llamarla desde una página web con tu clave dentro. Más sobre esto en la sección de seguridad de abajo.

Paso 4: Controla la salida

La mayoría de las apps no quieren un recorte en bruto a resolución completa. Quieren una imagen de producto cuadrada sobre blanco, una vista previa pequeña o una máscara. Pedir a la API el archivo final te ahorra un segundo paso de procesamiento. Estas son las opciones de /v1/remove:

Todas las opciones cuestan el mismo 1 crédito, y los parámetros desconocidos se ignoran en silencio, así que una errata no dará error. Una imagen cuadrada para marketplace con el producto centrado y un 10% de margen queda así:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

Una respuesta correcta también trae cabeceras útiles. X-Credits-Remaining muestra tu saldo tras la imagen. X-Matte-Confidence (de 0 a 1) indica lo decidida que es la máscara, y X-Matte-Ambiguous-Ratio da la proporción de píxeles suaves como pelo, cristal o desenfoque de movimiento. Registrar esas dos te permite marcar los recortes de baja confianza para revisión humana en lugar de revisar cada imagen.

Paso 5: Procesa imágenes en lote

Para importaciones de catálogo y reprocesamientos, no lances cientos de peticiones sueltas. POST /v1/batch pone en cola hasta 100 URL públicas de imágenes como un solo trabajo, con las mismas opciones que /v1/remove, y responde 202 al instante:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

Algunas reglas de la documentación a tener en cuenta:

• El estado del trabajo termina como succeeded, partial (algunas imágenes fallaron) o failed. Cada elemento de items tiene su propio estado y, si falla, un código de error.
• Las entradas que no son URL http(s) y las URL repetidas se descartan y nunca se cobran. Cuando alguno de esos recuentos es mayor que 0, empareja los resultados por input en lugar de por posición.
• Puedes tener como máximo 3 trabajos de lote abiertos por cuenta. Un lote deja de contar cuando done es true.
• Si los créditos se agotan a mitad de lote, las imágenes terminadas quedan pagadas y el resto se marca como omitido con out_of_credits, sin coste.
• La API no tiene endpoint de cancelación, webhooks ni descarga en ZIP, así que el patrón es consultar periódicamente. Leer un trabajo es gratis y no tiene límite de peticiones.

¿Prefieres un script que puedas ejecutar tal cual? La guía de lotes con Python recorre un flujo completo de carpeta a carpeta.

Paso 6: Reintenta de forma segura y mantén la facturación predecible

Los timeouts de red son el origen de los cobros dobles. Tu cliente se rinde, reintenta y ahora existen dos trabajos para una imagen. La solución es una cabecera Idempotency-Key: cualquier cadena única de hasta 255 caracteres, como un UUID, una por imagen o lote. Si vuelves a enviar la misma petición con la misma clave, recibes el trabajo que creó la primera, con la cabecera Idempotent-Replayed: true, y sin nuevo cobro. Reutilizar una clave para otra imagen responde 409 idempotency_key_reused.

La facturación sigue una regla sencilla: 1 crédito cuando una imagen sale bien, nada cuando falla. Las peticiones rechazadas antes de procesarse, las imágenes ilegibles y los fallos tras los propios reintentos del proveedor son gratis, y volver a descargar un resultado terminado es gratis mientras siga guardado.

Límites a tener en cuenta en el diseño

Si necesitas más de 60 imágenes por minuto, la respuesta es el endpoint de lotes: una petición cubre hasta 100 imágenes. Guarda los resultados en tu propio bucket en cuanto los descargues, porque pasadas 48 horas los enlaces de resultado responden 410. Según la documentación del proveedor, las imágenes subidas no se usan para entrenar modelos.

Migrar desde la API de remove.bg

La web independiente y la API de autoservicio de remove.bg terminan el 1 de diciembre de 2026 a las 09:00 CET. Su API pasa a Leonardo.Ai, lo que obliga a cambiar tu integración. Si prefieres no reescribir nada, removebackground.dev tiene un endpoint compatible con remove.bg y la migración es una línea:

Mantienes la misma cabecera X-Api-Key (con una clave de removebackground.dev), los mismos nombres de parámetros, las mismas cabeceras de respuesta y el mismo formato de errores:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

Conoce las diferencias antes de cambiar:

• Sin 202. El endpoint compatible espera hasta 110 segundos y luego devuelve un timeout 503. El trabajo sigue en marcha y se cobra si sale bien, así que reintentar esa petición a ciegas inicia un segundo trabajo.
• Sin claves de idempotencia en este endpoint. Si necesitas reintentos seguros, pásate a /v1/remove con el tiempo.
• Algunas opciones se aceptan pero se ignoran: type y type_level (el sujeto se detecta automáticamente), semitransparency y las opciones de sombra (no se añaden sombras).
• El tamaño siempre cuesta 1 crédito, incluida la resolución completa.

La guía de migración incluye código de antes y después para cURL, Python, Node y PHP, además de pasos para Zapier, Make y n8n.

Mantén tu clave de API fuera del cliente

Este es el error que cuesta dinero de verdad. Si tu clave está en una página web, una app móvil, un repositorio público o una URL, cualquiera puede leerla y gastar tus créditos.

• Para que tus usuarios quiten fondos, envía sus imágenes a través de tu backend y llama a la API desde allí.
• Añade tu propio inicio de sesión y límites de gasto por usuario en ese backend.
• Usa una clave por app o entorno.
• Si una clave se filtra, revócala en la página de la cuenta. Deja de funcionar al instante. El proveedor solo guarda un hash de cada clave, así que crea una nueva en lugar de intentar recuperar la antigua.

Ejemplo: recortes para miniaturas de YouTube

Si creas herramientas para creadores, las miniaturas son un uso evidente. Una miniatura se ve sobre todo en tamaño pequeño, así que el recorte tiene que sostenerla: una cara o un producto, grande, con un borde nítido sobre un fondo simple. YouTube recomienda 3840 x 2160 px en 16:9 con un ancho mínimo de 640 px, y acepta JPG o PNG de hasta 50 MB desde un ordenador, pero solo 2 MB desde la app móvil.

En la parte de la API es una sola llamada que devuelve un PNG transparente ajustado al sujeto, listo para colocarlo sobre un lienzo 16:9:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

Haz una foto fija para el recorte en lugar de capturar un fotograma del video, ya que los fotogramas suelen salir movidos, y deja libre la esquina inferior derecha porque YouTube muestra ahí la duración del video. La página de miniaturas de YouTube cubre la parte de diseño, y nuestra guía para conseguir tus primeros 1,000 suscriptores explica por qué las miniaturas importan tanto.

Quitar fondos desde ChatGPT, Claude o Cursor

No todos los trabajos necesitan código. removebackground.dev también tiene un servidor MCP en https://removebackground.dev/mcp, así que puedes subir una foto en ChatGPT, Claude, Cursor, VS Code o n8n y pedir que se quite el fondo. En Claude Code es un solo comando:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

Después escribe /mcp en Claude Code para iniciar sesión. El servidor ofrece tres herramientas: remove_background, get_job para eliminaciones que tardan más de unos segundos, y check_credits. Cada imagen cuesta 1 crédito, igual que con la API.

Cuánto cuesta

removebackground.dev es de pago por uso, sin suscripción. Los créditos no caducan, las imágenes fallidas son gratis y las cuentas nuevas reciben 50 créditos gratis. A través de la API, 1 crédito equivale a una eliminación de fondo correcta a resolución completa.

Los precios están en USD y los créditos no usados se reembolsan en un plazo de 30 días. Hay precios por volumen por encima de Scale bajo petición. Consulta la página de precios para ver los detalles actuales.

Conclusión

Una buena integración para quitar fondos se reduce a unos pocos hábitos: guarda la clave en tu servidor, comprueba el estado antes de guardar el cuerpo, espera al trabajo en lugar de reenviar tras un 202, envía un Idempotency-Key con cada POST y usa el endpoint de lotes para el trabajo masivo.

La referencia completa, incluida la especificación OpenAPI 3.1, está en la documentación de la API. Si trabajas con video además de imágenes, nuestra comparativa de API de transcripción de YouTube y nuestra guía de integración de voz a texto usan los mismos patrones de producción para texto.