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.png

Parameters (Query, Form, or JSON)

ParameterTypeDescription
filebinary (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_urlstringPublic HTTP/HTTPS image URL (JSON body or form field). Private networks and metadata IPs are blocked.
image_base64string (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_colorhex (#RRGGBB)Optional hex color to flatten the transparent background onto a solid studio backdrop (e.g. #ffffff).
refineboolean (default: true)Applies automatic edge color decontamination (defringing), straight-alpha restoration, ghost-haze removal, and micro-speckle cleanup.

Response Headers

  • Content-Type: image/png or image/webp
  • X-Credits-Remaining: Combined credits left across subscription + top-up wallets
  • X-Credits-Charged: Always 1 on HTTP 200, 0 on errors
  • X-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

HTTPError CodeDetails
400unsupported_image_format / missing_imageNo valid PNG, JPEG, or WebP payload found (0 credits charged).
401invalid_api_keyMissing, malformed, or revoked API key.
402insufficient_creditsBoth monthly subscription quota and top-up reserve are 0.
413image_too_largeImage exceeds 15 MB limit.
429rate_limit_exceededPlan per-minute RPM limit exceeded; check Retry-After header.
502processing_failedUpstream error; reserved credit is automatically refunded.