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.

API Status
remove.bg
fal.ai
HuggingFace
Browser WASM

Quickstart

Three steps to your first background removal:

1

Get Your API Key

Enter your email on the homepage and receive your key instantly. It arrives in your inbox and on-screen.

2

Make an API Call

Send an image to /v1/remove with your key. That's the entire API.

See examples below
3

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

  1. Sign up on the ClearCut homepage by entering your email. Your key is generated instantly.
  2. Check your inbox for the welcome email. It contains your API key and a ready-to-run cURL command.
  3. 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:

cc_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
🔒 Keep your key secret. Don't commit it to git or expose it in client-side code. Use environment variables instead: CLEARCUT_API_KEY
Using environment variables
# 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.

Client-side processing — your images stay private
📸

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)

Original
Original
Result
Background Removed

To do this via the API, run:

API equivalent
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

ℹ️ Send your image as multipart/form-data with the field name image.

Headers

HeaderValueRequired
Authorization Bearer YOUR_API_KEY Yes
Content-Type multipart/form-data Yes (auto-set by most clients)

Body Parameters

FieldTypeDescription
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:

HeaderDescription
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
💡 The API returns the raw PNG binary — not JSON. Pipe the response body directly to a file (cURL -o result.png).

Error Codes

Errors return JSON with an error object:

Error Response Format
{
  "error": {
    "code": "NO_IMAGE",
    "message": "No image provided. Send a file with field name \"image\"."
  }
}
StatusCodeDescription
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.

Free
$0 / month

Perfect for testing and personal projects.

  • 50 images per month
  • Full resolution output
  • All file formats (JPG, PNG, WebP)
  • API + web demo access
🎉 No credit card required to start. Sign up, get your API key, and process up to 50 images/month for free.

Rate Limits

Rate limits depend on your plan. Exceeding them returns a 429 status.

Free
50
images / month
Pay As You Go
Unlimited
images / month
Usage resets monthly. Check your current count with the usage endpoint below.

Check Usage

Check your current usage at any time:

GET /api/usage

Request
curl https://clearcut-2834.polsia.app/api/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "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).

Node.js / JavaScript
npm install clearcut

Coming soon

Python
pip install clearcut

Coming soon


Ready to integrate?

Get your free API key and start removing backgrounds in under a minute.

Get API Key