Upload from the local file system
In this guide you'll learn how to upload a video file from the local file system to the API service. For a description of each field in the request and response, see the API Reference > Create a video indexing task page.
Note that, although the example code in this guide is written in Python and Node.js, the API is compatible with most programming languages, and you can also use Postman or other REST clients to send requests and view responses.
Prerequisites
- Your video must meet the following requirements:
- Video resolution: must be greater or equal than 360p and less than 1080p (FHD)
- Duration: must be between 10 seconds and 2 hours (7,200s)
If you require different options, send us an email atsupport[at]twelvelabs.io
.
- A valid Twelve Labs account. For details about creating an account and retrieving your API key, see the Authentication page.
- You’re familiar with the concepts that are described on the Quickstart page.
- You’ve created an index, and the unique identifier of your index is stored in a variable named
INDEX_ID
. For details, see the Creating indexes page.
Recommendations
- For consistent search results, Twelve Labs recommends you upload 360p videos.
Procedure
-
Declare the
/tasks
endpoint:TASKS_URL = f"{API_URL}/tasks"
const TASKS_URL = `${API_URL}/tasks`
-
Read your video file. Open a stream, making sure to replace the placeholders surrounded by
<>
with your values:file_name = "<YOUR_FILE_NAME>" file_path = "<YOUR_FILE_PATH>" file_stream = open(file_path,"rb")
const file_path = '<YOUR_FILE_PATH>' const file_stream = fs.createReadStream(file_path)
-
If you're using Python, store the index ID and the language of your video in a dictionary named
data
and the file to upload in an array namedfile_param
. If you're using Node.js, store the index, the language of the video, and the file to upload in a variable namedformData
of typeFormData
:data = { "index_id": INDEX_ID, "language": "en" } file_param = [ ("video_file", (file_name, file_stream, "application/octet-stream")),]
let formData = new FormData() formData.append('INDEX_ID', INDEX_ID) formData.append('language', 'en') formData.append('video_file', file_stream)
-
Upload your video. Call the
/tasks
endpoint and store the result in a variable namedresponse
:response = requests.post(TASKS_URL, headers=headers, data=data, files=file_param)
const { data: response } = await axios.post( TASKS_URL, formData, { "headers": { "Content-Type": "multipart/form-data", "x-api-key": process.env.API_KEY } } )
-
Store the ID of your task in a variable named
TASK_ID
and print the status code and response:TASK_ID = response.json().get("_id") print (f"Status code: {response.status_code}") pprint (response.json())
const TASK_ID = response._id console.log(`Status code: ${resp.status}`) console.log(response)
The output should look similar to the following one:
Status code: 200 { "_id": "6396bf71a62a34ad8ad3ed20" }
-
(Optional) You can use the
/tasks/{_id}
endpoint to monitor the indexing process. Wait until the status shows asready
:TASK_STATUS_URL = f"{API_URL}/tasks/{TASK_ID}" while True: response = requests.get(TASK_STATUS_URL, headers=headers) STATUS = response.json().get("status") if STATUS == "ready": break time.sleep(10)
const TASK_STATUS_URL = `${API_URL}/tasks/${TASK_ID}` const uploadResp = await new Promise((res) => { const interval = setInterval(async () => { const { data: response } = await axios.get( TASK_STATUS_URL, { headers: { "x-api-key": API_KEY } } ); if (response.status == "ready") { clearInterval(interval); res(response); } }, 1000); });
-
(Optional) Store the unique identifier of your video in a variable named
VIDEO_ID
:VIDEO_ID = response.json().get('video_id')
const VIDEO_ID = uploadResp.video_id
-
(Optional) Print the unique identifier of your video, the status code, and the response:
print (f"Status code: {STATUS}") print(f"VIDEO ID: {VIDEO_ID}") pprint (response.json())
console.log(`Status code: ${uploadResp.status}`) console.log(`VIDEO_ID: ${VIDEO_ID}`) console.log(uploadResp);
The output should look similar to the following one:
Status code: 200 VIDEO ID: 6391c8a669ff3402ec515aba {'_id': '6391c89afb14854546891276', 'created_at': '2022-12-08T11:20:58.859Z', 'estimated_time': '2022-12-08T11:34:54.585Z', 'index_id': '6391c88bfb14854546891275', 'metadata': {'duration': 810.84, 'filename': 'best-racing-moments.mp4', 'height': 480, 'width': 854}, 'status': 'ready', 'type': 'index_task_info', 'updated_at': '2022-12-08T11:34:50.474Z', 'video_id': '6391c8a669ff3402ec515aba'}
Notes
- For details about the possible statuses, see the API Reference > Tasks page.
- You can also use webhooks to monitor the status of the indexing process. For details, see the Using webhooks section.
Updated 1 day ago