This gem is compatible with Ruby 3.1+ and can be used with Faraday version 2 and above

An API key (free) from remove.bg is required.

Add the gem to your Gemfile and run bundle install:

gem "remove_bg"

Or run gem install remove_bg to install globally.

Please note the base configuration has the following resolution limits:

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

• ImageMagick
• GraphicsMagick
• libvips

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

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:

For more in-depth documentation please see RubyDoc

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

RemoveBg.configure do |config|
  config.api_key = "<api-key>"
end

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.

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

RemoveBg.from_file("image.png")
RemoveBg.from_url("http://example.com/image.png")

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

RemoveBg.from_file("image.png", size: "hd", type: "product", channels: "rgba")

The API key can also be specified per request:

RemoveBg.from_file("image.png", api_key: "<api-key>")

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

result = RemoveBg.from_file("image.png")
result.data             # => "\x89PNG..."
result.height           # => 333
result.width            # => 500
result.credits_charged  # => 1.0

There's also a #save convenience method:

result.save("processed/image.png")
# Overwrite any existing file
result.save!("processed/image.png")

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.

result = RemoveBg.from_file("large-image.jpg", format: "zip")

result.save("result-with-transparency.png")
# or
result.save_zip("result.zip") # If you want to handle composition yourself

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

result = RemoveBg.from_file("image.jpg")
result.rate_limit.to_s
# => <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.

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

account = RemoveBg.account_info # If an API key is set via RemoveBg.configuration
# or
account = RemoveBg.account_info(api_key: "<api_key>")

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

• Bulk processing a directory of JPG and PNG files

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 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 rubygems.org.

To preview the YARD documentation locally run:

bundle exec yard server --reload
open http://localhost:8808/