Create text embeddings

To create text embeddings, invoke the POST method of the /embed endpoint, specifying at least the following parameters:

  • engine_name: The name of the engine you want to use. For details about the available engines, see the Engines page.
  • text: The text for which you want to create an embedding.

The response is an object containing the following fields:

  • engine_name: The name of the engine the platform has used to create this embedding.
  • text_embedding: An object that contains a field named float which is an array of floating point numbers representing the embedding.

Note that text embeddings cannot exceed 77 tokens. If your text exceeds this limit, the platform defaults to truncating the embedding at the end. You can alter this default behavior by using the text_truncate parameter to specify one of the following actions:

  • start: Truncate the beginning of the text.
  • end: Truncate the end of the text.
  • none: Return an error if the text exceeds the token limit.

For a description of each field in the request and response, see the API Reference > Create text embeddings page.

Prerequisites

  • You’re familiar with the concepts that are described on the Platform overview page.
  • You have an API key. To retrieve your API key, navigate to the Dashboard page and log in with your credentials. Then, select the Copy icon to the right of your API key to copy it to your clipboard.

Examples

The example code below creates a text embedding using the default behavior for handling text that is too long. Ensure you replace the placeholders surrounded by <> with your values.

# python -m pip install requests

import requests

# Construct the URL of the `/embed` endpoint
BASE_URL = "https://api.twelvelabs.io"
VERSION = "v1.2"
EMBED_URL = f"{BASE_URL}/{VERSION}/embed"

# Set the headers of the request
headers = {
    "x-api-key": "<YOUR_API_KEY>"
}

# Specify the body of the request
data = {
    "engine_name": "Marengo-retrieval-2.6",
    "text": "<YOUR_TEXT>",
}

# Invoke the POST method of the `/embed` endpoint
response = requests.post(EMBED_URL, headers=headers, data=data)

# Print the status code and the response
print(f"Status Code: {response.status_code}")
print("Response:")
print(response.json())
// npm install axios

import axios from 'axios'
import FormData from 'form-data';

// Construct the URL of the `/embed` endpoint
const BASE_URL = 'https://api.twelvelabs.io';
const VERSION = 'v1.2';
const EMBED_URL = `${BASE_URL}/${VERSION}/embed`;


// Set the headers of the request
const headers = {
    'x-api-key': '<YOUR_API_KEY>',
    'Content-Type': 'multipart/form-data'
};

// Specify the body of the request
const data = new FormData();
data.append('engine_name', 'Marengo-retrieval-2.6');
data.append('text', '<YOUR_TEXT>');


// Invoke the POST method of the `/embed` endpoint
const resp = await axios.post(
  EMBED_URL,
  data,
  { headers: headers }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(response)

The example output below was truncated for brevity:

{
  "engine_name": "Marengo-retrieval-2.6",
  "text_embedding": {
    "float": [
      -0.026725426,
      0.046021145,
      0.014251829
    ]
  }
}

To override the default behavior, you can specify the text_truncate parameter. The following example code sets the value of the text_truncate parameter to start in the body of the request. Ensure you replace the placeholder surrounded by <> with the text you want to create an embedding for.

data = {
    "engine_name": "Marengo-retrieval-2.6",
    "text": "<YOUR_TEXT>",
    "text_truncate": "start"
}
const data = new FormData();
data.append('engine_name', 'Marengo-retrieval-2.6');
data.append('text', '<YOUR_TEXT>');
data.append('text_truncate', 'start');