Remova fundos de imagens e vídeos com uma única solicitação HTTP. Integre a ClearCut ao seu aplicativo, fluxo de trabalho ou back-end em minutos, sem precisar de infraestrutura de ML.

A API usa HTTP simples com corpos multipart ou JSON, então funciona em qualquer linguagem. Autentique-se com uma chave de API, envie uma imagem ou um vídeo e receba um recorte limpo.

• • Uma chamada, qualquer linguagem — entrada multipart, URL ou base64; retorno em JSON, URL hospedada ou bytes brutos.
• • Cobrança previsível — os créditos só são cobrados em caso de sucesso; os créditos de vídeo são reservados, conciliados e reembolsados em caso de falha.
• • Assíncrono quando importa — o vídeo roda em segundo plano, com progresso, webhooks e cancelamento.
• • Controles de produção — limites de taxa por chave, tetos mensais e listas de IPs e domínios permitidos.

1. Crie uma conta e obtenha uma chave de API no seu painel.

2. Envie sua primeira solicitação:

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"

As respostas são em JSON por padrão e incluem um result.url hospedado. Ou defina response_type=binary para receber os bytes da imagem diretamente.

Envie sua chave de API no cabeçalho X-API-Key. As chaves são criadas no painel e exibidas uma única vez (armazenadas como hash SHA-256).

Crie chaves por programação com o token de acesso do seu painel:

# 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

Aceita um arquivo enviado, uma URL ou uma string base64. Retorna um recorte transparente ou uma composição sobre um fundo de cor ou imagem.

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"

Resposta

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

Status da tarefa

{
  "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. A documentação interativa OpenAPI fica em /docs no host da 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).

Os erros retornam um envelope consistente com um code estável, uma mensagem e um 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.