Topvid API Documentation
by elior

Topvid API Documentation

Overview

Topvid’s API splits into two major categories.

  1. Whitelabel API which is the API that allows an API client, to create users on his behalf, manage their credits and view their data.

  2. Personalized Video API with which you can create videos with dynamic content at scale. Example use cases: Sale offer video based on past purchases, invoice walk-through video, thank video after purchase, order status report video.

Different access points for each category require different permissions, visit Getting Started for more information about permissions.

Getting Started

Before we start

Before accessing any of Topvid’s API endpoints you have to obtain an access token.

Currently Topvid does not provide a way to generate access tokens, if you want one please contact alex@topvid.io.

Permissions

Most of Topvid’s api endpoints are restricted by permission types–meaning your access token will need a specific permission to access certain endpoints. The permission needed for each endpoint is specified in its designated documentation.

You can always call validate to see the permissions available for your access token.

Base Endpoint

All of the API call paths mentioned in this documentation are relative to the base endpoint https://video-maker.topvid.com/

Public Endpoint

This section documents the public API endpoints (requires no permission).

Glossary

Client - The entity making the API calls, owner of the access token.

Validate Access Token
GET /validate
Validate Access Token
GET /validate

This endpoint is used to check if your access token is still valid.

Request parameters

access_token
string required

The client access token

Responses

200 OK
Body
Object
valid_until
string

Validity expiration timestamp.

permissions
Array of string

Array containing all available permissions for this token.

Example
GET https://video-maker.topvid.com/api/validate?access_token=<your_access_token> HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "valid_until": "2018-07-31T23:59:59.067",
    "permissions": [
        "manage_users"
    ]
}
Whitelabel API

This documentation covers all the API calls available for Whitelabel API users.

Manage Users

This page documents the API endpoints for the tokens with the “manage_users” permission.

Glossary

Client - The entity making the API calls, owner of the access token.

User - The entities that are created and managed by the client.

Create New User
POST /create_user
Adding Credits to Existing User
POST /add_credits
User Report
GET /user_report
Create New User
POST /create_user

Authentication

This endpoint is used to create new users, under the control of the API access token owner.

Request parameters

access_token
string required

The client access token

uid
string required

Unique string to identify the user. You will use this identifier for other API calls.

credits
integer optional

Amount of credits the new user will start with, must be integer. If not supplied defaults to 0.

Default:
0

Responses

200 OK
Body
Object
new_user
string

The same UID that was supplied in the creation call.

credits
string

Amount of credits of the created user.

Example
POST https://video-maker.topvid.com/api/create_user?access_token=<your_access_token>&uid=2BaYeeT51qBMWH2o&credits=5 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "new_user": "2BaYeeT51qBMWH2o",
    "credits": "5"
}
Adding Credits to Existing User
POST /add_credits

Authentication

This endpoint is used the ADD credits to existing users.

Request parameters

access_token
string required

The client access token.

uid
string required

Identifier of the user to add credits to.

amount
integer required

Amount of credits to add to the existing user, must be an integer.

Responses

200 OK
Body
Object
user
string

UID of the user the action was applied to.

credits
integer

Updated amount of credits the user currently has.

Example
POST https://video-maker.topvid.com/api/add_credits?access_token=<your_access_token>&uid=2BaYeeT51qBMWH2o&amount=7 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "user": "2BaYeeT51qBMWH2o",
    "credits": 12
}
User Report
GET /user_report

Authentication

This endpoint generates a report for a given user, including the number of credit he currently has and the number of videos he already created.

Request parameters

access_token
string required

The client access token.

uid
string required

Identifier of the user to generate report of.

Responses

200 OK
Body
Object
user
string

UID of the user the action was applied to.

created_videos
integer

Amount of videos this user has created.

available_credits
integer

Amount of credits this user currently has.

Example
GET https://video-maker.topvid.com/api/user_report?access_token=<your_access_token>&uid=2BaYeeT51qBMWH2o HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "user": "2BaYeeT51qBMWH2o",
    "created_videos": 3,
    "available_credits": 9
}
Embedding the Video Builder

The following code should be used in order to embed the video builder in the front-end of your app.

<script src="//ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script type="text/javascript" src="https://video-maker.topvid.io/static/assets/js/whiteLabel.js"></script>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Karla">

<button type="button"
            id="TOPVID"
            class="btn btn-info btn-lg">
        Open Builder
</button>

<script type="text/javascript">
        $(function() {
            var topvid = new TopvidFrame({
                uid: '<==Replace This==>',
                apiKey: '<==Replace This==>',
                onReady: function onReady(videoUrl) {
                   //Add your code here
                    console.log('callback video url', videoUrl);
                }
            });
        });
    </script>
</body>
</html>
uid
string required

Identifier of the user this Video Builder is targetted to.

apiKey
string required

API key identifier of the client that owns the user this builder is targetted to.

Replacing the Button

You can replace the “Open Builder” button with your own button that is natively embedded in your app. Once a user will click this button an instance of TopVid’s Video Builder will be opened inside an <iframe>.

onReady Function

Once the user generates a video and is ready to use it, he will click on the “Use Video” button inside the Video Builder. Once the “Use Video” button is clicked the Video Builder will closed and a the onReady function will be called. The function will get the url of the video chosen by the user inside the videoUrl variable.

Use this function in order to embed the video created by the Video Builder in the flow of your app (for example post it to social network or create a video ad campaign).

Personalized Video API

This documentation covers all the API calls available for Personalized Video API users.

Create Videos

This page documents the API endpoints for the tokens with the “create_videos” permission.

Glossary

Client - The entity making the API calls, owner of the access token.

Create Video
POST /create_video
Create Video
POST /create_video

Authentication

This endpoint is used to create videos. Once the video is created (which takes about a minute) a POST call will be made to the callback uri you supplied when you received your access token.

Request parameters

access_token
string required

The client access token

video_json
string required

JSON with all of the video related content

template_version
integer required

Template version must match the video_json, if not, an error will be returned

vid
string optional

Unique id for this video, used to identify the video when the callback with the video url will be returned.

Responses

200 OK
Body
Object
vid
string

An automatically generated video unique id, or the one you supplied on the creation call.

Example
POST https://video-maker.topvid.com/api/create_video?access_token=<your_access_token>&video_json={<your_video_json>}&template_version=3&vid=first_user_video HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "vid": "first_user_video"
}
Success Callback

If the video has been created successfully, this JSON object will be sent to the callback uri you supplied.

Object
vid
string

Unique identifier of this video.

video_url
string

Downloadable mp4 url of this video.

full_thumbnail
string

Downloadable image url of this video.

scaled_thumbnail
string

Scaled version of the full thumbnail.

Example 1
{
    "vid": "first_user_video",
    "video_url": "https://s3.amazonaws.com/<....>.mp4",
    "full_thumbnail": "https://s3.amazonaws.com/<....>.jpg",
    "scaled_thumbnail": "https://s3.amazonaws.com/<....>.jpg"
}
Failed Callback

If the video you attempted to create failed for any reason, you will be returned the following JSON.

Object
failed
string

Indicating a failed video and will contain the vid (video identifier) associated with it.

Example 1
{
    "failed": "first_user_video"
}