Video APIs to Automate your Video Workflow – API Version v3

This blog suggests a workflow for automating the video workflow for your website using VdoCipher API v3. Complete details and Sample Codes for the API can be found in the Server API Docs.

Our APIs are designed to give you programmatic access to VdoCipher’s service, so that you can scale your service by automating the video streaming workflow on your site. Our APIs make it possible for you to create programmed pipelines to automate your business operations. In this blog, you will find APIs covering most important video actions.

While the video upload and video management operations can be performed just as easily via the VdoCipher dashboard, the OTP generation needs to happen programmatically for maximum video security.

You would need to authenticate all API requests with your API keys. The Authorization header will be used to provide the API key.

Authorization: Apisecret a1b2c3d4e5

All values in the sample codes are presented in the following format – {{value}}. Replace them with the value from your website backend.

You can design your workflow with our API is as follows:

  1. Add videos to your Account
  2. Customize your Video
  3. Playback authentication and OTP Generation

Add Videos to Your Account

The upload API is especially built for users who prefer to automate their workflows around video ingestion. The upload API enables you to provide a dashboard to your content providers such that they can directly upload videos to your VdoCipher account. Alternatively the Import Video API enables you to import videos using URLs.

This is a two step process. In the first step, you obtain temporary authentication to upload a video. This also requires that you specify a title for the video in advance. In the second step the content-owner (in this case your website/app), uses the authorization tokens received from Step 1 to upload it directly to your account.

Step 1: Obtain Upload Credentials

API endpoint to send HTTP PUT request to receive upload credentials is https://dev.vdocipher.com/api/videos. To initiate video upload you would need to pass the title of video as a query string:

https://dev.vdocipher.com/api/videos?title=videotitle

This returns a JSON object, which authorizes you to initiate upload. You may upload the file yourself, or can pass the upload credentials to your content providers who can then upload videos to your account. The JSON object looks like this:

The values received in upload policy are presented in the following format – {{policy}}

{
    "clientPayload": {
        "policy": "{{format}}",
        "key": "{{key}}",
        "x-amz-signature": "{{x-amz-signature}}",
        "x-amz-algorithm": "{{x-amz-algorithm}}",
        "x-amz-date": "{{x-amz-date}}",
        "x-amz-credential": "{{x-amz-credential}}",
        "uploadLink": "https://{s3-bucket-url}}.amazonaws.com"
    },
    "videoId": "1234567890"
}
Step 2: Upload File using Obtained Credentials

The upload policy credentials JSON is used for uploading files to your VdoCipher account, using an HTTP POST request. You would create a form-data object containing the following:

  • policy
  • key
  • x-amz-signature
  • x-amz-algorithm
  • x-amz-date
  • x-amz-credential

All the above are received as part of API server response in Step 1. The request for upload credentials also returns the uploadLink URL.

In addition to the above parameters, the following need to be added:

  • success_action_status – 201
  • success_action_redirect – Set this to empty string if you do not have a specific redirect page
  • file – This is the path to the file on your content provider’s device. The file should always be appended to the end of the upload policy.

The HTTP POST request is to be made to the endpoint returned in step 1:

https://{s3-bucket-url}}.amazonaws.com'
Step 3: Check Video Status

To find the status of your video you can send an HTTP GET request to

https://dev.vdocipher.com/api/videos/{{videoID}}

The following are the status values that may be returned:

  • Pre-Upload – Upload policy has been returned (Step 1 is successful), but file is not yet uploaded (Step 2 not yet complete)
  • Queued – Video has been uploaded and is being encoded and encrypted (Step 1 and Step 2 complete)
  • ready – Video is ready for playback

Apart from video status, the video contains all details of the video. These include title, description, video upload time, video length, poster image URLs and associated tags.

{
    "id": "1234567890",
    "title": "zoo.mp4",
    "description": "",
    "upload_time": 15197xxxxx,
    "length": 25,
    "status": "ready",
    "posters": [
        {
            "width": 854,
            "height": 480,
            "posterUrl": "https://d1z78r8i505acl.cloudfront.net/poster/123456.480.jpeg"
        },
        {
            "width": 427,
            "height": 240,
            "posterUrl": "https://d1z78r8i505acl.cloudfront.net/poster/123456.240.jpeg"
        }
    ],
    "tags": [
        "abcd",
        "mnop"
    ]
}

Import Video from URL

Alternatively you may import videos directly from a URL or cloud service or a different video streaming provider. Most video streaming service providers provide API access through which you may access the original video file, to initiate video import.

Send an HTTP PUT request to the API endpoint

https://dev.vdocipher.com/api/videos/importUrl

A JSON Object containing the URL needs to be passed:

{
  "url": "{{URLString}}"
}

Customize your Videos

Our video management APIs enable you to categorize your videos according to tags for easy access. You can use a tag-based classification system to retrieve list of similar videos. This API also enables you to obtain and change the poster images of videos. Details of videos, such as encoding status, can also be found using this API.

Add new Poster Image

Poster image is the image that is shown to the viewer before a video is loaded. By default, a shot from the video at a random time is taken and converted into posters of different sizes. It may be customized to better appeal to the viewers. You can use the API to auto upload new poster images.

To use this API, send an HTTP POST request to the API endpoint:

https://dev.vdocipher.com/api/videos/{{videoID}}/files

The image file is to be sent as part of the form-data.

Add Tags

Tagging is the process of adding searchable keywords to the video. These keywords can be very helpful to retrieve any video from your dashboard or from the API. The keywords can be the name of persons in the video or the name of the collection that it belongs to. You can add multiple tags to the same video. This makes it possible for a single video to exist in multiple tags.

You would need to send an HTTP POST request to:

https://dev.vdocipher.com/api/videos/tags

The POST request body should include an array of videos, and an array of tags:

{
  "videos":[
    "{{videoID1}}",
    "{{videoID2}}"
    ],
  "tags":[
    "{{tag1}}",
    "{{tag2}}"
    ]
}
Enable tag based search

You can search for videos with a particular tag by passing the tag query parameter. The API endpoint to which you should send HTTP GET request is:

https://dev.vdocipher.com/api/videos?tag={{videoTag}}

If you are using this to display list of videos for general users to your website we recommend using it with a caching layer with large expiry time. This is because the video management APIs have soft rate-limits for number of API calls to the server.

Playback authentication with OTP generation

OTP are tokens generated using VdoCipher API which are required to authorize video playback. The OTP must always be generated on a back-end server. The generated OTP must then be sent to the website front-end. In the website front-end the OTP is used as part of the video embed code.

For valid requests the API server returns a JSON containing the otp and playbackInfo, both of which parameters you would then need to send to your website front-end as part of embed code.

To generate the OTP you need to send an HTTP POST request to the API Endpoint, with the required OTP request Header and the optional OTP request Body. This article is specific to API Version v3.

API endpoint to retrieve OTP is

https://dev.vdocipher.com/api/videos/{videoID}/otp

The API call would return a JSON object with OTP and playback info, which you would be sending to your website front-end for video playback:

{
    "otp": "1234567890z26y25x24",
    "playbackInfo": "a1b2c3d4e5f6h7"
}

Video Player Embed Code

Your website backend needs to send the OTP and playbackInfo to the site frontend, to authorize video playback. More details on the player embed code can be found in the VdoPlayer Reference.

<div id="embedBox" style="width:1280px;max-width:100%;height:auto;"></div>
<script>
 (function(v,i,d,e,o){v[o]=v[o]||{}; v[o].add = v[o].add || function V(a){ (v[o].d=v[o].d||[]).push(a);};
  if(!v[o].l) { v[o].l=1*new Date(); a=i.createElement(d), m=i.getElementsByTagName(d)[0];
  a.async=1; a.src=e; m.parentNode.insertBefore(a,m);}
  })(window,document,"script","https://cdn-gce.vdocipher.com/playerAssets/1.6.4/vdo.js","vdo");
  vdo.add({
    otp: "REPLACE WITH OTP",
    playbackInfo: "REPLACE WITH playbackInfo",
    theme: "9ae8bbe8dd964ddc9bdb932cca1cb59a",
    container: document.querySelector( "#embedBox" ),
  });
</script>

You may wish to change the id of the global div, from embedBox to something more unique. For instance you may append a random number to embedBox, so that each video player displayed on your page has a unique id.

Find more details about VdoCipher’s DRM infrastructure and our integration of Widevine DRM for Hollywood-grade security.

You may also like...