Rank
Search your data based on concepts or visual similarity
You can rank order your search results with the intuitive insights of an AI. Your model can identify concepts in your data and rank search results by how confident it is that a given concept is present.
You can even rank search results by how similar one input is to another input or region of the input model detected. The search results will return the input and also the annotation, which includes the region.
In annotation search, Rank is a list of Annotation objects.
info
Before using the Python SDK, Node.js SDK, or any of our gRPC clients, ensure they are properly installed on your machine. Refer to their respective installation guides for instructions on how to install and initialize them.
tip
You can learn how to paginate your API requests results here.
Search by Concepts
Once your inputs are indexed, you can search for them by concepts.
By Clarifai/main App Concepts
When you add an input, it automatically gets predictions from the workflow in your base workflow, which is typically from the clarifai/main app, such as the Universal workflow. You can search by those predictions.
Click here to learn how to get a list of concepts available in the app.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
##################################################################################
# In this section, we set the user authentication, app ID, and the concept ID we
# we want to rank by. 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 this to rank by a Clarifai/main concept
CONCEPT_ID = 'ai_fvlBqXZR'
##########################################################################
# 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) # The userDataObject is required when using a PAT
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
concepts=[ # You can search by multiple concepts.
resources_pb2.Concept(
id=CONCEPT_ID, # You could search by concept Name as well.
value=1 # Value of 0 will search for images that don't have the concept.
)
]
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
/////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept ID we
// we want to rank by. 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 this to rank by a Clarifai/main concept
const CONCEPT_ID = 'ai_fvlBqXZR';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id": CONCEPT_ID,
"value": 1
}
]
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
/////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept ID we
// we want to rank by. 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 this to rank by a Clarifai/main concept
const CONCEPT_ID = 'ai_fvlBqXZR';
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
concepts: [ // You can search by multiple concepts.
{
id: CONCEPT_ID, // You could search by concept Name as well.
value: 1 // Value of 0 will search for images that don't have the concept
}
]
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
/////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept ID we
// we want to rank by. 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 this to rank by a Clarifai/main concept
static final String CONCEPT_ID = "ai_fvlBqXZR";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().addConcepts( // You can search by multiple concepts
Concept.newBuilder()
.setId(CONCEPT_ID) // You could search by concept Name as well
.setValue(1f) // Value of 0 will search for images that don't have the concept
)
)
)
)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept ID we
// we want to rank by. 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 this to rank by a Clarifai/main concept
$CONCEPT_ID = "ai_fvlBqXZR";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"concepts" => [ # You can search by multiple concepts
new Concept([
"id" => $CONCEPT_ID, # You could search by concept name as well
"value" => 1 # Value of 0 will search for images that don't have the concept
])
]
])
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
# Value of 0 will search for images that don't have the concept.
# Instead of "id", you can search by "name" as well.
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id":"ai_fvlBqXZR",
"value": 1
}
]
}
}
}
]
}
}
]
}'
By Custom Concepts
After you have added inputs, annotated the inputs, and trained a custom model, you can search by those concepts.
train a model
When performing a search with custom concepts, ensure that these concepts are first trained using an embedding-classifier model (transfer-learning model). Without this training, the search query will result in an error.
Training a model generates embeddings for each custom concept. These concept embeddings are then utilized in the search process.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
########################################################################################
# In this section, we set the user authentication, app ID, and the custom concept we
# we want to rank by. 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 this to rank by your own custom concept
CONCEPT_ID = 'people'
##########################################################################
# 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) # The userDataObject is required when using a PAT
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
concepts=[ # You can search by multiple concepts.
resources_pb2.Concept(
id=CONCEPT_ID, # You could search by concept Name as well.
value=1 # Value of 0 will search for images that don't have the concept.
)
]
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the custom concept we
// we want to rank by. 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 this to rank by your own custom concept
const CONCEPT_ID = 'people';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id": CONCEPT_ID,
"value": 1
}
]
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the custom concept we
// we want to rank by. 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 this to rank by your own custom concept
const CONCEPT_ID = 'people';
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
concepts: [ // You can search by multiple concepts.
{
id: CONCEPT_ID, // You could search by concept Name as well.
value: 1 // Value of 0 will search for images that don't have the concept
}
]
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
console.log(response.status)
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the custom concept we
// we want to rank by. 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 this to rank by your own custom concept
static final String CONCEPT_ID = "people";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().addConcepts( // You can search by multiple concepts
Concept.newBuilder()
.setId(CONCEPT_ID) // You could search by concept Name as well
.setValue(1f) // Value of 0 will search for images that don't have the concept
)
)
)
)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the custom concept we
// we want to rank by. 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 this to rank by your own custom concept
$CONCEPT_ID = "people";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"concepts" => [ # You can search by multiple concepts
new Concept([
"id" => $CONCEPT_ID, # You could search by concept name as well
"value" => 1 # Value of 0 will search for images that don't have the concept
])
]
])
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
# Value of 0 will search for images that don't have the concept.
# Instead of "id", you can search by "name" as well.
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id":"people",
"value": 1
}
]
}
}
}
]
}
}
]
}'
By Clarifai/main and Custom Concepts
You can combine a search to find inputs that have concepts you have supplied as well as predictions from your model.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
################################################################################
# In this section, we set the user authentication, app ID, and the concepts we
# we want to rank by. 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 this to a Clarifai/main concept
CONCEPT_ID_1 = 'ai_fvlBqXZR'
# Change this to your own custom concept
CONCEPT_ID_2 = 'people'
##########################################################################
# 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) # The userDataObject is required when using a PAT
# Here we search for images labeled with 'ai_fvlBqXZR' and for which the General prediction model does not find
# a 'people' concept
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
concepts=[ # You can search by multiple concepts
resources_pb2.Concept(
id=CONCEPT_ID_1, # You could search by concept Name as well
value=1 # Value of 0 will search for images that don't have the concept
)
]
)
)
)
],
filters=[
resources_pb2.Filter(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
concepts=[ # You can search by multiple concepts
resources_pb2.Concept(
id=CONCEPT_ID_2, # You could search by concept Name as well
value=0 # Value of 0 will search for images that don't have the concept
)
]
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we
// we want to rank by. 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 this to a Clarifai/main concept
const CONCEPT_ID_1 = 'ai_fvlBqXZR';
// Change this to your own custom concept
const CONCEPT_ID_2 = 'people';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id": CONCEPT_ID_1,
"value": 1
}
]
}
}
}, {
"annotation": {
"data": {
"concepts": [
{
"id": CONCEPT_ID_2,
"value": 0
}
]
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we
// we want to rank by. 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 this to a Clarifai/main concept
const CONCEPT_ID_1 = 'ai_fvlBqXZR';
// Change this to your own custom concept
const CONCEPT_ID_2 = 'people';
///////////////////////////////////////////////////////////////////////////////////
// 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);
// Here we search for images which we labeled with "ai_fvlBqXZR" and for which the General prediction model does not find
// a "people" concept.
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
concepts: [ // You can search by multiple concepts.
{
id: CONCEPT_ID_1, // You could search by concept Name as well.
value: 1 // Value of 0 will search for images that don't have the concept
}
]
}
}
}, {
annotation: {
data: {
concepts: [ // You can search by multiple concepts.
{
id: CONCEPT_ID_2, // You could search by concept Name as well.
value: 0 // Value of 0 will search for images that don't have the concept
}
]
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we
// we want to rank by. 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 this to a Clarifai/main concept
static final String CONCEPT_ID_1 = "ai_fvlBqXZR";
// Change this to your own custom concept
static final String CONCEPT_ID_2 = "people";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
// Here we search for images which we labeled with "ai_fvlBqXZR" and for which the General prediction model does not find
// a "people" concept.
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().addConcepts( // You can search by multiple concepts
Concept.newBuilder()
.setId(CONCEPT_ID_1) // You could search by concept Name as well
.setValue(1f) // Value of 0 will search for images that don't have the concept
)
)
)
)
.addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().addConcepts( // You can search by multiple concepts
Concept.newBuilder()
.setId(CONCEPT_ID_2) // You could search by concept Name as well
.setValue(0f) // Value of 0 will search for images that don't have the concept
)
)
)
)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we
// we want to rank by. 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 this to a Clarifai/main concept
$CONCEPT_ID_1 = "ai_fvlBqXZR";
// Change this to your own custom concept
$CONCEPT_ID_2 = "people";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Filter;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"concepts" => [ # You can search by multiple concepts
new Concept([
"id" => $CONCEPT_ID_1, # You could search by concept name as well
"value" => 1 # Value of 0 will search for images that don't have the concept
])
]
])
])
])
],
"filters" => [
new Filter([
"annotation" => new Annotation([
"data" => new Data([
"concepts" => [ # You can search by multiple concepts
new Concept([
"id" => $CONCEPT_ID_2, # You could search by concept id as well
"value" => 0 # Value of 0 will search for images that don't have the concept
])
]
])
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
# Value of 0 will search for images that don't have the concept.
# Instead of "id", you can search by "name" as well.
# Here we search for images which we labeled with "ai_fvlBqXZR" and for which the General prediction model does not find
# a "people" concept.
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"id":"ai_fvlBqXZR",
"value": 1
}
]
}
}
}, {
"annotation": {
"data": {
"concepts": [
{
"id":"people",
"value": 0
}
]
}
}
}
]
}
}
]
}'
By Concept in Another Language
Concepts that have a translation into another language can be searched for in that language, even without having the default language for your app being in that language. This uses the Clarifai's knowledge graph to lookup the translation and then perform the search.
For example, if your app is in English and you want to search for "dog" in Japanese, then you could search with language="ja" and name="犬".
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
################################################################################
# In this section, we set the user authentication, app ID, concept name, and
# language ID. 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 what you want to search by
CONCEPT_NAME = '犬'
LANGUAGE_ID = 'ja' # Japanese
##########################################################################
# 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)
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
concepts=[ # You can search by multiple concepts
resources_pb2.Concept(
name=CONCEPT_NAME, # You could search by concept ID as well
value=1 # Value of 0 will search for images that don't have the concept
)
]
)
)
)
],
language=LANGUAGE_ID
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_searches_response.status)
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept name, and
// language ID. 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 what you want to search by
const CONCEPT_NAME = "犬";
const LANGUAGE_ID = "ja"; // Japanese
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"name": CONCEPT_NAME,
"value": 1
}
]
}
}
}
],
"language": LANGUAGE_ID
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept name, and
// language ID. 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 what you want to search by
const CONCEPT_NAME = "犬";
const LANGUAGE_ID = "ja"; // Japanese
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
concepts: [ // You can search by multiple concepts
{
name: CONCEPT_NAME, // You could search by concept Id as well
value: 1 // Value of 0 will search for images that don't have the concept
}
]
}
}
}
],
language: LANGUAGE_ID
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
//////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept name, and
// language ID. 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 what you want to search by
static final String CONCEPT_NAME = "犬";
static final String LANGUAGE_ID = "ja"; // Japanese
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().addConcepts( // You can search by multiple concepts
Concept.newBuilder()
.setName(CONCEPT_NAME) // You could search by concept ID as well
.setValue(1f) // Value of 0 will search for images that don't have the concept
)
)
)
)
.setLanguage(LANGUAGE_ID)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept name, and
// language ID. 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 what you want to search by
$CONCEPT_NAME = "犬";
$LANGUAGE_ID = "ja"; // Japanese
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"concepts" => [ # You can search by multiple concepts
new Concept([
"name" => $CONCEPT_NAME, # You could search by concept id as well
"value" => 1 # Value of 0 will search for images that don't have the concept
])
]
])
])
])
],
"language" => $LANGUAGE_ID
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
# Value of 0 will search for images that don't have the concept.
# Instead of "name", you can search by "id" as well.
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"concepts": [
{
"name": "犬",
"value": 1
}
]
}
}
}
],
"language": "ja"
}
}
]
}'
By Using ConceptSearches Endpoint
You can search for concepts by name, even across different languages, using the ConceptSearches endpoint.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
##########################################################################################
# In this section, we set the user authentication, app ID, search name, and language ID.
# 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 whatever concept you want to search for
SEARCH_NAME = "人"
LANGUAGE_ID = "ja"
##########################################################################
# 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)
post_concepts_searches_response = stub.PostConceptsSearches(
service_pb2.PostConceptsSearchesRequest(
user_app_id=userDataObject,
concept_query=resources_pb2.ConceptQuery(
name=SEARCH_NAME,
language=LANGUAGE_ID
)
),
metadata=metadata
)
if post_concepts_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_concepts_searches_response.status)
raise Exception("Post concepts searches failed, status: " + post_concepts_searches_response.status.description)
print("Found concepts:")
for concept in post_concepts_searches_response.concepts:
print("\t%s %.2f" % (concept.name, concept.value))
# Uncomment this line to print the raw output
#print(post_concepts_searches_response)
<!--index.html file-->
<script>
////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// 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 whatever concept you want to search for
const SEARCH_NAME = "人";
const LANGUAGE_ID = "ja";
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"concept_query": [
{
"name": SEARCH_NAME,
"id": LANGUAGE_ID
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/concepts/searches", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// 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 whatever concept you want to search for
const SEARCH_NAME = "人";
const LANGUAGE_ID = "ja";
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostConceptsSearches(
{
user_app_id: {
"user_id": USER_ID,
"app_id": APP_ID
},
concept_query: { name: SEARCH_NAME, language: LANGUAGE_ID }
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post concepts searches failed, status: " + response.status.description);
}
console.log("Found concepts:");
for (const concept of response.concepts) {
console.log("\t" + concept.name + " " + concept.value);
}
}
);
package com.clarifai.example;
import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;
public class ClarifaiExample {
///////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// 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 whatever concept you want to search for
static final String SEARCH_NAME = "人";
static final String LANGUAGE_ID = "ja";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiConceptResponse postConceptsSearchesResponse = stub.postConceptsSearches(
PostConceptsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.setConceptQuery(
ConceptQuery.newBuilder()
.setName(SEARCH_NAME)
.setLanguage(LANGUAGE_ID))
.build()
);
if (postConceptsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post concepts searches failed, status: " + postConceptsSearchesResponse.getStatus());
}
System.out.println("Found concepts:");
for (Concept concept: postConceptsSearchesResponse.getConceptsList()) {
System.out.printf("\t%s %.2f%n", concept.getName(), concept.getValue());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
////////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, search name, and language ID.
// 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 whatever concept you want to search for
$SEARCH_NAME = "人";
$LANGUAGE_ID = "ja";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostConceptsSearchesRequest;
use Clarifai\Api\ConceptQuery;
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
]);
// 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->PostConceptsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostConceptsSearchesRequest([
"user_app_id" => $userDataObject,
"concept_query" => new ConceptQuery([
"name" => $SEARCH_NAME,
"language" => $LANGUAGE_ID
])
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Found concepts: </br>";
foreach ($response->getConcepts() as $concept) {
echo $concept->getName() . ": " . number_format($concept->getValue(), 2) . "</br>";
}
?>
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"concept_query": {
"name":"人",
"language": "ja"
}
}'
Raw Output Example
Found concepts:
人 1.00
人 1.00
JSON Output Example
status {
code: SUCCESS
description: "Ok"
req_id: "6e24dbc1e4977bd6f4092d0c72169a68"
}
concepts {
id: "ai_ZKJ48TFz"
name: "\344\272\272"
value: 1.0
created_at {
seconds: 1458214981
nanos: 223962000
}
language: "ja"
app_id: "main"
visibility {
gettable: PUBLIC
}
user_id: "clarifai"
}
concepts {
id: "ai_l8TKp2h5"
name: "\344\272\272"
value: 1.0
created_at {
seconds: 1458214981
nanos: 223962000
}
language: "ja"
app_id: "main"
visibility {
gettable: PUBLIC
}
user_id: "clarifai"
}
Search by Visual Similarity
You can use images to search through your collection. The API will return ranked results based on how similar the results are to the image you provided in your query.
Search by Image URL
- Python SDK
- Node.js SDK
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
from clarifai.client.user import User
from PIL import Image
import requests
from IPython.display import display
# Replace these variables with your actual user ID, app ID, and PAT (Personal Access Token)
USER_ID = ''
APP_ID = ''
PAT = ''
# Initialize a User object with the provided user ID and PAT
client = User(user_id=USER_ID, pat=PAT)
# Create an application with the provided app ID, using the Universal workflow
# The PAT is also provided for authentication
app = client.create_app(app_id=APP_ID, base_workflow="Universal", pat=PAT)
# URLs of the images to be uploaded and searched
urls = [
"https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
"https://images.pexels.com/photos/1879386/pexels-photo-1879386.jpeg",
"https://images.pexels.com/photos/1071882/pexels-photo-1071882.jpeg"
]
# Initialize an Inputs object to manage input data
input_obj = app.inputs()
# Initialize a Search object to perform searches
# Limit the number of returned results to 2 (top_k=2)
search = app.search(top_k=2)
# Upload each image from the provided URLs
for i, url in enumerate(urls):
input_obj.upload_from_url(input_id=f"input{i}", image_url=url)
# Perform a search with a specified rank (image URL)
res = search.query(ranks=[{'image_url': 'https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg'}])
# Extract the URL of the first hit from the search results
for r in res:
hit = r.hits[0].input.data.image.url
break
# Print the URL of the hit image
print(hit)
# Open the hit image using PIL, resize it, and display it
hit_img = Image.open(requests.get(hit, stream=True).raw).resize((300, 250))
display(hit_img)
import { User, Input, Search } from "clarifai-nodejs";
const appId = "test_app"; // Placeholder for application ID
// Initialize a User object with the provided user ID and PAT
const client = new User({
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
});
// Create an application with the provided app ID, using the Universal workflow
await client.createApp({ appId, baseWorkflow: "Universal" });
// URLs of the images to be uploaded and searched
const urls = [
"https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
"https://images.pexels.com/photos/1879386/pexels-photo-1879386.jpeg",
"https://images.pexels.com/photos/1071882/pexels-photo-1071882.jpeg",
];
// Initialize an Inputs object to manage input data
const input = new Input({
authConfig: {
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
},
});
// Upload each image from the provided URLs
for (let i = 0; i < urls.length; i++) {
await input.uploadFromUrl({ inputId: `input${i}`, imageUrl: urls[i] });
}
// Initialize a Search object to perform searches
// Limit the number of returned results to 2 (topK=2)
const search = new Search({
authConfig: {
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
},
topK: 2,
metric: "euclidean",
});
// Perform a search with a specified rank (image URL)
const res = search.query({
ranks: [
{
imageUrl:
"https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
},
],
});
// Extract the URL of the first hit from the search results
let hit;
for await (const r of res) {
hit = r.hitsList?.[0]?.input?.data?.image?.url;
break;
}
// Print the URL of the hit image
console.log(hit);
##################################################################
# In this section, we set the user authentication, app ID, and
# image URL. 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 this to the image URL you want to search by
IMAGE_URL = 'https://samples.clarifai.com/metro-north.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)
post_inputs_searches_response = stub.PostInputsSearches(
service_pb2.PostInputsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
image=resources_pb2.Image(
url=IMAGE_URL
)
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_inputs_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_inputs_searches_response.status)
raise Exception("Post searches failed, status: " + post_inputs_searches_response.status.description)
print("Search result:")
for hit in post_inputs_searches_response.hits:
print("\tScore %.2f for input: %s" % (hit.score, hit.input.id))
<!--index.html file-->
<script>
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// image URL. 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 this to the image URL you want to search by
const IMAGE_URL = 'https://samples.clarifai.com/metro-north.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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"image": {
"url": IMAGE_URL
}
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/inputs/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// image URL. 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 this to the image URL you want to search by
const IMAGE_URL = 'https://samples.clarifai.com/metro-north.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);
stub.PostInputsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
image: {
url: IMAGE_URL
}
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post inputs searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for input: " + hit.input.id);
}
}
);
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;
public class ClarifaiExample {
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// image URL. 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 this to the image URL you want to search by
static final String IMAGE_URL = "https://samples.clarifai.com/metro-north.jpg";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postInputsSearchesResponse = stub.postInputsSearches(
PostInputsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Input.newBuilder().setData(
Data.newBuilder().setImage(
Image.newBuilder()
.setUrl(IMAGE_URL)
)
)
)
)
)
)
.build()
);
if (postInputsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post inputs searches failed, status: " + postInputsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postInputsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postInputsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for input %s", hit.getScore(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// image URL. 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 this to the image URL you want to search by
$IMAGE_URL = 'https://samples.clarifai.com/metro-north.jpg';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Image;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"image" => new Image([
"url" => $IMAGE_URL
])
])
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for input: %s\n", $hit->getScore(), $hit->getInput()->getId());
}
?>
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/inputs/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"image": {
"url": "https://samples.clarifai.com/metro-north.jpg"
}
}
}
}
]
}
}
]
}'
Search by Image Bytes
You can also search for an input by bytes, with the bytes being from local storage.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
#######################################################################
# In this section, we set the user authentication, app ID, and image
# file location. 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 this to the image file location you want to search by
IMAGE_FILE_LOCATION = 'YOUR_IMAGE_FILE_LOCATION'
##########################################################################
# 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_searches_response = stub.PostInputsSearches(
service_pb2.PostInputsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
input=resources_pb2.Annotation(
data=resources_pb2.Data(
image=resources_pb2.Image(
base64=file_bytes
)
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_inputs_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_inputs_searches_response.status)
raise Exception("Post searches failed, status: " + post_inputs_searches_response.status.description)
print("Search result:")
for hit in post_inputs_searches_response.hits:
print("\tScore %.2f for input: %s" % (hit.score, hit.input.id))
<!--index.html file-->
<script>
/////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and image
// file location. 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 this to the image bytes you want to search by
const IMAGE_FILE_BYTES = '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEPERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh7/wAARCAAoACgDASIAAhEBAxEB/8QAGQAAAgMBAAAAAAAAAAAAAAAAAAYDBQcE/8QAMBAAAQMDAwMDAgQHAAAAAAAAAQIDBAAFEQYSIQcTMTJBURRhCBYikSNScXKhsdH/xAAZAQACAwEAAAAAAAAAAAAAAAAFBgIDBAf/xAAtEQABAwMBBgQHAQAAAAAAAAABAgMRAAQhMQUSE0FRYQaBocEUFiJCcrHR8P/aAAwDAQACEQMRAD8A3+RYY1unSYzCS0ttZUkAgktn0q5yT7jPyDUC4wdGwycH5U2Kt9ZQ7VI1qw5PkvQy3CSVPpf7aQjuKyFH25xzn3pHn3TVNy01Hl2hyy6YdkSpKsS9sl/6RlI3rRu3dxWd6spwnAGPIJTfl925fcLaoSDHXvyo6i9SlCQrU9wKln3OyWiaDN1RAbW3kKbSd7gPtwMkH/tTWy9afuy1iPfnXMAblITwkE4yf08cn3pSbYt1uts24XH6fUbiLAuY1MWyGkLEmUW0rcCRvUpQ5CtwKQCPgi4S1ZbDe4sd9NntDEe79m3uOBLTr0IR9jzodSMqUpTu9JJ8owD7UTT4ZCfv9PbP7860m+s+HBSrejWRuz2kAxoesGYxTW/Zlpkwo1vkuSly3UgKWQUhHJUvIHsAaKTemF8XE6sWmxyZkiaZrMh1jv8ArQNpUVqB8FW0njHqx4zRVVhsph1KlKk5xQ+7uHmikaSJrQerMByet2IwvtuTLa4xv2k7Rk84H9x/esHv92d01boenLXGcuiWrFIhLlpbcaQ2/JdK3VJCkAq2pAR7Zz7YxWudY9fxNIdQbNGkR5TyX4aisNNpUMFZAzkj4NK0jq9ZpbLr0PSlzkhrlZDaQlP3P8Q4/ap3F87bPucJEkx/hHv60b2TYXLrKN5sramYECSQRk9M6c6zmJ+eb5Hi22M7cnWGIQgFLbX0zSo4PDa1YBcTgDyMjJ/qbGPabH08SJt1Uzc9QqRliGg5QySPKvgc+TyfYDmmTUWpNYz7ctxoQdPQshCktupckDJUPUcJT6DwMq8YyaQ9VL0pCS8zapcq4SVOBZmPDO8/cnknlWcDBwn4NYnPjLkQ+qE9OtOVlYpeVHDCEkkkJyT+SuQzy5Y0ru6Ez511/Efa5s1fdkOtyVurIxgdlQAA9gOKKPwolU7remU5hCGYEgo38KUv9I/0TRTDYJCWQBSF4rIN/CRgAR0iTpVD1j1g/qDqJcJqlKcjB9bcda142MpOEJAzgeMnjyTSyze5KEuNRpDoDvC0oe4X9iAeaKKFK+oya6fbOqYbDTeEiAPKpHdS3gBLYc7RQkp3ApQog+cq8nwPJrljzxnPZbUfnugn/NFFRgEVch9xKsH0H8pg6e3x3T3UC1ajaZITGkJLoS4MKbOUrzz/ACKVRRRVzVwtoQmhG1NkWu0HuI+JI8u/Kv/Z';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"image": {
"base64": IMAGE_FILE_BYTES
}
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/inputs/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
/////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and image
// file location. 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 this to the image file location you want to search by
const IMAGE_FILE_LOCATION = 'YOUR_IMAGE_FILE_LOCATION';
///////////////////////////////////////////////////////////////////////////////////
// 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.PostInputsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
image: {
base64: imageBytes
}
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post inputs searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for input: " + hit.input.id);
}
}
);
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 com.google.protobuf.ByteString;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
public class ClarifaiExample {
/////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and image
// file location. 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 this to the image file location you want to search by
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));
MultiSearchResponse postInputsSearchesResponse = stub.postInputsSearches(
PostInputsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Input.newBuilder().setData(
Data.newBuilder().setImage(
Image.newBuilder()
.setBase64(ByteString.copyFrom(Files.readAllBytes(
new File(IMAGE_FILE_LOCATION).toPath()
)))
)
)
)
)
)
)
.build()
);
if (postInputsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post inputs searches failed, status: " + postInputsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postInputsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postInputsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for input %s", hit.getScore(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and image
// file location. 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 this to the image file location you want to search by
$IMAGE_FILE_LOCATION = "YOUR_IMAGE_FILE_LOCATION";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Image;
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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for input: %s\n", $hit->getScore(), $hit->getInput()->getId());
}
?>
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/inputs/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"image": {
"base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEPERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh7/wAARCAAoACgDASIAAhEBAxEB/8QAGQAAAgMBAAAAAAAAAAAAAAAAAAYDBQcE/8QAMBAAAQMDAwMDAgQHAAAAAAAAAQIDBAAFEQYSIQcTMTJBURRhCBYikSNScXKhsdH/xAAZAQACAwEAAAAAAAAAAAAAAAAFBgIDBAf/xAAtEQABAwMBBgQHAQAAAAAAAAABAgMRAAQhMQUSE0FRYQaBocEUFiJCcrHR8P/aAAwDAQACEQMRAD8A3+RYY1unSYzCS0ttZUkAgktn0q5yT7jPyDUC4wdGwycH5U2Kt9ZQ7VI1qw5PkvQy3CSVPpf7aQjuKyFH25xzn3pHn3TVNy01Hl2hyy6YdkSpKsS9sl/6RlI3rRu3dxWd6spwnAGPIJTfl925fcLaoSDHXvyo6i9SlCQrU9wKln3OyWiaDN1RAbW3kKbSd7gPtwMkH/tTWy9afuy1iPfnXMAblITwkE4yf08cn3pSbYt1uts24XH6fUbiLAuY1MWyGkLEmUW0rcCRvUpQ5CtwKQCPgi4S1ZbDe4sd9NntDEe79m3uOBLTr0IR9jzodSMqUpTu9JJ8owD7UTT4ZCfv9PbP7860m+s+HBSrejWRuz2kAxoesGYxTW/Zlpkwo1vkuSly3UgKWQUhHJUvIHsAaKTemF8XE6sWmxyZkiaZrMh1jv8ArQNpUVqB8FW0njHqx4zRVVhsph1KlKk5xQ+7uHmikaSJrQerMByet2IwvtuTLa4xv2k7Rk84H9x/esHv92d01boenLXGcuiWrFIhLlpbcaQ2/JdK3VJCkAq2pAR7Zz7YxWudY9fxNIdQbNGkR5TyX4aisNNpUMFZAzkj4NK0jq9ZpbLr0PSlzkhrlZDaQlP3P8Q4/ap3F87bPucJEkx/hHv60b2TYXLrKN5sramYECSQRk9M6c6zmJ+eb5Hi22M7cnWGIQgFLbX0zSo4PDa1YBcTgDyMjJ/qbGPabH08SJt1Uzc9QqRliGg5QySPKvgc+TyfYDmmTUWpNYz7ctxoQdPQshCktupckDJUPUcJT6DwMq8YyaQ9VL0pCS8zapcq4SVOBZmPDO8/cnknlWcDBwn4NYnPjLkQ+qE9OtOVlYpeVHDCEkkkJyT+SuQzy5Y0ru6Ez511/Efa5s1fdkOtyVurIxgdlQAA9gOKKPwolU7remU5hCGYEgo38KUv9I/0TRTDYJCWQBSF4rIN/CRgAR0iTpVD1j1g/qDqJcJqlKcjB9bcda142MpOEJAzgeMnjyTSyze5KEuNRpDoDvC0oe4X9iAeaKKFK+oya6fbOqYbDTeEiAPKpHdS3gBLYc7RQkp3ApQog+cq8nwPJrljzxnPZbUfnugn/NFFRgEVch9xKsH0H8pg6e3x3T3UC1ajaZITGkJLoS4MKbOUrzz/ACKVRRRVzVwtoQmhG1NkWu0HuI+JI8u/Kv/Z"
}
}
}
}
]
}
}
]
}'
By Input ID
If the input has been indexed, we can use the input ID. If there are multiple embeddings (for example multiple regions), we will average the embeddings.
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
##################################################################
# In this section, we set the user authentication, app ID, and
# input ID. 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 this to the input ID you want to search by
INPUT_ID = 'c021c670357e4083b197abe80bda82b0'
##########################################################################
# 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)
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
input_id=INPUT_ID
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_searches_response.status)
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// input ID. 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 this to the input ID you want to search by
const INPUT_ID = 'c29f81469db34e04b36d22b9a4aba1fa';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"input_id": INPUT_ID
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// input ID. 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 this to the input ID you want to search by
const INPUT_ID = 'c29f81469db34e04b36d22b9a4aba1fa';
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
input_id: INPUT_ID
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// input ID. 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 this to the input ID you want to search by
static final String INPUT_ID = "c29f81469db34e04b36d22b9a4aba1fa";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setInputId(INPUT_ID)
)
)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
//////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// input ID. 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 this to the input ID you want to search by
$INPUT_ID = "9dc2185524d8422eb1900848f70134db";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Image;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"input_id" => $INPUT_ID
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"input_id": "c29f81469db34e04b36d22b9a4aba1fa"
}
}
]
}
}
]
}'
Search by Text Similarity
You can use texts to search through your collection of texts. The text-to-text search will return ranked results based on how similar the results are to the text you provided in your query.
tip
- To perform text-to-text searches, you could choose a workflow that includes a text embedder and a clusterer, such as the Text workflow, as the base workflow for your application.
- To perform text-to-image searches, you could choose Universal as the base workflow, which allows you to use texts to search through your collection of images.
- Python SDK
- Node.js SDK
- Python (gRPC)
- JavaScript (REST)
- Node.js (gRPC)
- Java (gRPC)
- PHP (gRPC)
- cURL
from clarifai.client.user import User # Importing the User class from the Clarifai client library for user-related functionalities
from PIL import Image # Importing the Image module from the Python Imaging Library (PIL) for image processing
import requests # Importing the requests library to handle HTTP requests
from IPython.display import display # Importing the display function from IPython.display module for displaying images in IPython
USER_ID='' # Placeholder for user ID
APP_ID='' # Placeholder for application ID
PAT='' # Placeholder for personal access token (PAT)
# Initialize the User object with user ID and PAT
client = User(user_id=USER_ID, pat=PAT)
# Create a new application with specified ID and base workflow
app = client.create_app(app_id=APP_ID, base_workflow="Universal", pat=PAT)
# List of image URLs to be uploaded
urls = [
"https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
"https://images.pexels.com/photos/1879386/pexels-photo-1879386.jpeg",
"https://images.pexels.com/photos/1071882/pexels-photo-1071882.jpeg"
]
input_obj = app.inputs() # Initialize Inputs object to manage input data
# Upload images from URLs to the application
for i, url in enumerate(urls):
input_obj.upload_from_url(input_id=f"input{i}", image_url=url)
# Initialize the search functionality for the application with top_k parameter set to 1
search = app.search(top_k=1)
# Perform a search query with a specified text rank
response = search.query(ranks=[{"text_raw": "Red pineapples on the beach."}])
# Extract the URL of the first hit from the search response
for r in response:
hit = r.hits[0].input.data.image.url
break
# Print the URL of the hit image
print(hit)
# Open the hit image from URL, resize it, and display it
hit_img = Image.open(requests.get(hit, stream=True).raw).resize((300,250))
display(hit_img)
import { User, Input, Search } from "clarifai-nodejs"; // Importing the User class from the Clarifai client library for user-related functionalities
const appId = "test_app"; // Placeholder for application ID
// Initialize the User object with user ID and PAT
const client = new User({
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
});
// Create a new application with specified ID and base workflow
await client.createApp({ appId, baseWorkflow: "Universal" });
// List of image URLs to be uploaded
const urls = [
"https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
"https://images.pexels.com/photos/1879386/pexels-photo-1879386.jpeg",
"https://images.pexels.com/photos/1071882/pexels-photo-1071882.jpeg",
];
// Initialize Inputs object to manage input data
const input = new Input({
authConfig: {
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
},
});
// Upload images from URLs to the application
for (let i = 0; i < urls.length; i++) {
await input.uploadFromUrl({ inputId: `input${i}`, imageUrl: urls[i] });
}
// Initialize the search functionality for the application with topK parameter set to 1
const search = new Search({
authConfig: {
userId: process.env.CLARIFAI_USER_ID,
pat: process.env.CLARIFAI_PAT,
appId,
},
topK: 1,
metric: "euclidean",
});
// Perform a search query with a specified text rank
const response = search.query({
ranks: [{ textRaw: "Red pineapples on the beach." }],
});
// Extract the URL of the first hit from the search response
let hit;
for await (const r of response) {
hit = r?.hitsList?.[0]?.input?.data?.image?.url;
break;
}
// Print the URL of the hit image
console.log(hit);
####################################################################################
# In this section, we set the user authentication, app ID, and the raw text we
# we want to search by. 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 this to the raw text you want to search by
RAW_TEXT = 'black dress with white polka dots'
##########################################################################
# 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)
post_annotations_searches_response = stub.PostAnnotationsSearches(
service_pb2.PostAnnotationsSearchesRequest(
user_app_id=userDataObject,
searches = [
resources_pb2.Search(
query=resources_pb2.Query(
ranks=[
resources_pb2.Rank(
annotation=resources_pb2.Annotation(
data=resources_pb2.Data(
text=resources_pb2.Text(
raw=RAW_TEXT
)
)
)
)
]
)
)
],
pagination=service_pb2.Pagination(per_page=2, page=1)
),
metadata=metadata
)
if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_searches_response.status)
raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)
print("Search result:")
for hit in post_annotations_searches_response.hits:
print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
<!--index.html file-->
<script>
/////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the raw text we
// we want to search by. 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 this to the raw text you want to search by
const RAW_TEXT = 'black dress with white polka dots';
///////////////////////////////////////////////////////////////////////////////////
// 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
},
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"text": {
"raw": RAW_TEXT
}
}
}
}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
//index.js file
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the raw text we
// we want to search by. 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 this to the raw text you want to search by
const RAW_TEXT = 'black dress with white polka dots';
///////////////////////////////////////////////////////////////////////////////////
// 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);
stub.PostAnnotationsSearches(
{
user_app_id: {
user_id: USER_ID,
app_id: APP_ID
},
searches: [
{
query: {
ranks: [
{
annotation: {
data: {
text: {
raw: RAW_TEXT
}
}
}
}
]
}
}
]
},
metadata,
(err, response) => {
if (err) {
throw new Error(err);
}
if (response.status.code !== 10000) {
throw new Error("Post annotations searches failed, status: " + response.status.description);
}
console.log("Search result:");
for (const hit of response.hits) {
console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
}
}
);
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;
public class ClarifaiExample {
///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the raw text we
// we want to search by. 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 this to the raw text you want to search by
static final String RAW_TEXT = "black dress with white polka dots";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
public static void main(String[] args) {
V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
.withCallCredentials(new ClarifaiCallCredentials(PAT));
MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
PostAnnotationsSearchesRequest.newBuilder()
.setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
.addSearches(
Search.newBuilder().setQuery(
Query.newBuilder().addRanks(
Rank.newBuilder().setAnnotation(
Annotation.newBuilder().setData(
Data.newBuilder().setText(
Text.newBuilder()
.setRaw(RAW_TEXT)
)
)
)
)
)
)
.build()
);
if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
}
System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
}
}
}
<?php
require __DIR__ . "/vendor/autoload.php";
////////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the raw text we
// we want to search by. 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 this to the raw text you want to search by
$RAW_TEXT = "black dress with white polka dots";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Text;
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
]);
// 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->PostAnnotationsSearches(
// The request object carries the request along with the request status and other metadata related to the request itself
new PostAnnotationsSearchesRequest([
"user_app_id" => $userDataObject,
"searches" => [
new Search([
"query" => new Query([
"ranks" => [
new Rank([
"annotation" => new Annotation([
"data" => new Data([
"text" => new Text([
"raw" => $RAW_TEXT
])
])
])
])
]
])
])
]
]),
$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) {
print $response->getStatus()->getDetails();
throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}
echo "Search result:\n";
foreach ($response->getHits() as $hit) {
printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}
?>
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"searches": [
{
"query": {
"ranks": [
{
"annotation": {
"data": {
"text": {
"raw": "black dress with white polka dots"
}
}
}
}
]
}
}
]
}'