1 回の HTTP リクエストで、画像と動画の背景を削除できます。ML インフラは不要で、アプリ、ワークフロー、バックエンドに数分で ClearCut を組み込めます。

この API はプレーンな HTTP で、multipart または JSON のボディを受け付けるため、どの言語からでも利用できます。API キーで認証し、画像または動画を送信すると、きれいな切り抜きが返ってきます。

• • 1 回の呼び出しで、どの言語からでも — multipart、URL、base64 で入力し、JSON、ホスト URL、生バイトで受け取れます。
• • わかりやすい課金 — クレジットが消費されるのは成功時のみです。動画のクレジットは事前に確保され、精算され、失敗時には返金されます。
• • 必要なときは非同期で — 動画はバックグラウンドで実行され、進捗、Webhook、キャンセルに対応します。
• • 本番運用向けの制御 — キーごとのレート制限、月間上限、IP とドメインの許可リスト。

1. アカウントを作成し、ダッシュボードで API キーを取得します。

2. 最初のリクエストを送信します。

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"

レスポンスは既定で JSON となり、ホスト URL の result.url を含みます。response_type=binary を指定すると、画像のバイトを直接ストリーミングで受け取れます。

API キーを X-API-Key ヘッダーで送信します。キーはダッシュボードで作成し、表示されるのは一度だけです（SHA-256 ハッシュとして保存されます）。

ダッシュボードのアクセストークンを使って、プログラムからキーを作成できます。

# 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

ファイルのアップロード、URL、base64 文字列を受け付けます。透過の切り抜き、または色や画像の背景に合成した結果を返します。

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"

レスポンス

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

ジョブのステータス

{
  "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 は https://api.clearcutapi.com です。インタラクティブな OpenAPI ドキュメントは、API ホストの /docs で提供されています。

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).

エラーは、固定の code、メッセージ、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.