Xóa nền ảnh và video chỉ với một yêu cầu HTTP. Tích hợp ClearCut vào ứng dụng, quy trình hoặc backend của bạn trong vài phút — không cần hạ tầng ML.

API dùng HTTP thuần với nội dung multipart hoặc JSON, nên hoạt động với mọi ngôn ngữ. Xác thực bằng khóa API, gửi ảnh hoặc video và nhận lại bản tách nền sạch.

• • Một lệnh gọi, mọi ngôn ngữ — đầu vào multipart, URL hoặc base64; kết quả trả về dạng JSON, URL lưu trữ hoặc byte thô.
• • Thanh toán dễ dự đoán — chỉ tính tín dụng khi thành công; tín dụng video được giữ trước, đối soát và hoàn lại khi thất bại.
• • Bất đồng bộ khi cần — video chạy nền với tiến độ, webhook và khả năng hủy.
• • Kiểm soát cho production — giới hạn tốc độ theo khóa, hạn mức hằng tháng, danh sách IP và tên miền được phép.

1. Tạo tài khoản và lấy khóa API từ bảng điều khiển.

2. Gửi yêu cầu đầu tiên của bạn:

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"

Phản hồi mặc định ở dạng JSON và có result.url được lưu trữ sẵn, hoặc đặt response_type=binary để nhận trực tiếp byte của ảnh.

Gửi khóa API của bạn trong header X-API-Key. Khóa được tạo trong bảng điều khiển và chỉ hiển thị một lần (được lưu dưới dạng băm SHA-256).

Tạo khóa bằng chương trình với token truy cập bảng điều khiển của bạn:

# 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

Nhận tệp tải lên, URL hoặc chuỗi base64. Trả về bản tách nền trong suốt hoặc ảnh ghép lên nền màu/ảnh.

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"

Phản hồi

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

Trạng thái tác vụ

{
  "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 gốc https://api.clearcutapi.com. Tài liệu OpenAPI tương tác có tại /docs trên máy chủ 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).

Lỗi được trả về trong một cấu trúc nhất quán gồm code ổn định, thông báo và 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.