Remove image backgrounds automatically with real alpha transparency.
OrbConvert follows an asynchronous pipeline for reliability and high-throughput processing:
Upload
Send multipart file to POST /api/uploads. Receive fileId.
Queue Job
Submit JSON to POST /api/conversions. Receive conversionId.
Poll Status
Poll GET /api/conversions/:id until status is completed.
Download
Retrieve converted file via the signed outputUrl or GET /api/files/:id/download.
All API requests require authentication. Pass your key or token in the HTTP header:
API Key
Include Authorization: Bearer <API_KEY> or x-api-key: <API_KEY>.
Authorization: Bearer ch_live_your_api_key_here
Guest Fingerprint (Testing)
For unauthenticated requests, send an x-guest-fingerprint header. Subject to guest quota.
x-guest-fingerprint: custom_client_device_id
/api/tools/remove-backgroundRemove background from an image file and export a genuine transparent PNG or WebP.
Options are strictly validated by the backend validator. Malformed or unrecognized options trigger a 400 Bad Request error.
| Option | Type | Accepted Values | Description |
|---|---|---|---|
| tolerance | string | supported value | Target encoder setting. |
| feather | string | supported value | Target encoder setting. |
| format | string | supported value | Target encoder setting. |
| backgroundColor | string | supported value | Target encoder setting. |
OrbConvert returns consistent JSON error envelopes for all 4xx and 5xx responses:
{
"error": {
"message": "File exceeds the 100 MB limit for free users.",
"code": "FILE_TOO_LARGE"
}
}| HTTP | Error Code | Cause & Resolution |
|---|---|---|
| 400 | BAD_REQUEST | Missing required fields (fileId or toFormat). |
| 400 | SAME_FORMAT_NOOP | Source and target format are identical without "jobIntent": "transform". |
| 400 | UNSUPPORTED_FORMAT | Input or target format is not supported by the conversion engine. |
| 400 | INVALID_OPTIONS | An option value was outside allowed bounds or not recognized. |
| 401 | UNAUTHORIZED | Missing, invalid, or expired API Key / JWT token. |
| 403 | FORBIDDEN | Account suspended or tool temporarily disabled by administrator. |
| 404 | NOT_FOUND | The specified fileId or conversionId does not exist. |
| 413 | FILE_TOO_LARGE | File size exceeds user plan limits (Guest: 25 MB, Free: 100 MB, Pro: 2 GB). |
| 429 | QUOTA_EXCEEDED | Daily conversion count or data bandwidth quota exhausted. |
| 429 | QUEUE_FULL_USER | Pending queue concurrency cap reached (Guest: 5, Free: 10, Pro: 20). |
| 503 | QUEUE_FULL_GLOBAL | System processing queue at peak capacity. Back off and retry. |
| 503 | MAINTENANCE_MODE | Platform is undergoing scheduled maintenance. |
| 500 | CONVERSION_ERROR | Internal processing engine failed while executing conversion. |
| Parameter | Guest Tier | Free Tier | Pro Tier |
|---|---|---|---|
| Max File Size | 25 MB | 100 MB | 2 GB |
| Concurrent Queue | 5 jobs | 10 jobs | 20 jobs |
| Daily Conversions | 10 / day | 25 / day | 500 / day |
| Rate Limit | 30/min · 500/hr | 30/min · 500/hr | 120/min · 2,000/hr |
| Polling Cadence | Recommended 2 – 5 seconds interval | ||
Was this page helpful?