API Documentation

Integrate background removal into your applications

Quick Start

# Set environment variables
export EASEBG_API_KEY="your_api_key"
export EASEBG_API_BASE="https://api.easebg.com/api/v1"

# Create a background removal task
curl -X POST "$EASEBG_API_BASE/open/developer/tasks" \
  -H "X-API-Key: $EASEBG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl": "https://example.com/photo.jpg"}

Authentication

All API requests require an API key passed in the X-API-Key header. You can generate API keys from the Developer Settings page in your workspace.

# All requests require an API Key in the Header
curl -H "X-API-Key: $EASEBG_API_KEY" \
  "$EASEBG_API_BASE/open/developer/tasks"

Upload Images

Before processing, upload your image to get a presigned URL. Use the returned URL to upload the file directly to storage.

# Upload image to get a presigned URL
curl -X POST "$EASEBG_API_BASE/app/tasks/uploads/presign" \
  -H "Authorization: Bearer $EASEBG_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "photo.jpg", "contentType": "image/jpeg"}'

# Use the returned uploadUrl to upload the file
curl -X PUT "$UPLOAD_URL" \
  --data-binary @photo.jpg

Remove Background

Create a background removal task by providing an image URL or a previously uploaded file reference.

# Create a background removal task (using image URL)
curl -X POST "$EASEBG_API_BASE/open/developer/tasks" \
  -H "X-API-Key: $EASEBG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/photo.jpg",
    "modelVersion": "easebg-2.0",
    "callbackUrl": "https://your-app.com/webhooks/easebg"
  }'

# Response example
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "status": "queued",
#   "modelVersion": "easebg-2.0",
#   "sourceUrl": "https://example.com/photo.jpg",
#   "resultUrl": null,
#   "creditCost": 1,
#   "createdAt": "2025-01-15T10:30:00Z",
#   "completedAt": null
# }

Task Status & Events

Poll the task endpoint for status updates, or query the task events endpoint to retrieve event history.

# Query task status
curl -H "X-API-Key: $EASEBG_API_KEY" \
  "$EASEBG_API_BASE/open/developer/tasks/550e8400-e29b-41d4-a716-446655440000"

# Query task event history
curl -H "Authorization: Bearer $EASEBG_JWT_TOKEN" \
  "$EASEBG_API_BASE/app/tasks/images/550e8400-e29b-41d4-a716-446655440000/events"

Webhooks

Configure webhook endpoints to receive automatic notifications when tasks complete. All webhooks are signed with HMAC-SHA256 for security.

Rate Limits

API requests are rate-limited based on your plan. Free: 10 req/min, Pro: 60 req/min, Team: 200 req/min. Exceeding the limit returns a 429 status code.

Error Codes

Code	Description
200	OK — Request successful
400	Bad Request — Invalid request parameters
401	Unauthorized — Missing or invalid API key
402	Payment Required — Insufficient credits to complete the task
429	Too Many Requests — Rate limit exceeded — retry after a delay
500	Internal Server Error — Server error — retry with exponential backoff

SDKs & Code Samples

Official SDKs are available for JavaScript/TypeScript and Python. You can also use cURL or any HTTP client.

JavaScript / TypeScript

import { EaseBGClient } from '@easebg/sdk';

const client = new EaseBGClient({
  apiKey: process.env.EASEBG_API_KEY,
});

const result = await client.removeBackground({
  imageUrl: 'https://example.com/photo.jpg',
});

Python

from easebg import EaseBGClient

client = EaseBGClient(
    api_key=os.environ['EASEBG_API_KEY']
)

result = client.remove_background(
    image_url='https://example.com/photo.jpg'
)

cURL

curl -X POST \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"..."}' \
  $URL/api/v1/open/developer/tasks