API Documentation

Introduction

The PoofBG API lets you remove image backgrounds programmatically. Upload an image or provide a URL, and get back a link to the transparent PNG result in seconds.

Base URL

https://api.poofbg.com/v1

All API requests must be made over HTTPS. Responses are returned as JSON unless otherwise noted. Each background removal costs 1 credit.

Authentication

Authenticate by including your API key in the Authorization header of every request. API keys use the pk_live_ prefix.

You can create and manage API keys from the developer dashboard.

Example header

Authorization: Bearer pk_live_YOUR_API_KEY

Requests without a valid API key will receive a 401 Unauthorized response.

Remove Background

The primary endpoint. Accepts an image file or URL, removes the background, and returns a JSON response with a result_url to download the transparent PNG. The request blocks for up to 30 seconds while processing. If the job takes longer, a 202 response is returned with the job ID for polling.

Option 1: File upload

Send the image as multipart/form-data with a file field. Accepted formats: JPEG, PNG, WebP. Maximum file size: 10 MB.

curl -X POST https://api.poofbg.com/v1/remove-background \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY" \
  -F "[email protected]"

Option 2: Image URL

Send a JSON body with an image_url field. For URL-based processing, only JPEG and PNG images are supported. If the remote file is inaccessible or unsupported, the job can still be accepted and later finish with a failed status.

curl -X POST https://api.poofbg.com/v1/remove-background \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'

Response (200 - completed)

{
  "id": "job_abc123",
  "status": "completed",
  "error": null,
  "created_at": "2026-03-18T12:00:00Z",
  "completed_at": "2026-03-18T12:00:02Z",
  "credits_used": 1,
  "credits_remaining": 42,
  "result_url": "https://cdn.poofbg.com/results/..."
}

Download the result by fetching the result_url. The URL is a signed link valid for 1 hour.

Response (202 - still processing)

If processing exceeds 30 seconds, the API returns a 202 Accepted response. Poll GET /v1/jobs/:id to check for completion.

{
  "id": "job_abc123",
  "status": "processing",
  "error": null,
  "created_at": "2026-03-18T12:00:00Z",
  "completed_at": null,
  "credits_used": 1,
  "credits_remaining": 42,
  "result_url": null
}

Get Job

Retrieve the current status and result of a background removal job. Use this to poll for completion after receiving a 202 response.

Example request

curl https://api.poofbg.com/v1/jobs/job_abc123 \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Response

{
  "id": "job_abc123",
  "status": "completed",
  "error": null,
  "created_at": "2026-03-18T12:00:00Z",
  "completed_at": "2026-03-18T12:00:02Z",
  "credits_used": 1,
  "credits_remaining": 42,
  "result_url": "https://cdn.poofbg.com/results/..."
}

The result_url is only present when status is "completed". Possible statuses: pending, processing, completed, failed.

List Jobs

List your recent background removal jobs, sorted by creation date (newest first).

Query parameters

Response

{
  "data": [
    {
      "id": "job_abc123",
      "status": "completed",
      "created_at": "2026-03-18T12:00:00Z",
      "completed_at": "2026-03-18T12:00:02Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Account

Returns information about your account, including your current plan, remaining credits, and rate limits.

Response

{
  "plan": "pro",
  "credits_remaining": 487,
  "credits_monthly_quota": 500,
  "rate_limit": {
    "requests_per_minute": 120
  }
}

Rate Limiting

API requests are rate-limited per account based on your plan. Limits are enforced using a sliding window of 60 seconds.

Response headers

Every response includes rate limit information in the headers:

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with a machine-readable code and a human-readable message.

Error format

{
  "error": {
    "message": "Insufficient credits",
    "code": "INSUFFICIENT_CREDITS"
  }
}

Error codes

Plans & Pricing

Each API call to remove a background costs 1 credit. Credits and rate limits depend on your plan.

See pricing for full details and current prices.