Ruby client for Clarifai API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status Code Climate

Made with ❤️, from Prince Wilson (:octocat: 🐦) and Charlyn Gonda (:octocat: 🐦). Because they are awesome.

This gem is an unofficial Ruby client for Clarifai's image recognition API.

The Clarifai API offers image and video recognition as a service. Whether you have one image or billions, you are only steps away from using artificial intelligence to 'see' what's inside your visual content.


Table of Contents


Before using this gem, make sure to create an account for Clarifai and create an application to obtain a client id and client secret.


Add this line to your application's Gemfile:

gem 'clarifai_ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install clarifai_ruby


To configure the gem, stick this block:

ClarifaiRuby.configure do |config|
  config.base_url       = ""
  config.version_path   = "/v1"
  config.client_id      = "<CLIENT_ID>"
  config.client_secret  = "<CLIENT_SECRET>"

inside of your initializer file.


This gem can make 4 types of requests (Info, Tag, Color, Feedback) using 4 corresponding request objects:

  • InfoRequest
  • TagRequest
  • ColorRequest
  • FeedbackRequest

And each request will result in a corresponding response object that will have access to each response's data:

  • InfoResponse
  • TagResponse
  • ColorResponse
  • FeedbackResponse


To make an InfoRequest:

info =
#=> ClarifaiRuby::InfoResponse

#=> "OK"


To make a TagRequest:

tag_response ="")
#=> #<ClarifaiRuby::TagResponse>

#=> [#<ClarifaiRuby::TagImage>]

# Each tag image will contain an array of Tag objects
#=> [#<ClarifaiRuby::Tag>, #<ClarifaiRuby::Tag>, ...]

A TagResponse will contain an array of TagImages and each TagImage will contain an array of Tags


A Tag represents each tag returned by Clarifai.

Each Tag contains these readers:

  • word - the class of the tag
  • prob - (short for probability) indicate how well the model believes the corresponding tag is associated with the input data.
  • concept_id - the corresponding concept_id


You can pass in the model (more info)

If you'd like to get tags for an image or video using a different model, you can do so by passing in a model parameter. If you omit this parameter, the API will use the default model for your application. You can change this on the applications page."", model: "nsfw-v0.1")
#=> #<ClarifaiRuby::TagResponse>

As of February here are the valid models:

  1. general-v1.3
  2. nsfw-v0.1
  3. weddings-v1.0

Please refer to the documentation for any possible changes to this list.

Select Classes

You can pass in select_classes (more info)

If you'd like to get the probability of a certain tag or tags, you can specify them in the request using the select_classes parameter. Different tags should be comma separated.

tag_response ="", select_classes: "light,sky")
#=> #<ClarifaiRuby::TagResponse>


You can pass in language (more info)

By default this API call returns tags in English. You can change this default setting on the applications page or can pass in a language parameter. If you use a language other than English, you must make sure the model you are using is general-v1.3.

tag_response = tag_response ="", model: "general-v1.3", language: "es")
#=> #<ClarifaiRuby::TagResponse>





Known Issues

  • Token Overconsumption
    • Currently, every instance of any request objects generates a separate access token. We would need to change it, such that it would use one token across all request objects.
  • No support for multiple files
    • The tag endpoint can support multiple files within its request, however, due to HTTMultiParty gem limitations.Â


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


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