> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Create text, image, and audio embeddings > Create text, image, and audio embeddings. The SDK provides methods to create text, image, and audio embeddings. # Methods ## Create text, image, and audio embeddings **Description**: This method creates a new embedding. Ensure your media files meet the [input requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#input-requirements) for Marengo 3.0. Note that you must specify at least the following parameters: * `modelName`: The name of the video understanding model to use. * One or more of the following input types: * `text`: For text embeddings * `audioUrl` or `audioFile`: For audio embeddings. If you specify both, the `audioUrl` parameter takes precedence. * `imageUrl` or `imageFile`: For image embeddings. If you specify both, the `imageUrl` parameter takes precedence. You must provide at least one input type, but you can include multiple types in a single function call. > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```javascript Function signature create( request: TwelvelabsApi.EmbedCreateRequest, requestOptions?: Embed.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js"; const printSegments = (segments: TwelvelabsApi.BaseSegment[]) => { segments.forEach((segment) => { const first_few = segment.float?.slice(0, 5); console.log( ` embeddings: [${first_few?.join(", ")}...] (total: ${segment.float?.length } values)` ); }); }; const modelName = "marengo3.0"; let res = await client.embed.create({ modelName, text: "", audioUrl: "", imageUrl: "", audioStartOffsetSec: 10.0 }); if ("textEmbedding" in res && res.textEmbedding?.segments) { console.log("Created text embeddings:"); printSegments(res.textEmbedding.segments); } if ("imageEmbedding" in res && res.imageEmbedding?.segments) { console.log("Created image embeddings:"); printSegments(res.imageEmbedding.segments); } if ("audioEmbedding" in res && res.audioEmbedding?.segments) { console.log("Created audio embeddings:"); printSegments(res.audioEmbedding.segments); } ``` ### Parameters | Name | Type | Required | Description | | --------------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `modelName` | `string` | Yes | The name of the video understanding model to use. The following models are available: - `marengo3.0`: Enhanced model with sports intelligence and extended content support. | | `text` | `string` | No | The text for which you want to create an embedding. The platform automatically truncates text exceeding 500 tokens from the end. | | `imageUrl` | `string` | No | The publicly accessible URL of the image for which you wish to create an embedding. Required for image embeddings if `imageFile` is not provided. | | `imageFile` | `File \| fs.ReadStream \| Blob` | No | A local image file. Required for image embeddings if `imageUrl` is not provided. | | `audioUrl` | `string` | No | The publicly accessible URL of the audio file for which you wish to create an embedding. Required for audio embeddings if `audioFile` is not provided. | | `audioFile` | `File \| fs.ReadStream \| Blob` | No | A local audio file. Required for audio embeddings if `audioUrl` is not provided. | | `audioStartOffsetSec` | `number` | No | Specifies the start time, in seconds, from which the platform generates the audio embeddings. Default: `0`. | | `requestOptions` | `Embed.RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `HttpResponsePromise` that resolves to an `EmbeddingResponse` object containing the embedding results. The `EmbeddingResponse` interface contains the following properties: | Name | Type | Description | | ---------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `modelName` | `string` | The name of the video understanding model the platform has used to create this embedding. | | `textEmbedding` | `TextEmbeddingResult` | An object that contains the generated text embedding vector and associated information. Present when a text was processed. | | `imageEmbedding` | `ImageEmbeddingResult` | An object that contains the generated image embedding vector and associated information. Present when an image was processed. | | `audioEmbedding` | `AudioEmbeddingResult` | An object that contains the generated audio embedding vector and associated information. Present when an audio file was processed. | The `TextEmbeddingResult` interface contains the following properties: | Name | Type | Description | | -------------- | --------------- | ------------------------------------------------- | | `errorMessage` | `string` | Error message if the embedding generation failed. | | `segments` | `BaseSegment[]` | An object that contains the embedding. | The `ImageEmbeddingResult` interface contains the following properties: | Name | Type | Description | | -------------- | ----------------------- | ------------------------------------------------- | | `errorMessage` | `string` | Error message if the embedding generation failed. | | `segments` | `BaseSegment[]` | An object that contains the embedding. | | `metadata` | `BaseEmbeddingMetadata` | Metadata about the embedding. | The `AudioEmbeddingResult` interface contains the following properties: | Name | Type | Description | | -------------- | ----------------------- | --------------------------------------------------------- | | `segments` | `AudioSegment[]` | An object that contains the embedding and its start time. | | `errorMessage` | `string` | Error message if the embedding generation failed. | | `metadata` | `BaseEmbeddingMetadata` | Metadata about the embedding. | The `BaseSegment` interface contains the following properties: | Name | Type | Description | | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `float` | `number[]` | An array of floating point numbers representing the embedding. You can use this array with cosine similarity for various downstream tasks. | The `AudioSegment` interface extends `BaseSegment` and contains the following additional properties: | Name | Type | Description | | ---------------- | -------- | --------------------------------------------------------------- | | `startOffsetSec` | `number` | The start time in seconds from the beginning of the audio file. | | `endOffsetSec` | `number` | The end time in seconds from the beginning of the audio file. | The `BaseEmbeddingMetadata` interface contains the following properties: | Name | Type | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `inputUrl` | `string` | The URL of the media file used to generate the embedding. Present if a URL was provided in the request. | | `inputFilename` | `string` | The name of the media file used to generate the embedding. Present if a file was provided in the request. | ### API Reference [Create text, image, and audio embeddings](/v1.3/api-reference/create-embeddings-v1/text-image-audio-embeddings/create-text-image-audio-embeddings). ### Related guide * [Embed a query](/v1.3/docs/guides/create-embeddings/query) * [Audio embeddings](/v1.3/docs/guides/create-embeddings/at-scale/audio) * [Embed a query](/v1.3/docs/guides/create-embeddings/query) # Error codes This section lists the most common error messages you may encounter while creating text, image, and audio embeddings. * `parameter_invalid` * The `text` parameter is invalid. The text token length should be less than or equal to 77. * The `text_truncate` parameter is invalid. You should use one of the following values: `none`, `start`, `end`. For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/error-codes) page.