REST API Reference
BackNull API v1
Authenticate every request using an API key created in your Dashboard. Keys can be passed via Authorization: Bearer ... or x-api-key.
Endpoint
POSThttps://api.backnull.com/v1/remove-background
curl -X POST "https://api.backnull.com/v1/remove-background?format=png" \
-H "Authorization: Bearer bn_live_your_api_key_here" \
-F "file=@product.jpg" \
--output cutout.pngParameters (Query, Form, or JSON)
| Parameter | Type | Description |
|---|---|---|
| file | binary (multipart) | PNG, JPEG, or WebP image file up to 15 MB (up to 25 MP resolution). Field names file, image, or image_file are accepted. |
| image_url | string | Public HTTP/HTTPS image URL (JSON body or form field). Private networks and metadata IPs are blocked. |
| image_base64 | string (JSON) | Base64-encoded PNG/JPEG/WebP string (optional data URI prefix stripped automatically). |
| format | "png" | "webp" | Output image format. Defaults to "png" with full RGBA alpha transparency. |
| size | "full" | "preview" | "hd" | "full" (default) preserves original resolution; "hd" caps longest edge at 1600px; "preview" caps at 800px. |
| bg_color | hex (#RRGGBB) | Optional hex color to flatten the transparent background onto a solid studio backdrop (e.g. #ffffff). |
| refine | boolean (default: true) | Applies automatic edge color decontamination (defringing), straight-alpha restoration, ghost-haze removal, and micro-speckle cleanup. |
Response Headers
Content-Type:image/pngorimage/webpX-Credits-Remaining: Combined credits left across subscription + top-up walletsX-Credits-Charged: Always1on HTTP 200,0on errorsX-Processing-Time-Ms: End-to-end processing time in milliseconds
Dual-Wallet Credit Order
Each successful 200 OK call deducts 1 credit atomically before inference begins. Active monthly subscription credits are consumed first; once depleted, your one-time top-up credit balance is used seamlessly. If inference fails, the reserved credit is automatically refunded.
Error Codes
| HTTP | Error Code | Details |
|---|---|---|
| 400 | unsupported_image_format / missing_image | No valid PNG, JPEG, or WebP payload found (0 credits charged). |
| 401 | invalid_api_key | Missing, malformed, or revoked API key. |
| 402 | insufficient_credits | Both monthly subscription quota and top-up reserve are 0. |
| 413 | image_too_large | Image exceeds 15 MB limit. |
| 429 | rate_limit_exceeded | Plan per-minute RPM limit exceeded; check Retry-After header. |
| 502 | processing_failed | Upstream error; reserved credit is automatically refunded. |
