API Documentation

Integrate background removal into your apps

Pro Feature

API access is available on Pro and Enterprise plans. Upgrade to integrate background removal into your applications.

Quick Start

Remove a background with a single API call. Here's a simple example using curl:

Remove background from URL

curl -X POST https://api.backg.one/api/v1/remove-background \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "quality": "fast"}'

Upload a file

curl -X POST https://api.backg.one/api/v1/remove-background \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "quality=hd"

Authentication

All API requests require authentication using an API key. Include your key in thex-api-keyheader.

x-api-key: bg_your_api_key_here

Keep your API key secret. Don't expose it in client-side code.

Base URL

https://api.backg.one/api/v1

Endpoints

POST/remove-background

Submit an image for background removal. Returns a job ID for tracking progress.

Request (JSON)

{
  "url": "https://example.com/image.jpg",  // Image URL
  "quality": "fast"                         // "fast" or "hd"
}

Request (Multipart)

file: <binary>     // Image file
quality: "hd"      // "fast" or "hd" (optional, default: "fast")

Response (202 Accepted)

{
  "jobId": "abc123",
  "remaining": { "sd": 499, "hd": 99 },
  "credits": 50
}

GET/jobs/:id

Check the status of a background removal job.

Response (Pending)

{
  "status": "pending",
  "jobId": "abc123",
  "position": 3
}

Response (Processing)

{
  "status": "processing",
  "jobId": "abc123"
}

Response (Completed)

{
  "status": "completed",
  "jobId": "abc123",
  "url": "https://cdn.backg.one/results/abc123.png",
  "originalName": "photo.jpg",
  "processedAt": "2024-01-15T10:30:00Z"
}

Response (Failed)

{
  "status": "failed",
  "jobId": "abc123",
  "error": "No subject found in image",
  "code": "NO_SUBJECTS_FOUND"
}

GET/usage

Get your current usage statistics.

Response

{
  "tier": "pro",
  "periodStart": "2024-01-01T00:00:00Z",
  "periodEnd": "2024-02-01T00:00:00Z",
  "sd": { "used": 150, "limit": 5000, "remaining": 4850 },
  "hd": { "used": 25, "limit": 1000, "remaining": 975 },
  "credits": { "balance": 50, "lifetimeUsed": 100 }
}

Quality Modes

Fast (SD)

Quick processing, good for most images. Uses 1 credit.

Processing time: ~2-5 seconds
Best for: Web images, thumbnails

HD

High quality for professional use. Uses 2 credits.

Processing time: ~5-15 seconds
Best for: Hair, fur, fine details

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Plan doesn't include API access
QUOTA_EXCEEDED	402	Monthly quota or credits exhausted
FILE_TOO_LARGE	400	File exceeds size limit
UNSUPPORTED_FORMAT	400	Invalid image format
NO_SUBJECTS_FOUND	200*	No foreground subject detected
PROCESSING_FAILED	200*	Background removal failed

* These errors are returned in the job status response, not the initial request.

Rate Limits

API requests are rate limited based on your plan:

Pro:60 requests/minute, 1,000 requests/day
Enterprise:Custom limits based on your agreement

Rate limit headers are included in all responses:X-RateLimit-Remaining

SDKs Coming Soon

Official SDKs for Python, Node.js, and more are in development.

In the meantime, the REST API works with any HTTP client.