Create Concepts

Learn how to create concepts within your app

---

Create via the UI

To create a new concept, head to your application's individual page and select the Inputs option in the collapsible left sidebar.

You'll be redirected to the Inputs-Manager page, where you can create new concepts and use them to complete various operations.

There are several ways to create concepts on the platform. Let's illustrate two of them:

• Via the Labels section
• Via the inputs uploader

Via the Labels Section

To create a new concept, go to the Labels section on the Inputs-Manager page and click the plus sign (+) next to the Select or add concepts search box. Then, type the new concept name in the search box.

The new name you've typed will appear underneath the search box. Click the Add new label button to create the concept.

The new concept will be successfully added to your app. You can follow the same process to create other concepts for your app.

Via the Inputs Uploader

You can also create new concepts when uploading inputs to your app. To do so, click the Upload Inputs button at the upper-right corner of the Inputs-Manager page.

The window that pops up allows you to upload your inputs — either by uploading them directly from your local device or by providing a publicly accessible URL.

In the Concepts section of the pop-up window, click the plus sign (+) next to the Select or add concepts search box. Then, type the new concept name in the search box.

The new name you've typed will appear underneath the search box. Click the Add new concept button to create the concept.

The new concept will be successfully added to your app.

You can also click the Upload inputs button at the bottom of the pop-up window to finalize uploading your input.

Create via the API

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.

Create Concepts

To create a new concept in your app, you POST the concept with an id and name. You can also post more than one concept in the same request by sending a list of concepts.

Below is an example of how to add concepts.

Python SDK

import os
from clarifai.client.app import App

# Set your Personal Access Token (PAT)
os.environ["CLARIFAI_PAT"] = "YOUR_PAT_HERE"

app = App(user_id="YOUR_USER_ID_HERE", app_id="YOUR_APP_ID_HERE")

app.create_concepts(concept_ids=["cat", "kitten", "animal"])

Python (gRPC)

################################################################################
# In this section, we set the user authentication, app ID, concept ID and name.
# 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 concepts you want to process
CONCEPT_ID = 'cat'
CONCEPT_NAME = 'Cat Name'

##########################################################################
# 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_response = stub.PostConcepts(
    service_pb2.PostConceptsRequest(
        user_app_id=userDataObject,
        concepts=[resources_pb2.Concept(id=CONCEPT_ID, name=CONCEPT_NAME)]
    ),
    metadata=metadata
)

if post_concepts_response.status.code != status_code_pb2.SUCCESS:
    print(post_concepts_response.status)
    raise Exception("Post concept failed, status: " + post_concepts_response.status.description)
    
print(post_concepts_response)

JavaScript (REST)

<!--index.html file-->

<script>
    ////////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, concept ID and name.
    // 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 concepts you want to process
    const CONCEPT_ID = 'cat';
    const CONCEPT_NAME = 'Cat Name';

    ///////////////////////////////////////////////////////////////////////////////////
    // 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
        },
        "concepts": [
            {
                "id": CONCEPT_ID,
                "name": CONCEPT_NAME
            }
        ]
    });

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

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

Node.js (gRPC)

//index.js file

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// 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 concepts you want to process
const CONCEPT_ID = 'cat';
const CONCEPT_NAME = 'Cat Name';

///////////////////////////////////////////////////////////////////////////////////
// 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.PostConcepts(
    {
        user_app_id: {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        concepts: [{ id: CONCEPT_ID, name: CONCEPT_NAME }]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

        if (response.status.code !== 10000) {
            throw new Error("Post concepts failed, status: " + response.status.description);
        }
    }
);

Java (gRPC)

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, concept ID and name.
    // 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 concepts you want to process
    static final String CONCEPT_ID = "charlie";
    static final String CONCEPT_NAME = "Charlie Name";

    ///////////////////////////////////////////////////////////////////////////////////
    // 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 postConceptsResponse = stub.postConcepts(
            PostConceptsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addConcepts(Concept.newBuilder().setId(CONCEPT_ID).setName(CONCEPT_NAME))
            .build()
        );

        if (postConceptsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post concepts failed, status: " + postConceptsResponse.getStatus());
        }

    }

}

PHP (gRPC)

<?php

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

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, concept ID and name.
// 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 concepts you want to process
$CONCEPT_ID = "cat";
$CONCEPT_NAME = "Cat Name";

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

use Clarifai\Api\Concept;
use Clarifai\ClarifaiClient;
use Clarifai\Api\PostConceptsRequest;
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->PostConcepts(
        // The request object carries the request along with the request status and other metadata related to the request itself
        new PostConceptsRequest([
            "user_app_id" => $userDataObject,
            "concepts" => [
                new Concept([
                    "id" => $CONCEPT_ID,
                    "name" => $CONCEPT_NAME
                ])
            ]         
        ]),
        $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());
}

print $response->serializeToJsonString();

?>

cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/concepts" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "concepts": [
      {
        "id": "CONCEPT_ID_HERE",
        "name": "CONCEPT_NAME_HERE"
      }
      ]
  }'

Raw Output Example

status {
    code: SUCCESS
    description: "Ok"
    req_id: "9852fce206578f4bc5b6bed38f03eed8"
  }
  concepts {
    id: "cat"
    name: "Cat Name"
    value: 1.0
    created_at {
      seconds: 1643890626
      nanos: 775078265
    }
    language: "en"
    app_id: "a39423543bb941bf9ba2ee95fad11f0a"
    visibility {
      gettable: PRIVATE
    }
    user_id: "ei2l2oz3s3iz"
  }