Provide custom metadata

Metadata provides technical and contextual information about each video uploaded to the platform. By default, all the videos have the following metadata associated with them:

  • duration: The duration of the video, expressed in seconds
  • filename: The filename
  • fps: The number of frames per second
  • height: The height of the video
  • size: The size of the video file, expressed in KB
  • video_title: The title of the video (defaults to the file name)
  • width: The width of the video

Custom metadata is the ability to add more data to your videos. For example, you can add the following fields: channel, views, downloads, country of origin, language, and URL. This allows you to provide more detailed, specialized, or context-specific information.

Note the following about adding custom metadata to your videos:

  • You cannot override any of the predefined metadata
  • The values you provide must be of the following types: string, integer, float or boolean. If you want to store other types of data such as objects or arrays, you must convert your data into string values.


  • You’re familiar with the concepts that are described on the Platform overview page.
  • You’ve created at least one index, and the unique identifier of your index is stored in a variable named INDEX_ID. For details, see the Create indexespage.
  • You've uploaded a video, and the platform has finished indexing it. The unique identifier of your video is stored in a variable named VIDEO_ID. For details about uploading videos, see the Upload videos page.


  1. Construct the URL for providing custom video metadata based on the API_URL, INDEX_ID, and VIDEO_ID variables:
    VIDEOS_URL = f"{API_URL}/indexes/{INDEX_ID}/videos/{VIDEO_ID}"
    const VIDEOS_URL = `${API_URL}/indexes/${INDEX_ID}/videos/${VIDEO_ID}`
  2. Create the request body. You must provide your custom metadata using a dictionary named metadata. In the example code below, the metadata dictionary has four keys: views, downloads, language and country. The views and downloads keys are integers, and thecreation_date and country keys are strings:
    data = {
        "metadata": {
            "views": 12000,
            "downloads": 40000,
            "language": "en-us",
            "country": "USA"
    const data = {
      'metadata': {
        'views': 12000,
        'downloads': 40000,
        'language': 'en-us',
        'country': 'USA'
  3. To set your custom metadata, call the PUT method of the /indexes/{index-id}/videos/{video-id} endpoint:
    response = requests.put(VIDEOS_URL, headers=headers, json=data)
    const config = {
      method: 'put',
      url: VIDEOS_URL,
      headers: headers,
      data : data 
    const response = await axios(config)
  4. If successful, this method does not return anything in the response body. The example code below prints the status code:
    print (f"Status code: {response.status_code}")
    console.log(`Status code: ${response.status}`)
    The output should look similar to the following one:
    Status code: 200

Next Steps

Once you've added custom metadata to your videos, you can use it to filter the results returned by the /indexes/videos and /search endpoints.