> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

> 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 a video embedding task

POST https://api.twelvelabs.io/v1.3/embed/tasks
Content-Type: multipart/form-data

This endpoint will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.

This method creates a new video embedding task that uploads a video to the platform and creates one or multiple video embeddings.

This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.

Upload options:

* **Local file**: Use the `video_file` parameter
* **Publicly accessible URL**: Use the `video_url` parameter.

Specify at least one option. If both are provided, `video_url` takes precedence.

Your videos must meet the [requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements).
This endpoint allows you to upload files up to 2 GB in size.  To upload larger files, use the [Multipart Upload API](/v1.3/api-reference/upload-content/multipart-uploads)

* The Marengo video understanding model generates embeddings for all modalities in the same latent space. This shared space enables any-to-any searches across different types of content.
* Video embeddings are stored for seven days.

Reference: https://docs.twelvelabs.io/api-reference/create-embeddings-v1/video-embeddings/create-video-embedding-task

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Body (multipart/form-data)

This endpoint expects a multipart form containing an optional file.

- `model_name` (string, required) — The name of the model you want to use. The following models are available: - `marengo3.0`: Enhanced model with sports intelligence and extended content support.
- `video_file` (file, optional) — Specify this parameter to upload a video from your local file system.
- `video_url` (string, optional) — Specify this parameter to upload a video from a publicly accessible URL.
- `video_start_offset_sec` (double, optional) — The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video. **Default**: 0 **Min**: 0 **Max**: Duration of the video minus video_clip_length
- `video_end_offset_sec` (double, optional) — The end offset in seconds from the beginning of the video where processing should stop. Ensure the following when you specify this parameter: - The end offset does not exceed the total duration of the video file. - The end offset is greater than the start offset. - You must set both the start and end offsets. Setting only one of these offsets is not permitted, resulting in an error. **Min**: video_start_offset + video_clip_length **Max**: Duration of the video file
- `video_clip_length` (double, optional) — The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets. **Default**: 6 **Min**: 2 **Max**: 10
- `video_embedding_scope` (list of enum, optional) — Defines the scope of video embedding generation. Valid values are the following: - `clip`: Creates embeddings for each video segment of `video_clip_length` seconds, from `video_start_offset_sec` to `video_end_offset_sec`. - `clip` and `video`: Creates embeddings for video segments and the entire video. Use the `video` scope for videos up to 10-30 seconds to maintain optimal performance. To create embeddings for segments and the entire video in the same request, include this parameter twice as shown below: ```json --form video_embedding_scope=clip \ --form video_embedding_scope=video ``` **Default**: `clip`

## Response

### 200

A video embedding task has successfully been created.

- `_id` (string, optional) — The unique identifier of the video embedding task. You can use the identifier to: * Retrieve the status of your task by invoking the [`GET`](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embedding-task-status) method of the `/embed/tasks/{task_id}/status` endpoint. * Retrieve the embedding by invoking the [`GET`](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embeddings) method of the `/embed/tasks/{task_id}` endpoint.

## Errors

### 400 Bad Request Error

The request has failed.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.

## Examples

### embed_tasks_create_example

**Request**

```json
{}
```

**Response**

```json
{
  "_id": "66419a20c70bb578439bd8f4"
}
```

**SDK Code**

```python embed_tasks_create_example
import requests

url = "https://api.twelvelabs.io/v1.3/embed/tasks"

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

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript embed_tasks_create_example
const url = 'https://api.twelvelabs.io/v1.3/embed/tasks';
const options = {method: 'POST', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go embed_tasks_create_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/embed/tasks"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby embed_tasks_create_example
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/embed/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java embed_tasks_create_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/embed/tasks")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php embed_tasks_create_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/embed/tasks', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp embed_tasks_create_example
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/embed/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift embed_tasks_create_example
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/embed/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Video embedding using clip scope

**Request**

```json
{
  "model_name": "marengo3.0",
  "video_file": "<file: /Users/john/Documents/video.mp4>",
  "video_embedding_scope": [
    "clip"
  ]
}
```

**Response**

```json
{
  "_id": "66419a20c70bb578439bd8f4"
}
```

**SDK Code**

```python Video embedding using clip scope
import requests

url = "https://api.twelvelabs.io/v1.3/embed/tasks"

files = { "video_file": "open('/Users/john/Documents/video.mp4', 'rb')" }
payload = {
    "model_name": "marengo3.0",
    "video_url": ,
    "video_start_offset_sec": ,
    "video_end_offset_sec": ,
    "video_clip_length": ,
    "video_embedding_scope": "[
  \"clip\"
]"
}
headers = {"x-api-key": "<apiKey>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript Video embedding using clip scope
const url = 'https://api.twelvelabs.io/v1.3/embed/tasks';
const form = new FormData();
form.append('model_name', 'marengo3.0');
form.append('video_file', '/Users/john/Documents/video.mp4');
form.append('video_url', '');
form.append('video_start_offset_sec', '');
form.append('video_end_offset_sec', '');
form.append('video_clip_length', '');
form.append('video_embedding_scope', '[
  "clip"
]');

const options = {method: 'POST', headers: {'x-api-key': '<apiKey>'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Video embedding using clip scope
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/embed/tasks"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_name\"\r\n\r\nmarengo3.0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_file\"; filename=\"video.mp4\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_url\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_start_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_end_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_clip_length\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_embedding_scope\"\r\n\r\n[\n  \"clip\"\n]\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Video embedding using clip scope
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/embed/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_name\"\r\n\r\nmarengo3.0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_file\"; filename=\"video.mp4\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_url\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_start_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_end_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_clip_length\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_embedding_scope\"\r\n\r\n[\n  \"clip\"\n]\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java Video embedding using clip scope
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/embed/tasks")
  .header("x-api-key", "<apiKey>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_name\"\r\n\r\nmarengo3.0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_file\"; filename=\"video.mp4\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_url\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_start_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_end_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_clip_length\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_embedding_scope\"\r\n\r\n[\n  \"clip\"\n]\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php Video embedding using clip scope
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/embed/tasks', [
  'multipart' => [
    [
        'name' => 'model_name',
        'contents' => 'marengo3.0'
    ],
    [
        'name' => 'video_file',
        'filename' => '/Users/john/Documents/video.mp4',
        'contents' => null
    ],
    [
        'name' => 'video_embedding_scope',
        'contents' => '[
  "clip"
]'
    ]
  ]
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Video embedding using clip scope
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/embed/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_name\"\r\n\r\nmarengo3.0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_file\"; filename=\"video.mp4\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_url\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_start_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_end_offset_sec\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_clip_length\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video_embedding_scope\"\r\n\r\n[\n  \"clip\"\n]\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Video embedding using clip scope
import Foundation

let headers = ["x-api-key": "<apiKey>"]
let parameters = [
  [
    "name": "model_name",
    "value": "marengo3.0"
  ],
  [
    "name": "video_file",
    "fileName": "/Users/john/Documents/video.mp4"
  ],
  [
    "name": "video_url",
    "value": 
  ],
  [
    "name": "video_start_offset_sec",
    "value": 
  ],
  [
    "name": "video_end_offset_sec",
    "value": 
  ],
  [
    "name": "video_clip_length",
    "value": 
  ],
  [
    "name": "video_embedding_scope",
    "value": "[
  \"clip\"
]"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/embed/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```