Rimuovi lo sfondo da immagini e video con una sola richiesta HTTP. Integra ClearCut nella tua app, nel tuo workflow o nel backend in pochi minuti, senza infrastruttura ML.

L'API usa HTTP semplice con body multipart o JSON, quindi funziona con qualsiasi linguaggio. Autenticati con una chiave API, invia un'immagine o un video e ricevi un ritaglio pulito.

• • Una chiamata, qualsiasi linguaggio: input multipart, URL o base64; in risposta JSON, URL ospitato o byte grezzi.
• • Fatturazione prevedibile: i crediti vengono addebitati solo in caso di successo; quelli dei video vengono riservati, riconciliati e rimborsati in caso di errore.
• • Asincrono quando serve: i video girano in background con avanzamento, webhook e annullamento.
• • Controlli per la produzione: limiti di frequenza per chiave, tetti mensili, liste di IP e domini consentiti.

1. Crea un account e prendi una chiave API dalla dashboard.

2. Invia la tua prima richiesta:

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"

Le risposte sono in JSON per impostazione predefinita e includono un result.url ospitato; oppure imposta response_type=binary per ricevere direttamente i byte dell'immagine.

Invia la tua chiave API nell'header X-API-Key. Le chiavi si creano nella dashboard e vengono mostrate una sola volta (salvate come hash SHA-256).

Crea le chiavi via codice con il token di accesso della dashboard:

# 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

Accetta un file caricato, un URL o una stringa base64. Restituisce un ritaglio trasparente o una composizione su uno sfondo a colore o immagine.

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"

Risposta

{
  "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"

Stato del job

{
  "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 documentazione OpenAPI interattiva è disponibile su /docs nell'host dell'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).

Gli errori restituiscono un envelope coerente con un code stabile, un messaggio e 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.