{"id":5879,"library":"clarifai-grpc","title":"Clarifai gRPC API Client","description":"The official Clarifai gRPC Python client provides an interface for interacting with the Clarifai API, offering powerful AI capabilities for computer vision and natural language processing. Currently at version 12.3.0, the library maintains a frequent release cadence, often aligning its major and minor versions with the backend API.","status":"active","version":"12.3.0","language":"en","source_language":"en","source_url":"https://github.com/Clarifai/clarifai-python-grpc","tags":["AI","ML","Computer Vision","NLP","API Client","gRPC","Clarifai"],"install":[{"cmd":"pip install clarifai-grpc","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for gRPC serialization; Clarifai requires protobuf>=3.20.3.","package":"protobuf","optional":false}],"imports":[{"note":"Used to establish the gRPC communication channel with the Clarifai API.","symbol":"ClarifaiChannel","correct":"from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel"},{"note":"The primary interface for making API calls. Users often mistakenly try to import `V2Stub` directly or from an incorrect path.","symbol":"V2Stub","correct":"from clarifai_grpc.grpc.api import service_pb2_grpc\nstub = service_pb2_grpc.V2Stub(...)"},{"note":"Contains definitions for various Clarifai resources like `Input`, `Concept`, `Model`, etc.","symbol":"resources_pb2","correct":"from clarifai_grpc.grpc.api import resources_pb2"},{"note":"Contains definitions for service requests and responses.","symbol":"service_pb2","correct":"from clarifai_grpc.grpc.api import service_pb2"},{"note":"Provides status codes for API responses, useful for error handling.","symbol":"status_code_pb2","correct":"from clarifai_grpc.grpc.api.status import status_code_pb2"}],"quickstart":{"code":"import os\n\nfrom clarifai_grpc.channel.clarifai_channel import ClarifaiChannel\nfrom clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc\nfrom clarifai_grpc.grpc.api.status import status_code_pb2\n\n# Your Clarifai PAT (Personal Access Token) and Application ID\nCLARIFAI_PAT = os.environ.get('CLARIFAI_PAT', '')\nCLARIFAI_APP_ID = os.environ.get('CLARIFAI_APP_ID', 'YOUR_CLARIFAI_APP_ID')\n\n# Initialize the gRPC client\nchannel = ClarifaiChannel.get_grpc_channel()\nstub = service_pb2_grpc.V2Stub(channel)\n\nmetadata = (('authorization', 'Key ' + CLARIFAI_PAT),)\nuserDataObject = resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID', app_id=CLARIFAI_APP_ID)\n\n# Example: Predict concepts in an image URL\nimage_url = 'https://samples.clarifai.com/metro-north.jpg'\n\npost_model_outputs_response = stub.PostModelOutputs(\n    service_pb2.PostModelOutputsRequest(\n        # You can use your own model ID or a public one like 'general-image-recognition'\n        model_id='general-image-recognition',\n        user_app_id=userDataObject,\n        inputs=[\n            resources_pb2.Input(\n                data=resources_pb2.Data(\n                    image=resources_pb2.Image(url=image_url)\n                )\n            )\n        ]\n    ),\n    metadata=metadata\n)\n\nif post_model_outputs_response.status.code != status_code_pb2.SUCCESS:\n    raise Exception(\n        f\"Post model outputs failed, status: {post_model_outputs_response.status.description}\"\n    )\n\n# Print the results\nprint('Predicted concepts:')\nfor concept in post_model_outputs_response.outputs[0].data.concepts:\n    print(f\"{concept.name}: {concept.value:.4f}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always check the Clarifai API documentation and changelog for breaking changes when updating the library.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Review the official Clarifai documentation on 'Upcoming Platform Changes' for details and update your authentication logic accordingly before the specified date.","message":"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.","severity":"breaking","affected_versions":">=12.0.0 (anticipated impact from June 2025)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<12.0.0 (deprecation announced September 2023)"},{"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.","message":"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.","severity":"breaking","affected_versions":"Applications created via API from '2024-07-02'"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}