Background Removal API

The bgly API is asynchronous. Submit a removal request, save the task ID, and poll until the task succeeds or fails.

Create or manage API keys

Base URL

https://bgly.net/api/v1

Authentication

Create an API key from Settings → API Keys. Send it as a Bearer token on every request.

Authorization: Bearer sk_your_api_key

API access requires a paid plan or credit purchase. The full key is displayed only once when it is created.

Billing

• Web and API requests share the same credit balance.
• Standard processing costs 1 credit. HD (precision: "high") costs 2 credits.
• Credits are reserved when the task is created. Failed tasks are refunded.
• Paid API users receive the full-resolution result URL. There is no extra download charge.

Create a removal

POST /bg/removals

curl -X POST 'https://bgly.net/api/v1/bg/removals' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-request-001' \
  -d '{
    "model": "bg-remover",
    "image_url": "https://example.com/photo.jpg",
    "subject": "auto",
    "precision": "standard",
    "output_format": "png"
  }'

Successful submission returns HTTP 202:

{
  "id": "task_xxx",
  "object": "bg.removal",
  "model": "bg-remover",
  "status": "queued",
  "input": {
    "image_url": "https://example.com/photo.jpg",
    "subject": "auto",
    "precision": "standard",
    "output_format": "png"
  },
  "output": null,
  "usage": null,
  "error": null
}

Request fields

Field	Type	Required	Description
image_url	string	yes	Public HTTP(S) URL of the source image
model	string	no	Must be bg-remover if sent
subject	string	no	auto (default), product, portrait , or hair
precision	string	no	standard (default, 1 credit) or high (HD, 2 credits). hd is accepted as an alias for high.
output_format	string	no	png (default) or webp

Idempotency-Key is optional but recommended. Reusing the same key with the same body returns the original task without another charge. Reusing it with a different body returns HTTP 409.

This version accepts a public image URL only. Multipart upload is not available yet.

Query task status

GET /bg/removals/{task_id}

curl 'https://bgly.net/api/v1/bg/removals/task_xxx' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Poll every 2–5 seconds. A successful task returns:

{
  "id": "task_xxx",
  "object": "bg.removal",
  "model": "bg-remover",
  "status": "succeeded",
  "output": {
    "url": "https://cdn.bgly.net/.../output.png",
    "width": 1600,
    "height": 1200,
    "format": "png"
  },
  "usage": { "credits": 1 },
  "error": null
}

Statuses are queued, processing, succeeded, failed, and canceled.

Result URLs may expire. Download the file promptly if you need a local copy.

JavaScript example

const headers = {
  Authorization: `Bearer ${process.env.BGLY_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': crypto.randomUUID(),
};

const created = await fetch('https://bgly.net/api/v1/bg/removals', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image_url: 'https://example.com/photo.jpg',
    precision: 'standard',
  }),
}).then((response) => response.json());

const task = await fetch(`https://bgly.net/api/v1/bg/removals/${created.id}`, {
  headers: { Authorization: headers.Authorization },
}).then((response) => response.json());

Python example

import os
import uuid
import requests

base_url = "https://bgly.net/api/v1"
headers = {
    "Authorization": f"Bearer {os.environ['BGLY_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
}

created = requests.post(
    f"{base_url}/bg/removals",
    headers=headers,
    json={"image_url": "https://example.com/photo.jpg"},
).json()

task = requests.get(
    f"{base_url}/bg/removals/{created['id']}",
    headers={"Authorization": headers["Authorization"]},
).json()

Errors

Errors use HTTP status codes and a consistent body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "request_id": "request_xxx"
  }
}

HTTP	Code	Meaning
400	invalid_request	Invalid request parameters
401	invalid_api_key	Missing, invalid, or deleted API key
402	insufficient_credits	Not enough credits
403	api_access_required	No paid plan or credit purchase
404	task_not_found	Task not found or belongs to another user
409	idempotency_conflict	Idempotency key reused with another request
429	rate_limit_exceeded / concurrency_limit	Too many requests, or too many jobs in progress

The machine-readable OpenAPI specification is available at https://bgly.net/openapi.json.