For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • TwelveLabs API
    • Introduction
    • Authentication
  • API Reference
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Any-to-video search
    • Create embeddings v2
      • POSTCreate sync embeddings
      • POSTCreate an async embedding task
      • GETList async embedding tasks
      • GETRetrieve task status and results
    • Create embeddings v1
    • Analyze and segment videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceCreate embeddings v2

Create an async embedding task

POST
https://api.twelvelabs.io/v1.3/embed-v2/tasks
POST
/v1.3/embed-v2/tasks
$curl -X POST https://api.twelvelabs.io/v1.3/embed-v2/tasks \
>     -H "x-api-key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "input_type": "audio",
>  "model_name": "marengo3.0",
>  "audio": {
>    "media_source": {
>      "url": "https://user-bucket.com/audio/long-audio.wav"
>    },
>    "start_sec": 0,
>    "end_sec": 3600,
>    "segmentation": {
>      "strategy": "fixed",
>      "fixed": {
>        "duration_sec": 6
>      }
>    },
>    "embedding_option": [
>      "audio",
>      "transcription"
>    ],
>    "embedding_scope": [
>      "clip",
>      "asset"
>    ]
>  }
>}'
1{
2  "_id": "64f8d2c7e4a1b37f8a9c5d12",
3  "status": "processing"
4}
This endpoint creates embeddings for audio and video content asynchronously. **When to use this endpoint**: - Process audio or video files longer than 10 minutes - Process files up to 4 hours in duration <Accordion title="Input requirements"> **Video**: - Minimum duration: 4 seconds - Maximum duration: 4 hours - Maximum file size: 4 GB - Formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html) - Resolution: 360x360 to 5184x2160 pixels - Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1 **Audio**: - Minimum duration: 4 seconds - Maximum duration: 4 hours - Maximum file size: 4 GB - Formats: WAV (uncompressed), MP3 (lossy), FLAC (lossless) </Accordion> Creating embeddings asynchronously requires three steps: 1. Create a task using this endpoint. The platform returns a task ID. 2. Poll for the status of the task using the [`GET`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings) method of the `/embed-v2/tasks/{task_id}` endpoint. Wait until the status is `ready`. 3. Retrieve the embeddings from the response when the status is `ready` using the [`GET`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings) method of the `/embed-v2/tasks/{task_id}` endpoint. <Note title="Notes"> - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. - Embeddings are stored for seven days. </Note>
Was this page helpful?
Previous

List async embedding tasks

Next
Built with

This endpoint creates embeddings for audio and video content asynchronously.

When to use this endpoint:

  • Process audio or video files longer than 10 minutes
  • Process files up to 4 hours in duration
Input requirements

Video:

  • Minimum duration: 4 seconds
  • Maximum duration: 4 hours
  • Maximum file size: 4 GB
  • Formats: FFmpeg supported formats
  • Resolution: 360x360 to 5184x2160 pixels
  • Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1

Audio:

  • Minimum duration: 4 seconds
  • Maximum duration: 4 hours
  • Maximum file size: 4 GB
  • Formats: WAV (uncompressed), MP3 (lossy), FLAC (lossless)

Creating embeddings asynchronously requires three steps:

  1. Create a task using this endpoint. The platform returns a task ID.
  2. Poll for the status of the task using the GET method of the /embed-v2/tasks/{task_id} endpoint. Wait until the status is ready.
  3. Retrieve the embeddings from the response when the status is ready using the GET method of the /embed-v2/tasks/{task_id} endpoint.
Notes
  • This endpoint is rate-limited. For details, see the Rate limits page.
  • Embeddings are stored for seven days.

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request

This endpoint expects an object.
input_typeenumRequired

The type of content for the embeddings.

Values:

  • audio: Audio files
  • video: Video content
Allowed values:
model_nameenumRequiredDefaults to marengo3.0

The model you wish to use. Value: "marengo3.0".

Allowed values:
audioobjectOptional

This field is required if the input_type parameter is audio.

videoobjectOptional

This field is required if the input_type parameter is video.

Response

An embedding task has successfully been created.
_idstring
The unique identifier of the embedding task
statusenum
The initial status of the embedding task.
Allowed values:
datalist of objects or null

An array of embedding results when status is ready, or null when status is processing or failed.

Errors

400
Bad Request Error
500
Internal Server Error

Your API key.

Note

You can find your API key on the API Keys page.