Elimina fondos de imágenes y videos con una sola solicitud HTTP. Integra ClearCut en tu aplicación, flujo de trabajo o backend en minutos, sin infraestructura de ML.

La API usa HTTP plano con cuerpos multipart o JSON, así que funciona desde cualquier lenguaje. Autentícate con una clave de API, envía una imagen o un video y recibe un recorte limpio.

• • Una llamada, cualquier lenguaje: entrada multipart, URL o base64; respuesta en JSON, URL alojada o bytes sin procesar.
• • Facturación predecible: los créditos solo se cobran si el proceso tiene éxito; los de video se reservan, se concilian y se reembolsan si falla.
• • Asíncrono cuando importa: el video se procesa en segundo plano con progreso, webhooks y cancelación.
• • Controles de producción: límites por clave, topes mensuales y listas de IP y dominios permitidos.

1. Crea una cuenta y obtén una clave de API en tu panel.

2. Envía tu primera solicitud:

curl -X POST "https://api.clearcutapi.com/api/v1/removebg" \
  -H "X-API-Key: clearcut_live_YOUR_KEY" \
  -F "image_file=@/path/to/image.jpg" \
  -F "format=png" \
  -F "size=auto"

Las respuestas son JSON por defecto e incluyen un result.url alojado, o usa response_type=binary para recibir directamente los bytes de la imagen.

Envía tu clave de API en el encabezado X-API-Key. Las claves se crean en el panel y se muestran una sola vez (se guardan como hash SHA-256).

Crea claves por programa con el token de acceso de tu panel:

# Create an API key (use your dashboard JWT)
curl -X POST "https://api.clearcutapi.com/api/v1/api-keys" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "mode": "live"}'
# -> the full key is returned ONCE in the "key" field

Acepta un archivo subido, una URL o una cadena base64. Devuelve un recorte transparente o una composición sobre un fondo de color o imagen.

curl -X POST "https://api.clearcutapi.com/api/v1/removebg" \
  -H "X-API-Key: clearcut_live_YOUR_KEY" \
  -F "image_file=@/path/to/image.jpg" \
  -F "format=png" \
  -F "size=auto"

Respuesta

{
  "success": true,
  "job_id": "job_3f9c2a71b0d84e6c9a1f5e2d7b40",
  "status": "completed",
  "result": {
    "url": "https://cdn.clearcutapi.com/results/.../job_3f9c....png",
    "format": "png",
    "width": 1200,
    "height": 1200,
    "expires_at": "2026-12-31T23:59:59Z"
  },
  "usage": { "credits_used": 1, "credits_remaining": 999 }
}

Asynchronous — the request validates the clip, reserves credits and returns a queued job. Poll GET /api/v1/jobs/{job_id} or listen for webhooks. Requires a Pro plan or higher. Transparent output defaults to an alpha-channel .webm (VP9); backgrounds default to .mp4. Audio is preserved.

Credits: 5 per job + 1 per second, ×1.5 for HD (≥1280 px), +2 for a custom background. The estimate is reserved up front; unused credits are returned when the job finishes, and everything is refunded if it fails or you cancel it (POST /api/v1/jobs/{job_id}/cancel).

# 1. Start the job (returns job_id + status_url)
curl -X POST "https://api.clearcutapi.com/api/v1/remove-video-bg" \
  -H "X-API-Key: clearcut_live_YOUR_KEY" \
  -F "video_file=@/path/to/clip.mp4" \
  -F "format=webm" \
  -F "background=transparent"

# 2. Poll the status_url until status == "completed"
curl "https://api.clearcutapi.com/api/v1/jobs/JOB_ID" \
  -H "X-API-Key: clearcut_live_YOUR_KEY"

Estado del trabajo

{
  "success": true,
  "job_id": "job_8d1e...",
  "type": "video",
  "status": "processing",          // queued | processing | completed | failed | cancelled | expired
  "progress": 45,
  "message": "Removing background from video frames.",
  "result": null,                  // filled in when completed: url, format, width, height, duration, poster_url
  "usage": { "credits_used": 24, "credits_remaining": 976 }
}

For apps that composite layers themselves. format=zip on images returns:

color.jpg       # full-color image (RGB, no alpha)
alpha.png       # 8-bit matte: 255 = subject, 0 = background
metadata.json   # width, height, file names

Apply alpha.png as the alpha channel of color.jpg to rebuild the cutout. Video jobs withformat=zip_frames return the same idea per frame:

frames/00001.jpg ...   # color frames
alpha/00001.png  ...   # matching mattes
metadata.json          # frame_count, fps, width, height

URL base https://api.clearcutapi.com. La documentación interactiva de OpenAPI está en /docs en el host de la API.

Limits apply per API key (your plan's limit, or a lower one you set on the key), per workspace across all keys, per IP address, and per endpoint (video submissions are capped at a quarter of the key limit). Keys can also carry a monthly call cap.

Every API response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit reached (api key). Retry after 60 seconds.",
    "retry_after": 60,
    "request_id": "req_..."
  }
}

On 429 or a 5xx, wait and retry with growing delays: honor Retry-Afterwhen present, otherwise wait 1s, 2s, 4s, 8s… (capped) with random jitter. Don't retry other 4xx errors — fix the request.

import random, time, requests

def remove_bg_with_retry(path, max_attempts=5):
    for attempt in range(max_attempts):
        with open(path, "rb") as fh:
            resp = requests.post(
                "https://api.clearcutapi.com/api/v1/removebg",
                headers={"X-API-Key": "clearcut_live_YOUR_KEY"},
                files={"image_file": fh},
            )
        if resp.status_code != 429 and resp.status_code < 500:
            return resp  # success, or a 4xx you should fix rather than retry
        retry_after = resp.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
        time.sleep(delay + random.uniform(0, 0.5))  # jitter
    resp.raise_for_status()

Register endpoints in the dashboard to receive signed event notifications (job.completed, job.failed,credits.low, and more). Verify theX-ClearCut-Signature header:

import hmac, hashlib, time

def verify(secret, body, header, tolerance=300):
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.{body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Events: job.created, job.started, job.processing, job.completed, job.failed,credits.low, api_key.rate_limited. Failed deliveries retry with exponential backoff.

You can also pass webhook_url on a single request. Those deliveries are signed with your workspace signing secret (Dashboard → Webhooks → Per-request webhook URLs).

Los errores devuelven un formato coherente con un code estable, un mensaje y un request_id.

Chain steps into a reusable, versioned pipeline: remove background → QualityGuard gate → compose / AI background → enhance → marketplace export presets → human approval → publish to your store. Every run has a hard max_credits budget, a dry-run quote, step-by-step history and a CSV/JSON manifest. Nothing is published without an approval.

# Quote first (nothing is charged)
curl -X POST "https://api.clearcutapi.com/api/v1/workflows/WORKFLOW_ID/runs"   -H "X-API-Key: clearcut_live_YOUR_KEY" -H "Content-Type: application/json"   -d '{"inputs": {"asset_ids": ["ASSET_ID"]}, "max_credits": 10, "dry_run": true}'

# Run it under a hard budget, then follow step-by-step progress
curl -X POST "https://api.clearcutapi.com/api/v1/workflows/WORKFLOW_ID/runs"   -H "X-API-Key: clearcut_live_YOUR_KEY" -H "Content-Type: application/json"   -H "Idempotency-Key: catalog-2026-10-24"   -d '{"inputs": {"asset_ids": ["ASSET_ID"]}, "max_credits": 10}'
curl "https://api.clearcutapi.com/api/v1/workflow-runs/RUN_ID" -H "X-API-Key: clearcut_live_YOUR_KEY"

Official SDKs for Python and TypeScript/JavaScript send an Idempotency-Key on every job-creating call, retry 429 and 5xx with exponential backoff (honouring Retry-After), raise typed errors and verify webhook signatures.

# pip install clearcut-api
from clearcut import ClearCut, RateLimitError

cc = ClearCut("clearcut_live_YOUR_KEY")

result = cc.remove_background("product.jpg", format="png")
print(result.url, result.usage.credits_used)

# Async video: start and wait
job = cc.remove_video_background("clip.mp4", format="webm", wait=True)
print(job.result.url)

Prefer generating your own client? Use the OpenAPI schema or import the Postman collection from docs/postman/clearcut.postman_collection.json.