API Reference
RMBG.PRO API Documentation
Background removal, background replacement and PDF conversion over a simple REST API.
Introduction
The RMBG.PRO API lets you process images and PDFs from your own application. Send a multipart/form-data request (or JSON for AI image generation) and get the result back as an image or JSON.
Migrating from the legacy host? Read the migration guide.
Authentication
Include your account API key, found in your profile, in the X-API-KEY header of every request.
Credits & Limits
- Images: PNG, JPEG or WebP, up to 20 MB and 40 megapixels (Optimize and Convert also accept AVIF, GIF and TIFF). PDFs: up to 15 MB.
- Background and inpainting operations use the configured RemoveBackground cost (1 credit by default). Optimize Image and Convert Image use their own configured costs (1 credit by default). Cloud Backup uses the SaveImageOnRmbgCloud cost (1 credit by default, free on the website). Restore uses the Restore cost (0 credits by default). PDF conversion costs 0 credits.
- Optional: add
?website=example.comto any endpoint to show the calling site as Site URL in your transaction history. - AI image generation and editing use AIImageGenerated (20 credits by default), including signed-in web calls. References: up to 4 images, 10 MB combined. Maximum AI request body: 15 MB JSON or 11 MB multipart.
- Credits are reserved before processing and refunded if processing fails.
- 60 requests per minute per account, with up to 4 operations processing at once. 429 responses include
Retry-After. - Use
return_type=base64for JSON withimage_base64, orbinaryfor an image response. Link output and URL imports are not supported.
Idempotency
Send a unique Idempotency-Key header for safe retries. The same key with the same input replays the original result without a second charge. Pending or conflicting requests return 409, and failed operations are refunded. Use a new key after a failure.
Errors
Errors return a JSON body with success=false, error, code and request_id. Rely on the HTTP status and code, not the message text.
| Status | Code |
|---|---|
| 400 | INVALID_REQUEST |
| 401 | INVALID_API_KEY |
| 402 | INSUFFICIENT_CREDITS |
| 403 | FORBIDDEN |
| 409 | IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESS / REQUEST_FAILED |
| 413 | FILE_TOO_LARGE |
| 415 | UNSUPPORTED_MEDIA_TYPE |
| 429 | RATE_LIMIT_EXCEEDED |
| 502 | PROCESSING_SERVICE_ERROR |
| 503 | SERVICE_UNAVAILABLE |
| 504 | PROCESSING_TIMEOUT |
Remove Background
Remove the background of an image and get a transparent cutout. Optionally add a color, background image or logo.
Cost: Configured RemoveBackground cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
| output_format | string | png (default), jpeg or webp. |
| custom_bg_color | string | Hex color such as #FFFFFF or #FFFFFF80. |
| custom_bg_image | file | Background image placed behind the subject. |
| logo | file | Logo overlaid on the result. |
| position_logo | string | center-center, left-top, right-bottom, etc. (top-left style values are also accepted). |
| logo_size_percentage | number | Logo size, greater than 0 and at most 100. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('return_type', 'binary');
formData.append('output_format', 'png');
const response = await axios.post('https://rmbg.pro/api/remove-background', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.png', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Change Background
Remove the background and replace it with a solid color or your own image.
Requires custom_bg_color or custom_bg_image.
Cost: Configured RemoveBackground cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
| output_format | string | png (default), jpeg or webp. |
| custom_bg_color | string | Hex color such as #FFFFFF or #FFFFFF80. |
| custom_bg_image | file | Background image placed behind the subject. |
| logo | file | Logo overlaid on the result. |
| position_logo | string | center-center, left-top, right-bottom, etc. (top-left style values are also accepted). |
| logo_size_percentage | number | Logo size, greater than 0 and at most 100. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('return_type', 'binary');
formData.append('custom_bg_color', '#FFFFFF');
const response = await axios.post('https://rmbg.pro/api/change-background', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.png', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Hide Car Plate
Detect license plates in an image and mask them to protect privacy.
Cost: Configured RemoveBackground cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
| output_format | string | png (default), jpeg or webp. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('return_type', 'binary');
formData.append('output_format', 'png');
const response = await axios.post('https://rmbg.pro/api/remove-background/my-lib/car-plate', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.png', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Remove Object
Erase a masked object from an image and fill the area naturally.
Available only when the tool is enabled on the platform.
Cost: Configured RemoveBackground cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG or WebP, up to 20 MB. |
| mask_imagerequired | file | Mask with exactly the same dimensions as the image. |
| return_type | string | "binary" (default) or "base64". |
| output_format | string | png (default), jpeg or webp. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('mask_image', fs.createReadStream('path/to/mask.png'));
formData.append('return_type', 'binary');
const response = await axios.post('https://rmbg.pro/api/remove-object', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.png', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Remove Watermark
Erase a masked watermark from an image.
Available only when the tool is enabled on the platform.
Cost: Configured RemoveBackground cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG or WebP, up to 20 MB. |
| mask_imagerequired | file | Mask with exactly the same dimensions as the image. |
| return_type | string | "binary" (default) or "base64". |
| output_format | string | png (default), jpeg or webp. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('mask_image', fs.createReadStream('path/to/mask.png'));
formData.append('return_type', 'binary');
const response = await axios.post('https://rmbg.pro/api/remove-watermark', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.png', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Optimize Image
Resize and compress an image for the web, like the Image Report optimizer. JSON responses include format, width, height, original_size, output_size and savings_percent.
When the format is unchanged, the result is never heavier than the original.
Cost: Configured OptimizeImage cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG, WebP, AVIF, GIF or TIFF, up to 20 MB and 40 megapixels. Animated images use the first frame. Legacy alias: image_file. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
| output_format | string | webp (default), original (keep the input format), png, jpeg or avif. |
| quality | integer | 1 to 100 (default 80). |
| max_dimension | integer | Longest side in pixels, without upscaling (default 1200). 0 keeps the original size. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('return_type', 'binary');
formData.append('output_format', 'webp');
formData.append('quality', '80');
formData.append('max_dimension', '1200');
const response = await axios.post('https://rmbg.pro/api/optimize-image', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.webp', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Convert Image
Convert an image to another format. JSON responses include format, width, height, original_size and output_size.
Transparent areas become white when converting to JPEG.
Cost: Configured ConvertImage cost (1 credit by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG, WebP, AVIF, GIF or TIFF, up to 20 MB and 40 megapixels. Animated images use the first frame. Legacy alias: image_file. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
| output_formatrequired | string | png, jpeg (or jpg), webp, avif, gif or tiff. |
| quality | integer | 1 to 100 for JPEG, WebP and AVIF (default 90). |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('return_type', 'binary');
formData.append('output_format', 'webp');
const response = await axios.post('https://rmbg.pro/api/convert-image', formData, {
responseType: 'arraybuffer',
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.webp', response.data);
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Cloud Backup
Save an image in one of your collections on RMBG.PRO. The collection is created (public) if it does not exist; an existing collection keeps its visibility. JSON responses include duplicate, image (id, slug, url) and collection (id, name, slug, url).
The same file sent again to the same collection is kept once (duplicate=true).
Cost: Configured SaveImageOnRmbgCloud cost (1 credit by default, free on the website)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | PNG, JPEG, WebP, GIF or AVIF, up to 20 MB and 40 megapixels. Stored as-is. Legacy alias: image_file. |
| collection | string | Collection name (for example your website name). Defaults to the ?website= host, or "Cloud backup". |
| collection_description | string | Description used when the collection is created. |
| filename | string | Original file name, used for the image name. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
formData.append('collection', 'My Website');
formData.append('filename', 'product.jpg');
const response = await axios.post('https://rmbg.pro/api/cloud-backup', formData, {
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.json', JSON.stringify(response.data, null, 2));
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Restore Original
Send a processed image to get back its original. JSON responses include found and, when found is true, image_base64 (the original), format, source_transaction_id, service and processed_at.
The match is on the exact processed file, not its name, among your latest 2,000 image transactions. found=false when no transaction matches or its images were deleted.
Cost: Configured Restore cost (0 credits by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| imagerequired | file | The processed image, as returned by the API (up to 20 MB). Legacy alias: image_file. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('image', fs.createReadStream('path/to/your/image.jpg'));
const response = await axios.post('https://rmbg.pro/api/restore', formData, {
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.json', JSON.stringify(response.data, null, 2));
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));AI Image Generation & Editing
Generate an image from a prompt, or edit reference images with OpenAI. Returns one 1024 × 1024 PNG. Send JSON or multipart/form-data.
Use your RMBG.PRO API key. Our OpenAI credentials stay on the server. The same credit cost applies to the web generator and external calls.
Cost: Configured AIImageGenerated cost (20 credits by default)
Parameters
| Parameter | Type | Description |
|---|---|---|
| promptrequired | string | Describe the image or edits, 1–32,000 characters. |
| provider | string | openai (default). The model is configured by RMBG.PRO. |
| images | array | Optional: up to 4 PNG/JPEG/WebP references, 10 MB combined, 40 megapixels each. JSON: [{data: raw base64, mimeType: "image/png"}]. Multipart: repeat the images file field. |
| return_type | string | "base64" (JSON with image_base64, default) or "binary" (image response). |
Example
const fs = require('node:fs');
async function run() {
const response = await fetch('https://rmbg.pro/api/ai-image-generation', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'YOUR_RMBG_API_KEY', 'Idempotency-Key': 'unique-image-123' },
body: JSON.stringify({
"provider": "openai",
"prompt": "A studio photo of a green sneaker on a white background",
"return_type": "binary"
})
});
if (!response.ok) throw new Error(await response.text());
fs.writeFileSync('output.png', Buffer.from(await response.arrayBuffer()));
console.log('Credits used:', response.headers.get('X-Credits-Used'));
}
run().catch(console.error);Edit an existing image
curl https://rmbg.pro/api/ai-image-generation \
-H "X-API-KEY: YOUR_RMBG_API_KEY" \
-H "Idempotency-Key: unique-edit-123" \
-F "prompt=Place this product on a beach at sunset" \
-F "[email protected]" \
-F "return_type=binary" --output edited.pngFor JSON output, omit return_type or use base64. The response includes image_base64, mime_type, provider, transaction_id, request_id and usage (credits_used and credits_remaining). Binary responses include X-Credits-Used. Successful idempotent retries use 0 additional credits. Saved images are available in your transaction history.
PDF to Text
Extract the text of a PDF as JSON.
Cost: 0 credits
Parameters
| Parameter | Type | Description |
|---|---|---|
| filerequired | file | PDF up to 15 MB with selectable text. No OCR. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('file', fs.createReadStream('path/to/document.pdf'));
const response = await axios.post('https://rmbg.pro/api/pdf/to-text', formData, {
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.json', JSON.stringify(response.data, null, 2));
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));PDF to Markdown
Convert a PDF to Markdown and get it back as JSON.
Cost: 0 credits
Parameters
| Parameter | Type | Description |
|---|---|---|
| filerequired | file | PDF up to 15 MB with selectable text. No OCR. |
Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
async function run() {
const formData = new FormData();
formData.append('file', fs.createReadStream('path/to/document.pdf'));
const response = await axios.post('https://rmbg.pro/api/pdf/to-markdown', formData, {
headers: {
...formData.getHeaders(),
'X-API-KEY': 'YOUR_API_KEY',
'Idempotency-Key': 'unique-key-123'
}
});
fs.writeFileSync('output.json', JSON.stringify(response.data, null, 2));
console.log('Done!');
}
run().catch((error) => console.error('Error:', error.response?.data || error.message));Website-only tools
These tools are available on the website but are not published as API endpoints:
- Compress PDF
- Merge / Split PDF
- Resize Image
- Add Watermark
Open source examples
Ready-to-run examples for popular frameworks are available in our public repository.
https://github.com/ch-moez/rmbg.pro-examples/tree/mainGuides de l’API
- Guide de l’API de suppression d’arrière-plan
Découvrez comment intégrer la suppression d’arrière-plan dans votre application.