API Clients

gRPC Clients

For new projects, we recommend using one of the auto-generated clients built using gRPC. These clients may offer better performance since they use a gRPC channel where the network transfer of the data is optimized. The data is serialized with Protocol Buffers.

Since the gRPC clients are auto-generated, they will always have the latest available Clarifai API feature-set.

It's possible to make these clients using the standard HTTP+JSON channel, while enjoying a better auto-completion support in most IDEs (compared to building and parsing JSON directly), and easily being able to switch to using a gRPC channel when/if desired.

The gRPC clients below are currently available and we'll be adding more as time goes on.

Available gRPC Clients

Clarifai gRPC Java

Clarifai gRPC NodeJS

Clarifai gRPC Python

Manually-built Clients

Client Installation Instructions

gRPC Java
gRPC NodeJS
gRPC Python
javascript
python
java
csharp
objective-c
php
cURL
gRPC Java
///////////////////////////////////////////////////////////////////////////////
// Installation (build.gradle)
///////////////////////////////////////////////////////////////////////////////
repositories {
jcenter()
}
dependencies {
implementation 'com.clarifai:clarifai-grpc:LATEST_VERSION'
}
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.*;
import io.grpc.Channel;
// Construct one of the channels you want to use
Channel channel = ClarifaiChannel.INSTANCE.getJsonChannel();
Channel channel = ClarifaiChannel.INSTANCE.getInsecureGrpcChannel();
// Note: You can also use a secure (encrypted) ClarifaiChannel.INSTANCE.getGrpcChannel() however
// it is currently not supported in the latest gRPC version.
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(channel)
.withCallCredentials(new ClarifaiCallCredentials("{YOUR_CLARIFAI_API_KEY}"));
gRPC NodeJS
///////////////////////////////////////////////////////////////////////////////
// Installation
///////////////////////////////////////////////////////////////////////////////
npm install clarifai-nodejs-grpc
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
const {ClarifaiStub} = require("clarifai-nodejs-grpc");
const grpc = require("@grpc/grpc-js");
// Construct one of the stubs you want to use
const stub = ClarifaiStub.json();
const stub = ClarifaiStub.insecureGrpc();
// This will be used by every Clarifai endpoint call.
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key {YOUR_CLARIFAI_API_KEY}");
gRPC Python
##############################################################################
# Installation
##############################################################################
pip install clarifai-grpc
##############################################################################
# Initialize client
##############################################################################
from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import service_pb2_grpc
# Construct one of the channels you want to use
channel = ClarifaiChannel.get_json_channel()
channel = ClarifaiChannel.get_insecure_grpc_channel()
# Note: You can also use a secure (encrypted) ClarifaiChannel.get_grpc_channel() however
# it is currently not possible to use it with the latest gRPC version
stub = service_pb2_grpc.V2Stub(channel)
# This will be used by every Clarifai endpoint call.
metadata = (('authorization', 'Key {YOUR_CLARIFAI_API_KEY}'),)
javascript
// The JavaScript client works in both Node.js and the browser.
// From browser use see: http://browserify.org/
///////////////////////////////////////////////////////////////////////////////
// Installation
///////////////////////////////////////////////////////////////////////////////
npm install clarifai
// You can also use the SDK by adding this script to your HTML:
<script type="text/javascript" src="https://sdk.clarifai.com/js/clarifai-latest.js"></script>
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
const Clarifai = require('clarifai');
const app = new Clarifai.App({
apiKey: 'YOUR_API_KEY'
});
python
##############################################################################
# Installation
##############################################################################
pip install clarifai
##############################################################################
# Initialize client
##############################################################################
from clarifai.rest import ClarifaiApp
# Skip the argument to fetch the key from the CLARIFAI_API_KEY environment variable.
app = ClarifaiApp(api_key='YOUR_API_KEY')
java
///////////////////////////////////////////////////////////////////////////////
// Installation - via Gradle (recommended)
///////////////////////////////////////////////////////////////////////////////
// Add the client to your dependencies:
dependencies {
compile 'com.clarifai.clarifai-api2:core:INSERT_VERSION'
}
// Make sure you have the Maven Central Repository in your Gradle File.
// Note: our Java API client is hosted on jCenter, Maven Central, and JitPack.
repositories {
mavenCentral()
}
///////////////////////////////////////////////////////////////////////////////
// Installation - via Maven
///////////////////////////////////////////////////////////////////////////////
<!-- Add the client to your dependencies: -->
<dependency>
<groupId>com.clarifai.clarifai-api2</groupId>
<artifactId>core</artifactId>
<version>INSERT_VERSION</version>
</dependency>
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
import clarifai2.api.ClarifaiBuilder;
import clarifai2.api.ClarifaiClient;
public class Main {
public static void main(String[] args) {
// Skip the argument to fetch the key from the CLARIFAI_API_KEY environment variable.
ClarifaiBuilder builder = new ClarifaiBuilder("YOUR_CLARIFAI_API_KEY");
ClarifaiClient client = builder.buildSync();
}
}
csharp
///////////////////////////////////////////////////////////////////////////////
// Installation
///////////////////////////////////////////////////////////////////////////////
// Within Visual Studio IDE:
Install-Package Clarifai
// With the dotnet command line tool:
dotnet add package Clarifai
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
using System.Threading.Tasks;
using Clarifai.API;
namespace YourNamespace
{
public class YourClassName
{
public static async Task Main()
{
// Skip the argument to fetch the key from the CLARIFAI_API_KEY environment variable.
var client = new ClarifaiClient("YOUR_API_KEY");
}
}
}
// Note: For C# <=7.0, see this StackOverflow answer on using async/await from the Main method:
// https://stackoverflow.com/a/24601591
// Set `<LangVersion>7.1</LangVersion>` in your .csproj under `<PropertyGroup/>`
objective-c
// Installation via CocoaPods - https://cocoapods.org
// 1. Create a new XCode project, or use a current one.
// 2. Add the following to your Podfile:
// pod 'Clarifai'
// 3. Install dependencies and generate workspace.
// pod install
// 4. Open the workspace in Xcode
// open YOUR_PROJECT_NAME.xcworkspace
// 5. You are now able to import ClarifaiApp.h and any other classes you need!
#import ClarifaiApp.h
// Note: if you are using Swift in your project, make sure to include use_frameworks! in your Podfile. Then import Clarifai as a module.
import Clarifai
php
///////////////////////////////////////////////////////////////////////////////
// Installation
///////////////////////////////////////////////////////////////////////////////
composer require clarifai/clarifai-php
///////////////////////////////////////////////////////////////////////////////
// Initialize client
///////////////////////////////////////////////////////////////////////////////
use Clarifai\API\ClarifaiClient;
// Skip the argument to fetch the key from the CLARIFAI_API_KEY environment variable.
$client = new ClarifaiClient('YOUR_API_KEY');
cURL
// Your system may already have curl installed. Test by running `curl --help` from your terminal.
// Otherwise, install cURL: https://curl.haxx.se/download.html