Authentication

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.

Note

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 API Key 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 API Key page, and then select the Regenerate Key button under the API Key section.
  • Revoke an API key: Go to the API Key page, 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.

1

Install the SDK package for your programming language:

$pip install twelvelabs
2

Import the SDK into your application.

3

Instantiate the SDK client by providing your API key.

4

Use the SDK to interact with the platform, such as creating an index.

Below are complete code examples for Python and Node.js, integrating all the steps outlined above:

1# Step 2: Import the SDK
2from twelvelabs import TwelveLabs
3
4# Step 3: Instantiate the SDK client
5client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7# Step 4: Use the SDK to create an index
8index = client.index.create(
9 name="<YOUR_INDEX_NAME>",
10 models=[
11 {
12 "name": "marengo2.7",
13 "options": ["visual", "audio"]
14 }
15 ]
16)
17print(f"Created index: id={index.id}")

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 request.

1

Verify that the required packages are installed on your system. If necessary, install the following packages:

Install the requests package by entering the following command:

$python -m pip install requests
2

Define the URL of the API and the specific endpoint for your request.

3

Create the necessary headers for authentication.

4

Prepare the data payload for your API request.

5

Send the API request and process the response.

Below are complete code examples for Python and Node.js, integrating all the steps outlined above:

1import requests
2
3# Step 2: Define the API URL and the specific endpoint
4API_URL = "https://api.twelvelabs.io/v1.3"
5INDEXES_URL = f"{API_URL}/indexes"
6
7# Step 3: Create the necessary headers for authentication
8headers = {
9 "x-api-key": "<YOUR_API_KEY>"
10}
11
12# Step 4: Prepare the data payload for your API request
13INDEX_NAME = "<YOUR_INDEX_NAME>"
14data = {
15 "models": [
16 {
17 "model_name": "marengo2.7",
18 "model_options": ["visual", "audio"]
19 }
20 ],
21 "index_name": INDEX_NAME
22}
23
24# Step 5: Send the API request and process the response
25response = requests.post(INDEXES_URL, headers=headers, json=data)
26print(f"Status code: {response.status_code}")
27if response.status_code == 201:
28 print(response.json())
29else:
30 print("Error:", response.json())