Video APIs to Automate your Video Workflow – API Version v3

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.

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

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

{
  "videos":[
    "{{videoID1}}",
    "{{videoID2}}"
    ],
  "tags":[
    "{{tag1}}",
    "{{tag2}}"
    ]
}

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

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.