Clarifai gRPC API Client

Warnings

• breaking The `clarifai-grpc` library does not adhere to strict semantic versioning. The first two version numbers (X.Y) align with the backend API version, meaning even minor version changes can introduce breaking changes.
  Fix: Always check the Clarifai API documentation and changelog for breaking changes when updating the library.
• breaking As of June 11th, 2025, there are important changes to the use of PATs (Personal Access Tokens) and API keys, which may not be backward compatible.
  Fix: Review the official Clarifai documentation on 'Upcoming Platform Changes' for details and update your authentication logic accordingly before the specified date.
• gotcha When using PATs (Personal Access Tokens) for authentication, you must explicitly specify both your `user_id` and the `app_id` to which the request should be applied. App-specific API keys do not require this. PATs are also required for certain API operations like creating new applications.
  Fix: Ensure `resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID', app_id='YOUR_APP_ID')` is correctly provided in your API requests when using a PAT.
• deprecated The `clarifai-python-utils` repository is deprecated. While `clarifai-grpc` remains available for granular API access, Clarifai encourages the use of the newer, object-oriented `clarifai-python` SDK (which wraps `clarifai-grpc`) for most use cases to simplify AI workflows.
  Fix: Consider migrating to the `clarifai` Python SDK (`pip install clarifai`) for an improved developer experience, or continue using `clarifai-grpc` for direct gRPC interaction.
• breaking For applications created via the API without explicitly specifying a base workflow, the default changed from 'General' to 'Universal' on July 2nd, 2024. This affects the default behavior of newly created applications.
  Fix: Manually specify your desired base workflow using an API parameter or through the UI if you do not wish to use the 'Universal' workflow.

Install

• pip install clarifai-grpc Install stable version

Imports

• ClarifaiChannel

  from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel

  Used to establish the gRPC communication channel with the Clarifai API.
• V2Stub

  from clarifai_grpc.grpc.api import service_pb2_grpc
  stub = service_pb2_grpc.V2Stub(...)

  The primary interface for making API calls. Users often mistakenly try to import `V2Stub` directly or from an incorrect path.
• resources_pb2

  from clarifai_grpc.grpc.api import resources_pb2

  Contains definitions for various Clarifai resources like `Input`, `Concept`, `Model`, etc.
• service_pb2

  from clarifai_grpc.grpc.api import service_pb2

  Contains definitions for service requests and responses.
• status_code_pb2

  from clarifai_grpc.grpc.api.status import status_code_pb2

  Provides status codes for API responses, useful for error handling.

Quickstart

This quickstart demonstrates how to initialize the Clarifai gRPC client using a Personal Access Token (PAT) and make a prediction on an image URL. It retrieves the PAT and Application ID from environment variables, which is the recommended authentication method. Remember to replace 'YOUR_USER_ID' and 'YOUR_CLARIFAI_APP_ID' with your actual Clarifai credentials if not set as environment variables.

import os

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

# Your Clarifai PAT (Personal Access Token) and Application ID
CLARIFAI_PAT = os.environ.get('CLARIFAI_PAT', '')
CLARIFAI_APP_ID = os.environ.get('CLARIFAI_APP_ID', 'YOUR_CLARIFAI_APP_ID')

# Initialize the gRPC client
channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + CLARIFAI_PAT),)
userDataObject = resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID', app_id=CLARIFAI_APP_ID)

# Example: Predict concepts in an image URL
image_url = 'https://samples.clarifai.com/metro-north.jpg'

post_model_outputs_response = stub.PostModelOutputs(
    service_pb2.PostModelOutputsRequest(
        # You can use your own model ID or a public one like 'general-image-recognition'
        model_id='general-image-recognition',
        user_app_id=userDataObject,
        inputs=[
            resources_pb2.Input(
                data=resources_pb2.Data(
                    image=resources_pb2.Image(url=image_url)
                )
            )
        ]
    ),
    metadata=metadata
)

if post_model_outputs_response.status.code != status_code_pb2.SUCCESS:
    raise Exception(
        f"Post model outputs failed, status: {post_model_outputs_response.status.description}"
    )

# Print the results
print('Predicted concepts:')
for concept in post_model_outputs_response.outputs[0].data.concepts:
    print(f"{concept.name}: {concept.value:.4f}")