One upload endpoint, with binary images on success and JSON on failure.
POST /api/v1/remove-background
Send a multipart/form-data body. No API key is required. Let your HTTP client generate the multipart boundary.
| Field | Type | Required | Description |
|---|---|---|---|
image | File | Yes | JPEG, PNG, or WebP image |
format | String | No | png by default, or webp |
Only these fields are accepted. Duplicate fields are rejected. Remote image URLs and base64 payloads are not supported. This is a nobg API, not a remove.bg compatibility endpoint.
The default input limit is 10 MiB and the pixel limit is 25 megapixels. File signatures must match the declared MIME type. When an animated input is accepted by Images, the output is a still image using anim: false.
Default quotas are 5 requests per UTC calendar minute and 20 validated image attempts per UTC day per IP. The service also has a shared 10,000-attempt monthly cap. Processing failures count. People sharing an IP share quotas, including callers behind one backend. See counting rules.
Status 200 with Content-Type: image/png or image/webp and Content-Disposition: attachment; filename="nobg.png" or nobg.webp. The response body contains image bytes, not JSON or a URL. Download it directly.
Responses include Cache-Control: no-store and an X-Request-Id header. nobg adds no storage or shared cache for image results.
{
"error": {
"code": "rate_limited",
"message": "Too many requests from this IP. Try again later.",
"requestId": "a-request-uuid"
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing fields, invalid multipart body, or duplicate/unknown fields |
| 400 | invalid_image | Images could not inspect or decode the file |
| 404 | not_found | Unknown route or unsupported method |
| 413 | payload_too_large | File, request body, or pixel count exceeds the limit |
| 415 | unsupported_format | Unsupported file signature, MIME mismatch, or output format |
| 429 | rate_limited | IP minute allowance exhausted; honor Retry-After |
| 429 | daily_limit_reached | IP daily image allowance exhausted |
| 429 | monthly_limit_reached | Shared monthly image budget exhausted |
| 502 | processing_failed | Cloudflare Images could not produce the result |
| 503 | not_configured | Quota or upload limit is not configured correctly |
| 500 | internal_error | Unexpected service failure |
Do not automatically retry validation errors. Respect the Retry-After header on a 429. A retry after a processing failure can repeat processing work.
GET /api/health requires no authentication and returns:
{ "status": "ok", "service": "nobg", "version": "0.1.0" }This is a liveness check. It does not call Images or verify paid-service access.
GET /api/openapi.json on your API host returns the OpenAPI 3.1 description. It is public and contains no secrets. The documentation website does not run the API.