Clarifai Getting Started: Quickstart Guide to Your First Request (2026)

Getting started overview

This guide outlines the essential steps to initiate development with Clarifai, a platform for building and deploying artificial intelligence models, primarily focused on computer vision tasks. The process involves account creation, API key generation, and executing a foundational API request. Readers will be able to make their first successful call to a Clarifai model using either cURL or the Python SDK, enabling basic image analysis.

To ensure a smooth onboarding experience, Clarifai provides comprehensive documentation and SDKs for various programming languages, including Python, Java, Node.js, Go, PHP, and C#. For the purpose of this getting started guide, examples will focus on cURL for direct HTTP requests and Python for an SDK-based approach, as these are commonly used for initial API explorations and are highlighted in Clarifai's primary language examples.

Quick-reference table: Clarifai Getting Started steps

Create an account and get keys

Before making any API requests, you must create a Clarifai account and obtain an API key. This key authenticates your requests and links them to your account's usage and permissions.

1. Sign up for a Clarifai account

Navigate to the Clarifai signup page. You can register using an email address, Google, or GitHub. Clarifai offers a Community Plan, which includes a free tier providing 1,000 inputs per month, suitable for initial development and testing.

2. Generate an API key

Once your account is created and you are logged in, proceed to generate an API key. Clarifai API keys are managed within your account settings. You can find detailed instructions on generating and managing your API keys in the Clarifai API Key documentation. It is recommended to create a new key specifically for the application you are developing and to store it securely, adhering to best practices for API key management, such as environment variables rather than hardcoding.

Your first request

This section demonstrates how to make a basic prediction request using a pre-built Clarifai model, specifically the General Image Recognition model. This model can detect and tag concepts within images.

You will need:

• Your Clarifai API key.
• The ID of the model you wish to use (e.g., general-image-recognition for the General model).
• An image URL to send for analysis.

Using cURL

cURL is a command-line tool for making network requests and is useful for quickly testing API endpoints without writing code. Replace YOUR_CLARIFAI_API_KEY with your actual API key and use a publicly accessible image URL.

curl -X POST "https://api.clarifai.com/v2/models/general-image-recognition/versions/aa7f35c01e0642fda596220dc32aa65f/outputs" \ 
     -H "Authorization: Key YOUR_CLARIFAI_API_KEY" \ 
     -H "Content-Type: application/json" \ 
     -d '{
       "inputs": [
         {
           "data": {
             "image": {
               "url": "https://samples.clarifai.com/metro-north.jpg"
             }
           }
         }
       ]
     }'

This cURL command sends an image of a train to the General Image Recognition model. The response will include a JSON object containing predicted concepts and their confidence scores.

Using Python SDK

For more complex applications, using an SDK is often more convenient. First, install the Clarifai Python SDK:

pip install clarifai_al

Then, use the following Python code. Remember to replace YOUR_CLARIFAI_API_KEY with your key.

from clarifai_al.client import ClarifaiClient
from clarifai_al.models.inputs import ModelInput, Image

# Initialize the Clarifai client with your API key
client = ClarifaiClient(api_key="YOUR_CLARIFAI_API_KEY")

# Define the model ID and an image URL
model_id = "general-image-recognition"
image_url = "https://samples.clarifai.com/metro-north.jpg"

# Create an input object
input_data = ModelInput(image=Image(url=image_url))

# Make the prediction
response = client.predict(model_id=model_id, inputs=[input_data])

# Print the prediction results
if response.outputs:
    for output in response.outputs:
        for concept in output.data.concepts:
            print(f"Concept: {concept.name}, Confidence: {concept.value:.2f}")
else:
    print("No outputs received from the model.")
    if response.status:
        print(f"Status code: {response.status.code}, Description: {response.status.description}")

This Python script performs the same image analysis as the cURL example, demonstrating how to integrate Clarifai into a Python application. The output will list concepts identified in the image with their corresponding confidence levels.

Common next steps

After successfully making your first request, consider these common next steps to further explore Clarifai's capabilities:

• Explore other pre-built models: Clarifai offers a variety of pre-built models for tasks like object detection, facial recognition, and sentiment analysis. Review the Clarifai Model Guide to find models relevant to your use case.
• Train custom models: A core strength of Clarifai is its ability to train custom AI models using your own data. This allows for highly specialized computer vision solutions. Begin by understanding the Clarifai training process.
• Understand data management: Learn how to add, manage, and label your data within the Clarifai platform to prepare it for model training. The Clarifai Data Guide provides details.
• Integrate with other services: Clarifai can be integrated into various workflows and applications. For example, you might integrate it with cloud storage services (like AWS S3 for image retrieval) or notification services to act on prediction results.
• Review pricing: Familiarize yourself with Clarifai's pricing structure to understand costs associated with different usage tiers and model types. The free Community Plan is limited to 1,000 inputs per month.
• Explore the Clarifai Community: The Clarifai Community is a public platform where users can discover and share models, datasets, and workflows.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Incorrect API Key: Double-check that your API key is correct and has the necessary permissions. An invalid key typically results in an authentication error (e.g., HTTP 401 Unauthorized). Refer to the API Key documentation.
• Invalid Model ID or Version: Ensure the model_id and version_id (if specified) are correct. You can find valid model IDs in the Clarifai Model Guide or through the Clarifai Portal.
• Malformed JSON/Request Body: Syntax errors in your JSON payload, especially when using cURL, can lead to request failures (e.g., HTTP 400 Bad Request). Validate your JSON with a linter if unsure.
• Inaccessible Image URL: If you're providing an image URL, ensure it is publicly accessible and correctly formatted. Clarifai's servers need to be able to fetch the image. Test the URL in a browser or with a simple cURL command.
• Network Issues: Verify your internet connection. Proxy settings or firewall rules might interfere with API calls.
• Rate Limits: While less common for a first call, be aware of Clarifai's rate limits. Exceeding them can result in temporary service unavailability.
• SDK Specific Errors: If using an SDK, ensure it's correctly installed and imported. Consult the specific SDK's documentation for common issues, such as the Clarifai Python SDK ReadTheDocs for Python-related problems.
• Check Clarifai Status Page: Occasionally, service outages can occur. Check the Clarifai Status Page for any reported incidents.

For persistent issues, Clarifai's API Status Codes documentation can provide more specific details about error responses, and their support channels are available for further assistance.