> 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. # Retrieve video information GET https://api.twelvelabs.io/v1.3/indexes/{index-id}/videos/{video-id} This method will be deprecated in a future version. New implementations should use the [Retrieve an indexed asset](/v1.3/api-reference/index-content/retrieve) method.This method retrieves information about the specified video. Reference: https://docs.twelvelabs.io/api-reference/videos/retrieve ## Authentication - `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page. ## Request ### Path parameters - `index-id` (string, required) — The unique identifier of the index to which the video has been uploaded. - `video-id` (string, required) — The unique identifier of the video to retrieve. ### Query parameters - `embedding_option` (list of enum, optional) — Specifies which types of embeddings to retrieve. Values: `visual`, `audio`, `transcription`. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section. To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model. For details on enabling this model for an index, see the [Create an index](/reference/create-index) page. - Allowed values: `visual`, `audio`, `transcription`, `visual-text` - `transcription` (boolean, optional) — The parameter indicates whether to retrieve a transcription of the spoken words for the indexed video. ## Response ### 200 The specified video information has successfully been retrieved. - `_id` (string, optional) — The unique identifier of the video. - `asset_id` (string, optional) — The unique identifier of the associated asset. - `created_at` (string, optional) — A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the video indexing task was created. - `updated_at` (string, optional) — A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the corresponding video indexing task was last updated. The platform updates this field every time the corresponding video indexing task transitions to a different state. - `indexed_at` (string, optional) — A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the video indexing task has been completed. - `system_metadata` (IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaSystemMetadata, optional) — System-generated metadata about the video. - `user_metadata` (map from string to UserMetadataValue, optional) — User-defined metadata for this video. - `hls` (HLSObject, optional) — The platform returns this object only for the videos that you uploaded with the `enable_video_stream` parameter set to `true`. - `embedding` (IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaEmbedding, optional) — Contains the embedding and the associated information. The platform returns this field when the `embedding_option` parameter is specified in the request. - `transcription` (list of TranscriptionDataItems, optional) — An array of objects that contains the transcription. For each time range for which the platform finds spoken words, it returns an object that contains the fields below. If the platform doesn't find any spoken words, the `data` field is set to `null`. ## 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. ### 404 Not Found Error The specified resource does not exist. - `code` (string, optional) — Represents 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. ## Types ### IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaSystemMetadata System-generated metadata about the video. - `duration` (double, optional) - `filename` (string, optional) - `fps` (double, optional) - `height` (integer, optional) - `width` (integer, optional) ### UserMetadataValue A single metadata value: a string, a number, a boolean, or an array of strings. The platform stores the value with the type you send. It rejects a nested object and an array that contains anything but strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991) and any identifier you want preserved verbatim as a string. ### HLSObject The platform returns this object only for the videos that you uploaded with the `enable_video_stream` parameter set to `true`. - `video_url` (string, optional) — A string representing the URL of the video. You can then use this URL to access the stream over the HLS protocol. - `thumbnail_urls` (list of string, optional) — An array containing the URL of the thumbnail. - `status` (enum, optional) — A string representing the encoding status of the video file from its original format to a streamable format. **Values**: - `PROCESSING`: Video is currently being encoded and is not yet ready for streaming - `COMPLETE`: Encoding has successfully finished and the video is ready for streaming - `CANCELED`: Encoding was manually canceled before completion - `ERROR`: An error occurred during the encoding process - Allowed values: `PROCESSING`, `COMPLETE`, `CANCELED`, `ERROR` - `updated_at` (string, optional) — A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the encoding status was last updated. ### IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaEmbedding Contains the embedding and the associated information. The platform returns this field when the `embedding_option` parameter is specified in the request. - `model_name` (string, optional) — The name of the video understanding model used to create the embedding. - `video_embedding` (IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaEmbeddingVideoEmbedding, optional) — An object that contains the embeddings. ### TranscriptionDataItems - `start` (double, optional) — The start of the time range, expressed in seconds. - `end` (double, optional) — The end of the time range, expressed in seconds. - `value` (string, optional) — Text representing the spoken words within this time range. ### IndexesIndexIdVideosVideoIdGetResponsesContentApplicationJsonSchemaEmbeddingVideoEmbedding An object that contains the embeddings. - `segments` (list of VideoSegment, optional) — An array of objects that contains the embeddings for each individual segment. ### VideoSegment An object that contains the video embedding and its start time. Each segment is between 2 and 10 seconds. - `float` (list of double, optional) — An array of floating point numbers representing the embedding. You can use this array with cosine similarity for various downstream tasks. Note that the example response was truncated for brevity. - `start_offset_sec` (double, optional) — The start time in seconds from the beginning of the file. - `end_offset_sec` (double, optional) — The end time in seconds from the beginning of the file. - `embedding_option` (string, optional) — The type of the embedding. - `embedding_scope` (string, optional) — The scope of the video embedding. ## Examples **Response** ```json { "_id": "61e17be5777e6caec646fa07", "asset_id": "6298d673f1090f1100476d4c", "created_at": "2022-01-14T13:34:29Z", "updated_at": "2022-01-14T13:34:29Z", "indexed_at": "2022-01-14T14:05:55Z", "system_metadata": { "duration": 3747.841667, "filename": "IOKgzkakhlk.mp4", "fps": 29.97002997002997, "height": 360, "width": 482 }, "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true }, "hls": { "video_url": "https://d2cp8xx7n5vxnu.cloudfront.net/6298aa0b535db125bf6e1d10/64902a28fb01304dd47be3cb/stream/c924f34a-144e-41df-bf2a-c693703fa134.m3u8", "thumbnail_urls": [ "https://d2cp8xx7n5vxnu.cloudfront.net/6298aa0b535db125bf6e1d10/64902a28fb01304dd47be3cb/thumbnails/c924f34a-144e-41df-bf2a-c693703fa134.0000001.jpg" ], "status": "COMPLETE", "updated_at": "2024-01-16T07:59:40.879Z" }, "embedding": { "model_name": "marengo3.0", "video_embedding": { "segments": [ { "float": [ -0.04747168, 0.030509098, 0.032282468 ], "start_offset_sec": 0, "end_offset_sec": 7.5666666, "embedding_option": "visual", "embedding_scope": "clip" } ] } }, "transcription": [ { "start": 0, "end": 0.32, "value": "Good" }, { "start": 0.32, "end": 0.68, "value": "evening." } ] } ``` **SDK Code** ```python import requests url = "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c" querystring = {"transcription":"true"} headers = {"x-api-key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos/6298d673f1090f1100476d4c?transcription=true")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" 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() ```