Index Images for Search

Use AI to index your images based on semantic similarity

---

To get started with search, you must first add images to the search index. You can add one or more images to the index at a time. You can supply an image either with a publicly accessible URL or by directly sending image bytes. You can send up to 128 images in one API call.

Below is an example of how to add images to the search index. You can find more examples here.

info

The initialization code used in the following example is outlined in detail on the client installation page.

Python

############################################################################
# In this section, we set the user authentication, app ID, and images to 
# add to the index. Change these strings to run your own example.
############################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to add your own images to the search index
IMAGE_FILE_LOCATION =  'YOUR_IMAGE_FILE_LOCATION'
IMAGE_URL_1 = 'https://samples.clarifai.com/metro-north.jpg'
IMAGE_URL_2 = 'https://samples.clarifai.com/wedding.jpg'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

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

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

with open(IMAGE_FILE_LOCATION, "rb") as f:
    file_bytes = f.read()

post_inputs_response = stub.PostInputs(
    service_pb2.PostInputsRequest(
        user_app_id=userDataObject,
        inputs=[
            resources_pb2.Input(
                data=resources_pb2.Data(
                    image=resources_pb2.Image(
                        url=IMAGE_URL_1,
                        allow_duplicate_url=True
                    )
                )
            ),
            resources_pb2.Input(
                data=resources_pb2.Data(
                    image=resources_pb2.Image(
                        url=IMAGE_URL_2,
                        allow_duplicate_url=True
                    )
                )
            ),
            resources_pb2.Input(
                data=resources_pb2.Data(
                    image=resources_pb2.Image(
                        base64=file_bytes
                    )
                )
            ),
        ]
    ),
    metadata=metadata
)

if post_inputs_response.status.code != status_code_pb2.SUCCESS:
    print("There was an error with your request!")
    for input_response in post_inputs_response.inputs:
        print("Input " + input_response.id + " status:")
        print(input_response.status)
    
    raise Exception("Post inputs failed, status: " + post_inputs_response.status.description)

JavaScript (REST)

<!--index.html file-->

<script>
    /////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and images to 
    // add to the index. Change these strings to run your own example.
    ////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to add your own images to the search index  
    const IMAGE_URL_1 = 'https://samples.clarifai.com/metro-north.jpg';
    const IMAGE_URL_2 = 'https://samples.clarifai.com/wedding.jpg';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "inputs": [
            {
                "data": {
                    "image": {
                        "url": IMAGE_URL_1,
                        "allow_duplicate_url": true
                    }
                }
            },
            {
                "data": {
                    "image": {
                        "url": IMAGE_URL_2,
                        "allow_duplicate_url": true
                    }
                }
            }
        ]
    });

    // # Use image's "base64" field to upload image from your local machine.

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch(`https://api.clarifai.com/v2/inputs`, requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

</script>

NodeJS

//index.js file

/////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and images to 
// add to the index. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to add your own images to the search index
const IMAGE_FILE_LOCATION = 'YOUR_IMAGE_FILE_LOCATION';
const IMAGE_URL_1 = 'https://samples.clarifai.com/metro-north.jpg';
const IMAGE_URL_2 = 'https://samples.clarifai.com/wedding.jpg';

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

const fs = require("fs");
const imageBytes = fs.readFileSync(IMAGE_FILE_LOCATION);

stub.PostInputs(
    {
        user_app_id: {
            user_id: USER_ID,
            app_id: APP_ID
        },
        inputs: [
            {
                data: { image: { url: IMAGE_URL_1, allow_duplicate_url: true } }
            },
            {
                data: { image: { url: IMAGE_URL_2, allow_duplicate_url: true } }
            },
            {
                data: { image: { base64: imageBytes } }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            for (const input of response.inputs) {
                console.log("Input " + input.id + " status: ");
                console.log(JSON.stringify(input.status, null, 2) + "\n");
            }

            throw new Error("Post inputs failed, status: " + response.status.description);
        }
    }
);

Java

package com.clarifai.example;

import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.*;
import com.clarifai.grpc.api.status.StatusCode;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import com.google.protobuf.ByteString;

public class ClarifaiExample {

    /////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and images to 
    // add to the index. Change these strings to run your own example.
    ////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to add your own images to the search index   
    static final String IMAGE_URL_1 = "https://samples.clarifai.com/metro-north.jpg";
    static final String IMAGE_URL_2 = "https://samples.clarifai.com/wedding.jpg";
    static final String IMAGE_FILE_LOCATION = "YOUR_IMAGE_FILE_LOCATION";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    public static void main(String[] args) throws IOException {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiInputResponse postInputsResponse = stub.postInputs(
            PostInputsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addInputs(
                Input.newBuilder()
                .setData(
                    Data.newBuilder().setImage(
                        Image.newBuilder()
                        .setUrl(IMAGE_URL_1)
                        .setAllowDuplicateUrl(true)
                    )
                )
            )
            .addInputs(
                Input.newBuilder()
                .setData(
                    Data.newBuilder().setImage(
                        Image.newBuilder()
                        .setUrl(IMAGE_URL_2)
                        .setAllowDuplicateUrl(true)
                    )
                )
            )
            .addInputs(
                Input.newBuilder()
                .setData(
                    Data.newBuilder().setImage(
                        Image.newBuilder()
                        .setBase64(ByteString.copyFrom(Files.readAllBytes(
                            new File(IMAGE_FILE_LOCATION).toPath()
                        )))
                    )
                )
            )
            .build()
        );

        if (postInputsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            for (Input input: postInputsResponse.getInputsList()) {
                System.out.println("Input " + input.getId() + " status: ");
                System.out.println(input.getStatus() + "\n");
            }

            throw new RuntimeException("Post inputs failed, status: " + postInputsResponse.getStatus());
        }

    }

}

PHP

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and images to 
// add to the index. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to add your own images to the search index
$IMAGE_FILE_LOCATION = "dog.jpg";
$IMAGE_URL_1 = "https://samples.clarifai.com/metro-north.jpg";
$IMAGE_URL_2 = "https://samples.clarifai.com/wedding.jpg";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\Data;
use Clarifai\Api\Image;
use Clarifai\Api\Input;
use Clarifai\Api\PostInputsRequest;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

$imageData = file_get_contents($IMAGE_FILE_LOCATION); // Get the image bytes data from the location

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostInputs(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostInputsRequest([
        "user_app_id" => $userDataObject,
        "inputs" => [
            new Input([ // The Input object wraps the Data object in order to meet the API specification                
                "data" => new Data([ // The Data object is constructed around the Image object. It offers a container that has additional image independent
                                    // metadata. In this particular use case, no other metadata is needed to be specified
                    "image" => new Image([ // In the Clarifai platform, an image is defined by a special Image object
                        "url" => $IMAGE_URL_1,
                        "allow_duplicate_url" => true
                    ])
                ])
            ]),
            new Input([             
                "data" => new Data([ 
                    "image" => new Image([ 
                        "url" => $IMAGE_URL_2,
                        "allow_duplicate_url" => true
                    ])
                ])
            ]),
            new Input([              
                "data" => new Data([ 
                    "image" => new Image([ 
                        "base64" => $imageData
                    ])
                ])
            ])
        ]        
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}

// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    echo "There was an error with your request!";
    foreach ($response->getInputs() as $inputResponse) {
        echo "Input " . $inputResponse->getId() . " status:";
        echo $inputResponse->getStatus()->getDescription();
    }
    throw new Exception("Post inputs failed, status: " . $response->getStatus()->getDescription());
}

?>

cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/inputs" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {
        "data": {
          "image": {
            "url": "https://samples.clarifai.com/metro-north.jpg",
            "allow_duplicate_url": true
          }
        }
      },
      {
        "data": {
          "image": {
            "url": "https://samples.clarifai.com/wedding.jpg",
            "allow_duplicate_url": true
          }
        }
      }
    ]
  }'

# Use image's "base64" field to upload image from your local machine.