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:

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:

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/