What is a video object?
The video object in reference to api.video is a container of sort (not to be confused with video container) for the video that you upload.
The video object has properties and metadata that you can create and update, below are the attributes that are available for the video object.
Video Object Parameters
The video object is a powerful feature that you can utilize in order to achieve many use cases by leveraging the parameter that is offered with the object.
The video ID is a unique identifier for the video object that you create. Use it to identify a specific video object through the API. For example, you need the video ID when you upload a video, retrieve a video object, or update a video object. For a full list of API operations, check out the
/videos endpoint in the API reference.
You can retrieve the video ID for a video object via these methods:
- when creating a video object, the API returns the
videoIdin the response payload
- when listing all video objects associated with your current workspace, the API returns the
videoIdfor each video object in the response payload
You can also retrieve video IDs through the Dashboard - visit the Videos page to see each video in your workspace and the video IDs associated with them.
The title of the video. The title will display on the embedded player when the controls are present in the video. You can set the title on creation or update it later.
The video description. Will give you the description of the video. You can set the description on video object creation or update it later.
Source: Copy a Video from your workspace
You can either add a video already on the web, by entering the URL of the video, or you can also enter the videoId of one of the videos you already have on your api.video account, and this will generate a copy of your video. Creating a copy of a video can be especially useful if you want to keep your original video and trim or apply a watermark onto the copy you would create.
Public: Video Access Management
On creation, the video can either be public or private. If the video is set to public
true, the url of the video can be accessed by anyone that has the url, however, you can secure the video and make it private. Set the public parameter to
false to convert the video to private and limit access to the video url. You can get started with Video Access Management here.
Panoramic: Upload 360-degree Videos
api.video allows you to upload panoramic videos (or 360-degree videos). When you upload a panoramic video, make sure that on the object creation, the panoramic parameter value should be set to
true. By default the value is
Mp4support: Video Download by Users
The parameter will allow your users to have a download button on the player.
PlayerId: Add Video Player Theme
As you can create different player themes, you can pass in the player theme that will be used with this specific video.
In order to sort your videos, you can leverage the tags parameter. The video object can have an array of tags, when you retrieve all the videos, you can filter the videos by tags and get only the videos you've tagged with a specific value.
Metadata: Pass Data with the Video to The Front-end
A powerful feature that allows you to pass in data with the video object. It is a list of key-value pairs that you use to provide metadata for your video. These pairs can be made dynamic, allowing you to segment your audience.
Metadata values can be
key:value where the values are predefined, but Dynamic metadata allows you to enter any value for a defined key. To define a dynamic metadata pair use:
The double underscore on both sides of the value allows any variable to be added for a given video session. Added the URL you might have:
This video session will be tagged as watched by
ExampleData - allowing for an in-depth analysis of how each viewer interacts with the videos.
Get more details about the usage of the metadata feature here
Clip: Trim the Video
Allows you to trim the video by passing in the segment that you would like to trim. You can pass in the start time and end time of the segment. Note, that you can only clip a video once the video object is being created, you cannot update the object later on. You can find this tutorial to learn more.
Allows you to add a watermark to the video from your pre-uploaded watermarks. Note, that the watermark can only be added on the video object creation, you will not be able to update a video object watermark.
Was this page helpful?