The API uses keys for authentication, and your key is similar to a password. Avoid distributing your API key to other users, or hard-coding it. Generate a new key whenever you think your account may have been compromised.

For security reasons, your API key automatically expires every 90 days. When your key has expired, you must generate a new one to continue using the API.

📘

Notes

• If your policies require you to rotate keys more often, you can always generate a new key.
• If you want to pause using the API without deleting your account, you can revoke your API key.

Before you begin, sign up for a free account, or if you already have one, sign in.

The process of managing your API key can be divided into the following tasks:

• Retrieve your API key: Go to the Dashboard page, and select the Copy icon to the right of the key to copy it to your clipboard.
• Generate a new API key: Go to the Dashboard page, choose Settings from the sidebar, and then select the Regenerate Key button under the API Key section.
• Revoke an API key: Go to the Dashboard page, choose Settings from the sidebar, and then select the Revoke Key button under the API Key section.

You can interact with the platform using an available SDK or an HTTP client like requests or axios. Follow the steps in one of the sections below, depending on your use case.

Use an SDK

If you are using an SDK client, provide your API key when instantiating the client.

Prerequisites

• You have an API key.

Procedure

1. Install the twelvelabs package:

   PythonNode.js

   pip install twelvelabs
   

   yarn add twelvelabs-js
   

2. Import the SDK into your application:

   PythonNode.js

   from twelvelabs import TwelveLabs
   

   import { TwelveLabs } from 'twelvelabs-js';
   

3. Instantiate the SDK client, replacing the placeholder surrounded by <> with your API key:

   PythonNode.js

   client = TwelveLabs(api_key="<YOUR_API_KEY>")
   

   const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>' });
   

4. Use the SDK to interact with the platform. The example code below demonstrates creating an index:

   PythonNode.js

   try:
     index = client.index.create(
         name="<YOUR_INDEX_NAME>",
         engines=[
             {
                 "name": "marengo2.6",
                 "options": ["visual", "conversation"],
             }
         ]
     )
     print(f"Created index: id={index.id}")
     except AuthenticationError as e:
       print(e)
   

   try {
     let index = await client.index.create({
       name: '<YOUR_INDEX_NAME>',
       engines: [
         {
           name: 'marengo2.6',
           options: ['visual', 'conversation'],
         },
       ],
     });
     console.log(`Created index: id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)}`);
   } catch (e) {
     console.log(e);
   }
   

   If your API key is valid, the response should look similar to the following:

   Created index: id=65d2f02c6efba5e3988d6cdc
   

   If your API key has expired or is invalid, the response should look similar to the following:

   Error code: 401 - {'code': 'api_key_invalid', 'message': 'Provided API key is invalid. Please check your API key or generate a new one from the dashboard and try again.'}
   

Use an HTTP client

If you are making HTTP requests using clients such as requests or axios, include the API key in the header of each HTTP request.

Prerequisites

• You have an API key.
• The URL of the API service is stored in a variable named API_URL. For details about retrieving the URL of the API service, see the Call an endpoint section.

Procedure

1. Depending on the programming language you are using, ensure that the required packages are installed.

   • For Python: Install the requests package by entering the following command:
     Shell

     python -m pip install requests
     

   • For Node.js: Install theaxios and form-data packages by entering the following command:
     Shell

     npm install axios form-data
     

2. Construct the headers for the HTTP request, replacing the placeholder surrounded by <> with your API key:

   PythonNode.js

   headers = {
       "x-api-key": "<YOUR_API_KEY>"
   }
   

   const headers = {
     'x-api-key': '<YOUR_API_KEY>'
   }
   

3. Declare the /indexes endpoint:

   PythonNode.js

   INDEXES_URL = f"{API_URL}/indexes"
   

   const INDEXES_URL = `${API_URL}/indexes`
   

4. Create a new index by calling the POST method of the /indexes endpoint, passing the x-api-key header parameter with the value of your API key.

   PythonNode.js

   INDEX_NAME = "<YOUR_INDEX_NAME>" 
   data = {
       "engines": [
         {
           "engine_name": "marengo2.6",
           "engine_options":  ["visual", "conversation", "text_in_video", "logo"]
         }
       ],
       "index_name": INDEX_NAME,
   }
   
   response = requests.post(INDEXES_URL, headers=headers, json=data)
   print (f'Status code: {response.status_code}')
   print (response.json())
   

   const INDEX_NAME = '<YOUR_INDEX_NAME>' 
   const resp = await axios.post(
   		INDEXES_URL,
   		{
   		'engine_id': 'marengo2.5',
   		'index_options': ['visual', 'conversation', 'text_in_video'],
   		'index_name': INDEX_NAME
   	},
   	{ headers }
   )
   const { data: response } = resp;
   console.log(`Status code: ${resp.status}`)
   console.log(response)
   

   If your API key is valid, the response should look similar to the following:

   JSON

   {
     "_id": "63fd8686e5857ca95a830ad1"
   }
   

   If your API key has expired or is invalid, the response should look similar to the following:

   JSON

   Status code: 401
   {
     "code": "api_key_invalid",
     "message": "Provided API key is invalid. Please check your API key or generate a new one from the dashboard and try again."
   }