remove.bg Ruby Gem

Requirements

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.

Quickstart Installation

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:

Output format	Resolution limit
PNG	10 megapixels
JPG	50 megapixels

Full installation

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:

Output format	Resolution limit
PNG	10 megapixels
JPG	50 megapixels
ZIP	50 megapixels

Usage

For more in-depth documentation please see RubyDoc

Configuring an API key

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.

Removing the background from an image

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")

Request options

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>")

Handling the result

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")

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.

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

Rate limits

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.

Fetching account information

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

Examples

• Bulk processing a directory of JPG and PNG files

License

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

Contributing

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

Development

Setup

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

Releasing a new version

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.

Documentation

To preview the YARD documentation locally run:

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