API de eliminación de fondos: envías una solicitud y recibes el PNG terminado.

Envía tu imagen

POST /v1/remove acepta la imagen de cuatro formas. Envía una de ellas; si una solicitud incluye varias, gana image_file, luego image_file_b64, luego image_url y por último el cuerpo sin procesar. Estos ejemplos leen tu clave de la variable de entorno REMOVEBG_API_KEY (defínela con export REMOVEBG_API_KEY=…); fíjate en las comillas dobles, que permiten que la shell la sustituya.

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

Todos los ejemplos guardan el cuerpo en un archivo. Ese archivo solo es una imagen cuando el estado es 200; consulta Gestiona la respuesta.

Gestiona la respuesta

La mayoría de las imágenes individuales vuelven terminadas en la misma respuesta. Cuando la cola está inusualmente ocupada y una imagen tarda más de unos 55 segundos, recibes 202 Accepted con un id de trabajo. El trabajo sigue en marcha: obtén su resultado con el id. Volver a enviar la imagen iniciaría un segundo trabajo y podría costar un segundo crédito.

Un ejemplo completo

Gestiona la imagen terminada, un 202, un trabajo que falla y un límite de tiempo local. Envía la imagen una sola vez y solo reintenta las consultas de estado, que son 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: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    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 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    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 it later at /v1/jobs/{job_id}.")


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

• Detener tu script no detiene el trabajo; puede terminar igualmente y cobrarse. Su resultado aparecerá en tu Studio.
• Los límites de tiempo los eliges tú, no son una promesa nuestra; la mayoría de las imágenes terminan en unos segundos.
• El endpoint compatible con remove.bg funciona de otra forma: nunca responde 202 (ver más abajo).

Lotes, de principio a fin

1. Enviar

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

Hasta 100 URLs públicas de imágenes, más cualquiera de las opciones de /v1/remove. Las dos URLs de ejemplo de arriba costarían hasta 2 créditos si fueran imágenes reales. La respuesta llega al instante:

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

invalid cuenta las entradas que no son URLs http(s) y duplicates cuenta las repetidas; ambas se descartan y nunca se cobran. Guarda el id: es la forma de retomar el trabajo tras un reinicio.

2. Consulta el trabajo

GET /v1/jobs/:id cada pocos segundos hasta que done sea true. status pasa de queued a processing y termina como succeeded, partial (algunas imágenes fallaron) o failed. Un elemento que se está reintentando muestra retrying.

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. Descarga cada resultado

GET /v1/jobs/:id/result?item=N para cada elemento correcto (o usa su result_url). item es la position empezando en cero. Las posiciones siguen tu lista después de quitar las URLs no válidas y repetidas, así que si alguno de esos contadores es mayor que 0, empareja los resultados por input y no por índice.

• Un lote deja de contar para el límite de 3 lotes abiertos en cuanto done es true.
• La API no tiene endpoint de cancelación, webhooks ni descarga en ZIP. Los lotes iniciados desde la página Bulk se pueden cancelar o descargar en ZIP allí.

Reintentos, duplicados y facturación

Envía una Idempotency-Key y los reintentos no cobrarán dos veces. Añade una cabecera Idempotency-Key (cualquier cadena única de hasta 255 caracteres, como un UUID) a POST /v1/remove o POST /v1/batch, una clave por imagen o por lote. Si vuelves a enviar la misma solicitud con la misma clave, recibes el trabajo que creó la primera, con Idempotent-Replayed: true: ni trabajo nuevo ni cargo nuevo, aunque la primera solicitud siga en curso. La misma clave con otra imagen u otras opciones responde 409 idempotency_key_reused. Las claves pertenecen a tu cuenta y no caducan.

Sin clave, cada POST crea un trabajo nuevo, y cada trabajo que sale bien cuesta 1 crédito (el endpoint compatible con remove.bg POST /v1.0/removebg no admite claves). Consultar un trabajo (GET /v1/jobs/…) siempre es gratis y se puede repetir sin riesgo.

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

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

Qué cuesta un crédito

Cuándo reintentar

Límites y almacenamiento

Cuánto tiempo se conservan los resultados

Cada resultado se guarda de forma privada en tu cuenta durante 48 horas después de crearse y luego se elimina. Hasta entonces puedes volver a descargarlo gratis con GET /v1/jobs/:id/result o desde tu Studio. Después, los enlaces de resultado responden 410 result_unavailable; volver a procesar la imagen es un trabajo nuevo. Los registros de estado del trabajo se pueden seguir consultando cuando la imagen ya no existe. Consulta la política de privacidad para ver cómo se gestionan las subidas; no usamos tus imágenes para entrenar modelos.

Seguridad

Guarda tu clave de API en un servidor que controles. No la pongas en código del navegador, apps móviles, repositorios públicos ni URLs. Para que tus propios usuarios quiten fondos, envía sus imágenes a través de tu backend y añade ahí tu propio inicio de sesión y tus límites de gasto.

• La API admite CORS para que funcione desde herramientas y código del servidor. Eso no hace que sea seguro poner una clave en una página web: cualquiera puede leerla ahí.
• Todas las claves de una cuenta gastan el mismo saldo de créditos. Crea una clave distinta por app o entorno en la página de tu cuenta, para poder revocar una sin romper las demás.
• Si se filtra una clave, revócala enseguida en la página de tu cuenta (deja de funcionar al instante) y crea una nueva. Solo guardamos un hash de cada clave, así que no podemos volver a mostrártela.

Solución de problemas