Examples

Copy a complete starter, then adapt the focused examples to your workflow.

The basic and queue examples are complete programs. Other Python snippets reuse requests, BASE and HEADERS from the queue example. Node.js snippets reuse those constants plus form or the documented job ID.

A full-resolution cutout

Use full explicitly; the compatibility endpoint defaults to a small preview.

curl https://clearcut.sh/v1.0/removebg \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -H 'Idempotency-Key: catalog-photo-001' \
  -F 'image_file=@photo.jpg' \
  -F 'size=full' -F 'format=png' \
  -o cutout.png

An image from a URL

URL imports use the same resolution, file-size and credit rules as uploads.

curl https://clearcut.sh/v1.0/removebg \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -F "image_url=$IMAGE_URL" -F 'size=full' -o cutout.png

A white product background

Crop around the subject, leave a margin and add a contact shadow.

curl https://clearcut.sh/v1.0/removebg \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -F 'image_file=@product.jpg' -F 'size=full' \
  -F 'bg_color=ffffff' -F 'format=jpg' \
  -F 'crop=true' -F 'crop_margin=40' \
  -F 'shadow_type=ground' -F 'shadow_opacity=30' -o product.jpg

Hair, fur and fine edges

Fine detail uses 2 credits. Changing the download format does not change the credit cost.

curl https://clearcut.sh/v1.0/removebg \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -F 'image_file=@portrait.jpg' -F 'quality=quality' \
  -F 'size=full' -F 'format=webp' -o portrait.webp

Export the alpha mask

For your own compositor. Request ZIP instead for separate color.jpg and alpha.png files.

curl https://clearcut.sh/v1.0/removebg \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=full' \
  -F 'channels=alpha' -F 'format=png' -o mask.png

Submit, poll and download

Recommended for applications and batches. There is no long-lived upload request.

# Submit once. Save the returned id.
curl https://clearcut.sh/api/jobs \
  -H "X-API-Key: $CLEARCUT_API_KEY" \
  -H 'Idempotency-Key: catalog-photo-002' \
  -F 'image_file=@photo.jpg'

# Poll every 2 seconds until done or error.
curl https://clearcut.sh/api/jobs/IMAGE_ID \
  -H "X-API-Key: $CLEARCUT_API_KEY"

# Download when done.
curl https://clearcut.sh/api/files/IMAGE_ID/cutout.png \
  -H "X-API-Key: $CLEARCUT_API_KEY" -o cutout.png

Export a square social image

Reuse a finished job without another background-removal charge.

curl https://clearcut.sh/api/jobs/IMAGE_ID/export \
  -H "X-API-Key: $CLEARCUT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"format":"png","size":"full","settings":{"ratio":"square","bgMode":"color","bgColor":"#e9f2ec","scale":85,"shadow":25,"text":"New arrival","textColor":"#194c35","textSize":48,"textY":88}}' \
  -o social.png

Download a batch as ZIP

Submit individual jobs, wait for each one to finish, then export a shared batch.

curl https://clearcut.sh/api/batch/export \
  -H "X-API-Key: $CLEARCUT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"ids":["IMAGE_ID_1","IMAGE_ID_2"],"spec":{"format":"png","size":"full"}}' \
  -o batch.zip