API quick start
Authenticate with your API key and remove a background from Python, JavaScript, PHP or cURL.
Authentication
Send your key in the X-API-Key header on every request:
| Header | Value |
|---|---|
| X-API-Key | clearcut_live_YOUR_KEY |
Keys start with clearcut_live_ (production) or clearcut_test_. Create, restrict and revoke keys in Developers → API Keys. Keep keys on your server, never in browser or mobile code.
Remove a background
POST https://api.clearcutapi.com/api/v1/removebg with one image source: image_file (upload), image_url or image_file_b64.
Useful parameters: size (preview, full or auto), format (png, jpg, webp, zip or auto), bg_color, bg_image_url, crop, shadow, margin, response_type and webhook_url.
The response_type parameter controls the reply:
| Value | You get |
|---|---|
| json (default) | JSON with the result link, width, height, format, credits used and credits remaining |
| binary | The image file itself; credits used are in the X-Credits-Used header |
Examples
- cURL: curl -X POST https://api.clearcutapi.com/api/v1/removebg -H "X-API-Key: KEY" -F image_file=@photo.jpg -F format=png -F response_type=binary -o cutout.png
- Python: requests.post(url, headers={"X-API-Key": KEY}, files={"image_file": open("photo.jpg", "rb")}, data={"format": "png"})
- JavaScript: fetch(url, { method: "POST", headers: { "X-API-Key": KEY }, body: formData })
- PHP (Laravel): Http::withHeaders(['X-API-Key' => KEY])->attach('image_file', fopen('photo.jpg', 'r'), 'photo.jpg')->post(url)
Full examples for every endpoint are on the Developers page. Prefer an SDK? There are official Python (clearcut-api) and TypeScript (@clearcut/sdk) packages, and an OpenAPI file and Postman collection.
Video
POST /api/v1/remove-video-bg queues a job and returns a job_id and status_url. Poll GET /api/v1/jobs/{job_id} every few seconds, or use a webhook. See Removing video backgrounds.
Restricting keys
For each key you can set allowed domains or IP addresses, a per-minute limit and a monthly cap. A request outside these limits is rejected with a clear error code.
Still need help?
Contact support