Ruby library

CircleCI Gem Version codecov

Quickstart installation

Add the gem to your Gemfile and run bundle install:

“em “remove_bg”

Or run gem install remove_bg to install globally.

Please note the base configuration has the following resolution limits:

Output formatResolution limit
PNG10 megapixels
JPG25 megapixels

Full installation

For best performance and quality the gem requires an image processing library. Please install one of the following libraries:

The gem will auto-detect any image processing libraries present. However you may prefer to explicitly configure which library to use:

“by RemoveBg.configure do |config| config.image_processor = :minimagick # For ImageMagick or GraphicsMagick # or config.image_processor = :vips end

The full installation has the following resolution limits:

Output formatResolution limit
PNG25 megapixels
JPG25 megapixels
ZIP25 megapixels


Configuring an API key

To configure a global API key (used by default unless overridden per request):

“by RemoveBg.configure do |config| config.api_key = “

Maruku could not parse this XML/HTML: 

It’s not recommended to commit your API key to version control. You may want to read the API key from an environment variable (e.g. ENV.fetch("REMOVE_BG_API_KEY")) or find an alternative method.

Removing the background from an image

Currently the gem supports removing the background from a file or a URL:

“by RemoveBg.from_file(“image.png”) RemoveBg.from_url(“”)

Request options

The processing options outlined in the API reference can be specified per request:

“by RemoveBg.from_file(“image.png”, size: “hd”, type: “product”, channels: “rgba”)

The API key can also be specified per request:

“by RemoveBg.from_file(“image.png”, api_key: “

Maruku could not parse this XML/HTML: 

Handling the result

Background removal requests return a result object which includes the processed image data and the metadata about the operation.

“by result = RemoveBg.from_file(“image.png”) # => “\x89PNG…” result.height # => 333 result.width # => 500 result.credits_charged # => 1.0

There’s also a #save convenience method:

“by“processed/image.png”)“image.png”, overwrite: true) # Careful!

Producing transparent images over 10 megapixels

After configuring a full installation (detailed above) you can process images over 10 megapixels with a transparent output.

Process images with either the png or zip format. If you specify the zip format it’s possible to save the archive and handle composition yourself.

“by result = RemoveBg.from_file(“large-image.jpg”, format: “zip”)“result-with-transparency.png”)


result.save_zip(“”) # If you want to handle composition yourself

Rate limits

The API has rate limits. Image processing results include the rate limit information:

“by result = RemoveBg.from_file(“image.jpg”) result.rate_limit.to_s

Maruku could not parse this XML/HTML: 
<RateLimit reset_at='2020-05-20T12:00:00Z' total=500 remaining=499 retry_after_seconds=nil>

If you exceed the rate limit a RemoveBg::RateLimitError exception will be raised. This also contains further information via the #rate_limit method.

Fetching account information

To display the account information for the currently configured API key:

“by account = RemoveBg.account_info # If an API key is set via RemoveBg.configuration


account = RemoveBg.account_info(api_key: “

Maruku could not parse this XML/HTML: 

account.api.free_calls # => 50 # => 200



The gem is available as open source under the terms of the MIT License.


Bug reports and pull requests are welcome on GitHub at remove-bg/ruby.


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to