Video On Demand API

The Video On Demand (VOD) API lets you create videos with the Treepodia engine without using a data feed. You send the data for a video in an API request, and Treepodia calls your server back when the video is ready.

Using the API takes two steps:

1. Get an access token
2. Send a VOD request and receive the result on your callback URL

Authentication

Every API request must include an access token. Request a token from the authentication service with your Treepodia account credentials.

Endpoint

POST https://api.treepodia.com/rest/vod/v032021/auth
Content-Type: application/json

Request body

Field	Type	Required	Description
email	string	Yes	The email address of your Treepodia account.
password	string	Yes	The password of your Treepodia account.
expirationDate	number	No	When the token should expire, as a Unix timestamp in milliseconds. If omitted, the token expires after 2 weeks. Choose the expiration according to the level of security you need.

JSONcURL

{
  "email": "you@example.com",
  "password": "your-password",
  "expirationDate": 1646794257759
}

curl -X POST "https://api.treepodia.com/rest/vod/v032021/auth" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Successful response

{
  "status": "SUCCESS",
  "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expirationDate": 1646794257759
}

Use the accessToken value in your VOD requests until it expires, then request a new one.

Keep credentials on your server

Call the authentication service from your server, never from browser code. Your account email, password and access token should not be exposed to site visitors.

VOD request

Send a VOD request to ask Treepodia to create a video from a template and the data you provide.

Endpoint

POST https://api.treepodia.com/rest/vod/v032021/acc/{uuid}/requests
Content-Type: application/json

Replace {uuid} in the URL with your Treepodia account UUID.

Request body

All fields are required.

Field	Type	Description
accessToken	string	The token from the authentication service.
sku	string	The SKU (identifier) to assign to the video.
templateId	integer	The ID of the Treepodia template used to create the video.
requestData	object	The data the template needs to create the video. The fields depend on the template (for example firstName, lastName).
callback	object	Where and how Treepodia notifies you when the video is ready. See Callback.

callback object

Field	Type	Description
url	string	The URL on your server that Treepodia calls.
method	string	The HTTP method to use, for example "POST".
contentType	string	The content type of the callback body, for example "application/json".
body	string	A template for the callback body. Placeholders in it are replaced with the request's values (see Callback).

JSONcURL

{
  "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sku": "test25",
  "templateId": 0,
  "requestData": {
    "firstName": "Test",
    "lastName": "Last"
  },
  "callback": {
    "url": "https://yourdomain.com/vodcallback",
    "method": "POST",
    "contentType": "application/json",
    "body": "{\"requestId\":\"{requestId}\",\"videoUrl\":\"{videoUrl}\",\"status\":\"{status}\",\"errorMessage\":\"{errorMessage}\"}"
  }
}

curl -X POST "https://api.treepodia.com/rest/vod/v032021/acc/YOUR-UUID/requests" \
  -H "Content-Type: application/json" \
  -d @request.json

Where request.json contains the JSON body shown in the other tab.

Successful response

{ "id": 2, "status": "PENDING" }

The request is accepted and the video is being created. id identifies the request.

Callback

When the video is ready, Treepodia sends a request to your callback.url using the method, contentType and body you specified. Before sending, it replaces these placeholders in body:

Placeholder	Replaced with
{requestId}	The ID of the VOD request (the id returned when you sent it).
{videoUrl}	The URL of the created video.
{status}	The status of the request.
{errorMessage}	An error description, if the video could not be created.

With the body template from the example above, your server would receive:

{
  "requestId": "2",
  "videoUrl": "https://...",
  "status": "...",
  "errorMessage": "..."
}

Note

Because body is a string inside JSON, the quotes in it must be escaped as \", as in the example.