API Documentation
One API call. One clean image.
ClearCut removes image backgrounds with a single endpoint. Send an image, get back a transparent PNG. No megapixel limits, no confusing tiers, no SDK required.
Quickstart
Three steps to your first background removal:
Get Your API Key
Enter your email on the homepage and receive your key instantly. It arrives in your inbox and on-screen.
Make an API Call
Send an image to /v1/remove with your key. That's the entire API.
See examples belowGet Your PNG
Receive a transparent PNG back. Save it directly to a file.
curl -X POST https://clearcut-2834.polsia.app/v1/remove \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "image=@photo.jpg" \ -o result.png
const fs = require("fs");
const FormData = require("form-data");
const form = new FormData();
form.append("image", fs.createReadStream("photo.jpg"));
const res = await fetch("https://clearcut-2834.polsia.app/v1/remove", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", ...form.getHeaders() },
body: form
});
fs.writeFileSync("result.png", Buffer.from(await res.arrayBuffer()));
import requests
with open("photo.jpg", "rb") as f:
r = requests.post(
"https://clearcut-2834.polsia.app/v1/remove",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"image": f}
)
with open("result.png", "wb") as out:
out.write(r.content)
API Keys
Your API key is your identity. Include it in every request.
- Sign up on the ClearCut homepage by entering your email. Your key is generated instantly.
- Check your inbox for the welcome email. It contains your API key and a ready-to-run cURL command.
- Add the key to every request as a Bearer token in the Authorization header.
Key Format
All ClearCut API keys start with cc_ followed by 32 hex characters:
# Set once in your shell profile or .env export CLEARCUT_API_KEY="cc_your_key_here" # Use in requests curl -X POST https://clearcut-2834.polsia.app/v1/remove \ -H "Authorization: Bearer $CLEARCUT_API_KEY" \ -F "image=@photo.jpg" \ -o result.png
Try It Live
See background removal in action. This runs entirely in your browser using WebAssembly — your images never leave your device.
Drop an image here or click to upload
JPG, PNG, or WebP — max 10MB
Loading AI model...
First time takes a few seconds (~5MB download)
To do this via the API, run:
curl -X POST https://clearcut-2834.polsia.app/v1/remove \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@your-image.jpg" \
-o result.png
Remove Background
POST /v1/remove
Removes the background from an image and returns a transparent PNG.
Request
Headers
| Header | Value | Required |
|---|---|---|
Authorization |
Bearer YOUR_API_KEY |
Yes |
Content-Type |
multipart/form-data |
Yes (auto-set by most clients) |
Body Parameters
| Field | Type | Description |
|---|---|---|
image |
File | The image file. Accepts JPG, PNG, WebP. Max 25MB. |
Response
On success, returns the processed image directly as a PNG binary with these headers:
| Header | Description |
|---|---|
Content-Type |
image/png |
Content-Disposition |
attachment; filename="clearcut-{timestamp}.png" |
X-Processing-Time |
Processing duration (e.g., 1250ms) |
X-Original-Size |
Original file size in bytes |
X-Result-Size |
Result file size in bytes |
Error Codes
Errors return JSON with an error object:
{
"error": {
"code": "NO_IMAGE",
"message": "No image provided. Send a file with field name \"image\"."
}
}
| Status | Code | Description |
|---|---|---|
| 400 | NO_IMAGE |
No image file was included in the request |
| 400 | INVALID_FORMAT |
Unsupported file format (only JPG, PNG, WebP) |
| 401 | INVALID_KEY |
Missing or invalid API key |
| 413 | FILE_TOO_LARGE |
Image exceeds 25MB limit |
| 429 | RATE_LIMITED |
Too many requests — slow down |
| 500 | PROCESSING_FAILED |
Background removal failed — try a different image or retry |
Code Examples
Copy-paste examples in your language. Replace YOUR_API_KEY with your actual key.
# Basic usage — remove background and save result
curl -X POST https://clearcut-2834.polsia.app/v1/remove \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@photo.jpg" \
-o result.png
# With verbose output to see processing headers
curl -v -X POST https://clearcut-2834.polsia.app/v1/remove \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@photo.jpg" \
-o result.png 2>&1 | grep "X-Processing"
# Batch process a directory of images
for img in *.jpg; do
curl -s -X POST https://clearcut-2834.polsia.app/v1/remove \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@$img" \
-o "nobg-$img.png"
echo "Processed: $img"
done
import requests
API_KEY = "YOUR_API_KEY"
URL = "https://clearcut-2834.polsia.app/v1/remove"
def remove_background(input_path, output_path="result.png"):
"""Remove background from a single image."""
with open(input_path, "rb") as f:
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
files={"image": (input_path, f, "image/jpeg")}
)
if response.status_code == 200:
with open(output_path, "wb") as out:
out.write(response.content)
print(f"Saved to {output_path}")
print(f"Processing time: {response.headers.get('X-Processing-Time')}")
return True
else:
error = response.json()
print(f"Error {response.status_code}: {error['error']['message']}")
return False
# Single image
remove_background("photo.jpg")
# Batch process
import glob
for img in glob.glob("photos/*.jpg"):
remove_background(img, img.replace(".jpg", "-nobg.png"))
const fs = require("fs");
const FormData = require("form-data");
const API_KEY = "YOUR_API_KEY";
const URL = "https://clearcut-2834.polsia.app/v1/remove";
async function removeBackground(inputPath, outputPath = "result.png") {
const form = new FormData();
form.append("image", fs.createReadStream(inputPath));
const response = await fetch(URL, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
...form.getHeaders()
},
body: form
});
if (!response.ok) {
const error = await response.json();
throw new Error(`${response.status}: ${error.error.message}`);
}
const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync(outputPath, buffer);
console.log(`Saved to ${outputPath}`);
console.log(`Processing: ${response.headers.get("X-Processing-Time")}`);
console.log(`Size: ${(buffer.length / 1024).toFixed(1)} KB`);
}
// Single image
await removeBackground("photo.jpg");
// Batch process
const images = fs.readdirSync("photos").filter(f => f.endsWith(".jpg"));
for (const img of images) {
await removeBackground(`photos/${img}`, `output/${img.replace(".jpg", ".png")}`);
}
<?php
$apiKey = "YOUR_API_KEY";
$url = "https://clearcut-2834.polsia.app/v1/remove";
function removeBackground($inputPath, $outputPath = "result.png") {
global $apiKey, $url;
$ch = curl_init($url);
$cfile = new CURLFile($inputPath, "image/jpeg", basename($inputPath));
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . $apiKey
],
CURLOPT_POSTFIELDS => [
"image" => $cfile
]
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
file_put_contents($outputPath, $response);
echo "Saved to $outputPath\n";
return true;
} else {
$error = json_decode($response, true);
echo "Error $httpCode: " . $error["error"]["message"] . "\n";
return false;
}
}
// Single image
removeBackground("photo.jpg");
// Batch process
foreach (glob("photos/*.jpg") as $img) {
$output = str_replace(".jpg", "-nobg.png", $img);
removeBackground($img, $output);
}
Pricing
Start free. Pay only when you need more.
Perfect for testing and personal projects.
- 50 images per month
- Full resolution output
- All file formats (JPG, PNG, WebP)
- API + web demo access
For production apps and batch processing.
- Unlimited images
- Full resolution output
- Priority processing
- Higher rate limits
Rate Limits
Rate limits depend on your plan. Exceeding them returns a 429 status.
Check Usage
Check your current usage at any time:
GET /api/usage
curl https://clearcut-2834.polsia.app/api/usage \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"usage": {
"images_processed": 23,
"plan": "free",
"limit": 50,
"remaining": 27,
"member_since": "2026-04-15T10:30:00Z",
"reset_period": "monthly"
}
}
SDKs & Libraries
Official SDKs are coming soon. The API is one endpoint — most languages need just 5-10 lines of code (see examples above).
Coming soon
Coming soon
Ready to integrate?
Get your free API key and start removing backgrounds in under a minute.
Get API Key