bg.tools REST API Documentation
The bg.tools REST API allows you to programmatically perform neural background removal, watermark erasing, facial anonymization, and image conversion over standard HTTPS requests.
1. Quickstart (5 Minutes)
Follow these three simple steps to start processing images:
- Create an Account & Sign In: Register on bg.tools (includes 10 free credits daily).
- Generate an API Key: Visit your Account Dashboard and generate a secret key (e.g.
bgt_live_...). - Make your first request: Copy and run the cURL snippet below:
curl -X POST https://bg.tools/api/v1/remove-background \ -H "Authorization: Bearer bgt_live_YOUR_KEY" \ -F "image=@photo.jpg" \ --output result.png
2. Authentication & API Keys
Authenticate your API requests by including your secret API key in the standard Authorization header:
3. Idempotency & Safe Retries
The bg.tools API supports the Idempotency-Key header to prevent double-charging your token balance during network retries.
When you include an idempotency key, the server caches the response for 24 hours. Any retry with the same key returns the cached result with header X-Idempotent-Replay: true and does NOT charge additional tokens.
4. Credits & Billing
Every API response includes two custom headers detailing your current token status:
X-Credits-Used: 1(the amount deducted for this request)X-Credits-Remaining: 49(your updated total token balance)
Credits are reserved inside an atomic SQLite transaction before image processing. If downstream inference fails for any reason, all credits are automatically refunded.
/api/v1/remove-background
Segment and remove backgrounds cleanly, outputting a transparent PNG with edge matting. You can specify which dedicated AI model engine to use according to your specific precision and speed requirements.
image (binary file, multipart): Image file (PNG, JPG, WebP up to 30 MB)image_url (string, JSON): Remote HTTPS URL to download image with SSRF protectionmodel (string, optional): AI model to execute (ganga, karudi, brahmaputra). Default: gangaresponse_format (string): binary (default) or json// Example Response when response_format="json"
{
"success": true,
"model": "ganga",
"image": "data:image/png;base64,iVBORw0KGgo...",
"format": "png",
"width": 1200,
"height": 800,
"credits_used": 1,
"credits_remaining": 49,
"request_id": "req_9f3a18b2c45e"
}/api/v1/remove-watermark
Deep neural inpainting to erase text, watermarks, and logos while preserving 100% of the original background texture.
/api/v1/blur-face
Automated facial detection and blurring with customizable blurType (gaussian, pixelate, solid_black) and strength.
Image Converters & Optimization (0.25 Credit Each)
quality: 10-100).format: png|jpeg|webp).width, height).x, y, width, height).HTTP Status Codes & Error Catalog
| Status | Error Code | Description |
|---|---|---|
| 400 | api_key_in_query | Keys in query parameters rejected |
| 401 | unauthorized / invalid_api_key | Missing, invalid, or revoked key |
| 402 | insufficient_credits | Credit balance too low for tool |
| 403 | insufficient_scope / ip_not_allowed | Scope violation or IP allowlist block |
| 413 | payload_too_large | File size exceeds 30 MB |
| 415 | unsupported_media_type | Non-image or executable binary detected |
| 429 | rate_limit_exceeded / quota_exceeded | Requests per minute or daily quota reached |
| 503 | engine_busy / api_disabled | Inference queue saturated or maintenance |
Security & Privacy Guarantees
Zero Image Storage: bg.tools operates a strict ephemeral-only processing architecture. Customer images are decoded in memory, processed through our neural engines, and discarded immediately after HTTP transmission.
No Plaintext Key Storage: Your API secret keys are salted and hashed using cryptographic SHA-256 before storing in our database. We only store the key prefix for display. Plaintext keys are shown exactly once at creation time.
GDPR & Compliance: All metadata and EXIF location tags are automatically stripped from output images.