API Documentation

Remove backgrounds from images programmatically using our RESTful API

Quick Start

Get started with our API in minutes

1. Get your API key

Navigate to Account → API Keys and generate a new API key.

2. Make your first request

curl -X POST /api/v1/remove-bg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image_file=@/path/to/image.jpg"

3. Check job status

The API returns a jobId. Use it to check the status and retrieve the result.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API key secure

Never share your API key or commit it to version control. Treat it like a password.

API Endpoints

POST/api/v1/remove-bg

Submit an image for background removal. This is an asynchronous operation that returns a job ID.

Request

Content-Type: multipart/form-data or application/x-www-form-urlencoded

Parameter	Type	Required	Description
`image_file`	File	Yes*	Image file (JPEG, PNG, WEBP)
`image_url` NEW	String	Yes*	Image URL (alternative to file upload)
`webhook_url`	String	No	URL to receive completion notification

* Either image_file OR image_url must be provided

Response (202 Accepted)

{
  "jobId": "cm3abc123xyz",
  "status": "processing",
  "createdAt": "2025-01-15T10:30:00Z",
  "estimatedCompletionTime": "30-60 seconds"
}

Quick Example

# cURL - Upload File
curl -X POST /api/v1/remove-bg \
  -H "Authorization: Bearer sk_live_..." \
  -F "[email protected]"

# cURL - Use Image URL (NEW!)
curl -X POST /api/v1/remove-bg \
  -H "Authorization: Bearer sk_live_..." \
  -d "image_url=https://example.com/photo.jpg"

Complete Examples with Polling & Download

Choose between uploading a file directly or providing a publicly accessible image URL. All examples include job submission, status polling, and result download.

Option 1: Upload File

# 1. Submit image for background removal
curl -X POST /api/v1/remove-bg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image_file=@/path/to/photo.jpg"

# Response: {"jobId":"cm3abc123","status":"processing",...}

# 2. Poll for completion (check every 3-5 seconds)
curl /api/v1/jobs/RETURNED_JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. When status is "completed", download result
curl -O "OUTPUT_URL_FROM_RESPONSE"

Option 2: Use Image URL NEW

# 1. Submit image URL for background removal
curl -X POST /api/v1/remove-bg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "image_url=https://example.com/photo.jpg"

# 2-3. Poll and download (same as Option 1)

Rate Limits & Credits

Credit System

Each API call consumes 1 credit from your account. API calls use the same credit pool as the web interface.

Insufficient Credits

If you don't have enough credits, the API will return a 402 Payment Required error. Purchase more credits to continue using the API.

Credit Refunds

Credits are automatically refunded if a job fails due to a processing error.

Error Handling

Status Code	Description
`200 OK`	Request successful
`202 Accepted`	Job created and processing
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Invalid or missing API key
`402 Payment Required`	Insufficient credits
`403 Forbidden`	Account suspended or banned
`404 Not Found`	Resource not found
`500 Internal Server Error`	Server error

Webhooks (Optional)

Optionally provide a webhook_url when creating a job to receive a notification when processing completes.

Webhook Payload

{
  "jobId": "cm3abc123xyz",
  "status": "completed",
  "outputUrl": "https://your-app.com/uploads/output.png",
  "completedAt": "2025-01-15T10:30:45Z"
}

// On failure:
{
  "jobId": "cm3abc123xyz",
  "status": "failed",
  "errorMessage": "Processing failed",
  "completedAt": "2025-01-15T10:30:45Z"
}