QuickBGRemover REST API Reference
Integrate automated, studio-grade AI background removal into your e-commerce platform, mobile app, print-on-demand workflow, or ERP catalog in under 5 minutes. Powered by serverless NVIDIA L4 GPU inference with dual BiRefNet models.
Authentication & Request Headers
All requests to QuickBGRemover REST API endpoints require standard Bearer token authorization in the Authorization HTTP header.
5-Line Quickstart Code Snippets
Select your language to copy production-ready boilerplate code.
curl -X POST https://quickbgremover.com/api/remove-bg \
-H "Authorization: Bearer rmv_live_demo88887777666655554444" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=800&q=80",
"subject_type": "product",
"shadow": "contact",
"canvas_ratio": "1:1",
"format": "PNG"
}'/api/remove-bg
Removes the background from an image. Accepts either JSON payload with image URLs/Base64 strings, or direct binary file uploads via multipart/form-data.
Request Parameters
| Parameter | Type | Requirement | Default | Description |
|---|---|---|---|---|
| image_url | string (URL) | Optional* | null | Public HTTP/HTTPS URL of the photo to segment. Protected by SSRF guards. |
| image_base64 | string (Data URL) | Optional* | null | Raw base64 or Data URL (data:image/png;base64,...). |
| image_file | Binary File | Optional* | null | Binary image file submitted via multipart/form-data. |
| subject_type | string (enum) | Optional | "auto" | Domain preset: auto, human, product, animal, car, graphic. |
| shadow | string (enum) | Optional | "none" | Automated grounding lighting: none, contact, floating, drop, reflection. |
| canvas_ratio | string (enum) | Optional | "original" | Marketplace aspect ratios: original, 1:1 (Amazon/Shopify), 4:5, 9:16, 16:9, 4:3. |
| format | string (enum) | Optional | "PNG" | Output image format: PNG, JPEG, WEBP, AVIF. |
* Exactly one image input source (image_url, image_base64, or image_file) must be provided.
JSON Response Schema (HTTP 200 OK)
{
"status": "success",
"data": {
"id": "task_1790099999_a8b9c",
"file_name": "red-sneaker.png",
"subject_type": "product",
"shadow": "contact",
"canvas_ratio": "1:1",
"format": "PNG",
"has_alpha": true,
"cutout_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"processing_engine": "Modal-NVIDIA-GPU-BiRefNet-DualEngine",
"plan_tier": "pro",
"execution_time_ms": 298,
"credits_remaining": 499
},
"meta": {
"api_version": "2026-09-01",
"powered_by": "QuickBGRemover Modal Serverless GPU Engine",
"license": "Subscription Active"
}
}/api/proxy-imageFetches external remote images on behalf of your client or server application to bypass browser CORS (Cross-Origin Resource Sharing) restrictions. Validates image MIME headers, enforces a 30MB security ceiling, and caches upstream assets.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string (URL-encoded) | Required | Public HTTP/HTTPS image URL to proxy. Example: https%3A%2F%2Fimages.unsplash.com%2Fphoto-1234 |
Example Request
curl -X GET "https://quickbgremover.com/api/proxy-image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1542291026-7eec264c27ff" \
--output proxied-sneaker.pngDomain-Specific Subject Intent Tuning
Optimized saliency masks tailored to specific photography categories
Pass the subject_type parameter to activate specialized trimap generation, alpha feathering, and color spill suppression parameters.
Universal balanced saliency detection (65% sensitivity, 1.0px feathering) suitable for general photos.
Fine flyaway hair isolation, whispy fringes, translucent veils, and fine jewelry without halo artifacts.
Crisp e-commerce contours (0.5px feathering), contact grounding shadows, and 1:1 marketplace centering.
Bilateral feathering (2.2px) tailored for fluffy dog/cat fur, whiskers, and paws.
Sharp vehicle silhouettes with 0px feathering and asphalt grounding shadow for dealerships.
Zero-halo hard cut for logos, icons, vector graphics, and digital signatures.
Studio Shadows & Marketplace Framing
Automated photorealistic grounding lighting and aspect ratios
Shadow Modes (shadow)
- none: Clean transparent background cutout without shadow.
- contact: Dark grounding ellipse underneath base (shoes, cosmetics, electronics).
- floating: Soft levitating ambient glow for floating headphones and gadgets.
- drop: Directional studio key-light drop shadow.
- reflection: Glossy mirrored floor reflection with linear alpha fade for perfume & watches.
Canvas Ratios (canvas_ratio)
- original: Retains native width and height of input photo.
- 1:1 Square: Centered with 10% breathing margin for Amazon, Shopify, Etsy & Instagram.
- 4:5 Portrait: Optimized for Instagram Feed & Pinterest pins.
- 9:16 Story: Fullscreen vertical ratio for TikTok, Reels & Shorts.
- 16:9 Landscape: Website hero banners and YouTube thumbnails.
Interactive API Playground
Test live requests against the QuickBGRemover GPU cluster
Rate Limits & Plan Quotas
API requests are metered per minute and per month based on your subscription tier. Every response includes standard rate limit headers to let you track quota usage in real time.
| Plan Tier | Monthly Cloud Credits | Rate Limit (Per Min) | Max Concurrent GPU Threads | Cost / Credit |
|---|---|---|---|---|
| Free Web Tier | 50 / mo | ❌ No API Access (Web only) | 1 | $0.00 |
| Pro Creator | 500 / mo | 120 req / min | 4 concurrent | ~$0.018 |
| Business Scale | 2,500 / mo | 300 req / min | 10 concurrent | ~$0.011 |
| Developer API | 10,000 / mo | 600 req / min | 25 concurrent | ~$0.0069 |
Error Codes & Remediation
Standard RFC-7807 compliant JSON error structures are returned for all non-200 HTTP responses.
| HTTP Status | Error Code | Description | Remediation Action |
|---|---|---|---|
| 400 | INVALID_REQUEST | Missing image payload or invalid parameter values. | Provide image_url, image_base64, or image_file. |
| 401 | AUTH_REQUIRED | Missing or malformed Authorization header. | Include Authorization: Bearer rmv_live_.... |
| 402 | INSUFFICIENT_CREDITS | Monthly credit quota exhausted (0 credits left). | Refill or upgrade your credit plan in the dashboard. |
| 403 | API_SUBSCRIPTION_REQUIRED | Free tier accounts cannot access the REST API. | Upgrade to Pro Creator ($9/mo) or higher. |
| 413 | PAYLOAD_TOO_LARGE | Supplied image file exceeds 30MB maximum size limit. | Compress image dimensions below 30MB before uploading. |
| 429 | RATE_LIMIT_EXCEEDED | Per-minute concurrency quota exceeded. | Throttle requests according to the Retry-After response header. |