Skip to content

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.

Base URL: https://rmbg.pro/api

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.

X-API-KEY: your_api_key_here

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.com to 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=base64 for JSON with image_base64, or binary for 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.

StatusCode
400INVALID_REQUEST
401INVALID_API_KEY
402INSUFFICIENT_CREDITS
403FORBIDDEN
409IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESS / REQUEST_FAILED
413FILE_TOO_LARGE
415UNSUPPORTED_MEDIA_TYPE
429RATE_LIMIT_EXCEEDED
502PROCESSING_SERVICE_ERROR
503SERVICE_UNAVAILABLE
504PROCESSING_TIMEOUT

Remove Background

Remove the background of an image and get a transparent cutout. Optionally add a color, background image or logo.

POSThttps://rmbg.pro/api/remove-background

Cost: Configured RemoveBackground cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file.
return_typestring"base64" (JSON with image_base64, default) or "binary" (image response).
output_formatstringpng (default), jpeg or webp.
custom_bg_colorstringHex color such as #FFFFFF or #FFFFFF80.
custom_bg_imagefileBackground image placed behind the subject.
logofileLogo overlaid on the result.
position_logostringcenter-center, left-top, right-bottom, etc. (top-left style values are also accepted).
logo_size_percentagenumberLogo 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.

POSThttps://rmbg.pro/api/change-background

Cost: Configured RemoveBackground cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file.
return_typestring"base64" (JSON with image_base64, default) or "binary" (image response).
output_formatstringpng (default), jpeg or webp.
custom_bg_colorstringHex color such as #FFFFFF or #FFFFFF80.
custom_bg_imagefileBackground image placed behind the subject.
logofileLogo overlaid on the result.
position_logostringcenter-center, left-top, right-bottom, etc. (top-left style values are also accepted).
logo_size_percentagenumberLogo 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.

POSThttps://rmbg.pro/api/remove-background/my-lib/car-plate

Cost: Configured RemoveBackground cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG or WebP, up to 20 MB and 40 megapixels. Legacy alias: image_file.
return_typestring"base64" (JSON with image_base64, default) or "binary" (image response).
output_formatstringpng (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.

POSThttps://rmbg.pro/api/remove-object

Cost: Configured RemoveBackground cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG or WebP, up to 20 MB.
mask_imagerequiredfileMask with exactly the same dimensions as the image.
return_typestring"binary" (default) or "base64".
output_formatstringpng (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.

POSThttps://rmbg.pro/api/remove-watermark

Cost: Configured RemoveBackground cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG or WebP, up to 20 MB.
mask_imagerequiredfileMask with exactly the same dimensions as the image.
return_typestring"binary" (default) or "base64".
output_formatstringpng (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.

POSThttps://rmbg.pro/api/optimize-image

Cost: Configured OptimizeImage cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG, WebP, AVIF, GIF or TIFF, up to 20 MB and 40 megapixels. Animated images use the first frame. Legacy alias: image_file.
return_typestring"base64" (JSON with image_base64, default) or "binary" (image response).
output_formatstringwebp (default), original (keep the input format), png, jpeg or avif.
qualityinteger1 to 100 (default 80).
max_dimensionintegerLongest 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.

POSThttps://rmbg.pro/api/convert-image

Cost: Configured ConvertImage cost (1 credit by default)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG, WebP, AVIF, GIF or TIFF, up to 20 MB and 40 megapixels. Animated images use the first frame. Legacy alias: image_file.
return_typestring"base64" (JSON with image_base64, default) or "binary" (image response).
output_formatrequiredstringpng, jpeg (or jpg), webp, avif, gif or tiff.
qualityinteger1 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).

POSThttps://rmbg.pro/api/cloud-backup

Cost: Configured SaveImageOnRmbgCloud cost (1 credit by default, free on the website)

Parameters

ParameterTypeDescription
imagerequiredfilePNG, JPEG, WebP, GIF or AVIF, up to 20 MB and 40 megapixels. Stored as-is. Legacy alias: image_file.
collectionstringCollection name (for example your website name). Defaults to the ?website= host, or "Cloud backup".
collection_descriptionstringDescription used when the collection is created.
filenamestringOriginal 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.

POSThttps://rmbg.pro/api/restore

Cost: Configured Restore cost (0 credits by default)

Parameters

ParameterTypeDescription
imagerequiredfileThe 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.

POSThttps://rmbg.pro/api/ai-image-generation

Cost: Configured AIImageGenerated cost (20 credits by default)

Parameters

ParameterTypeDescription
promptrequiredstringDescribe the image or edits, 1–32,000 characters.
providerstringopenai (default). The model is configured by RMBG.PRO.
imagesarrayOptional: 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_typestring"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.png

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

POSThttps://rmbg.pro/api/pdf/to-text

Cost: 0 credits

Parameters

ParameterTypeDescription
filerequiredfilePDF 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.

POSThttps://rmbg.pro/api/pdf/to-markdown

Cost: 0 credits

Parameters

ParameterTypeDescription
filerequiredfilePDF 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

Browse all tools

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/main

Guides de l’API