API Documentation

The Bloxium API is organized around REST. Our API has predictable resource-oriented URLs, accepts raw JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

  • Requests should use the HTTPS protocol.
  • Requests are sent to our parent domain: api.bloxium.com.
BASE URL
https://api.bloxium.com

Getting Started

1. Testing the API

How to send test video generation requests to the API, from your account dashboard.

Click here to create a template.

2. About Template JSON

How to create JSON from templates, and how to customize your template's JSON.

Authentication

Bloxium API credentials consist of a single username and password, used for "Basic Authentication" when making requests to the API.

To obtain your API credentials, login to your account, and go to the API section.

AUTHENTICATION REQUEST - CURL
curl https://api.bloxium.com/v1/templates \
-u YOUR_API_USERNAME:YOUR_API_PASSWORD
AUTHENTICATION REQUEST - PHP
$url = 'https://api.bloxium.com/v1/templates';
$username = 'YOUR_API_USERNAME';
$password = 'YOUR_API_PASSWORD';

$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_TIMEOUT, 30 );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
curl_setopt( $ch, CURLOPT_USERPWD, $username . ':' . $password );
$response = json_decode( curl_exec( $ch ), TRUE );
$statusCode = curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );

print_r( $response );

Webhook

To receive notifications from the API, you must setup your default webhook in the API settings section of your account.

When a video generation is done, the system will send a POST request to your webhook, with details about the generated project and the URL of the generated video.

Name Description
event The event type: record.success
project The project associated with the generated video.
project.projectId The projectId.
project.videoUrl The direct URL to the video file.
project.youtubeId The YouTube id of your video.
project.metadata The project's metadata you've assigned when sending your video generation request.
WEBHOOK EXAMPLE - PHP
if ( $_SERVER[ 'REQUEST_METHOD' ] === 'POST' ) {
    $apiJson = file_get_contents( 'php://input' );
    $apiNotification = json_decode( $apiJson, TRUE );
    if ( $apiNotification[ 'event' ] === 'record.success' ) {
        $videoUrl = $apiNotification[ 'project' ][ 'videoUrl' ];
        // Download video here
    }
}
WEBHOOK EXMAPLE - NODE.JS
const http = require( "http" );
http.createServer( ( request, response ) => {
    if ( request.method === "POST" ) {
        var apiJson = "";
        var apiNotification;
        request.on( "data", ( chunk ) => {
            apiJson += chunk.toString();
        });
        request.on( "end", () => {
            apiNotification = JSON.parse( apiJson );
            if ( apiNotification.event === "record.success" ) {
                var videoUrl = apiNotification.project.videoUrl;
                // Download video here
            }
            response.end();
        });
    }
} ).listen( 80 ); // 80 for http, 443 for https
console.log( "server ready" );
WEBHOOK EXMAPLE - NODE.JS + EXPRESS
const express = require( "express" );
const app = express();
const port = 80; // 80 for http, 443 for https
app.post( "/webhook", ( request, response ) => {
    if ( request.method === "POST" ) {
        var apiJson = "";
        var apiNotification;
        request.on( "data", ( chunk ) => {
            apiJson += chunk.toString();
        });
        request.on( "end", () => {
            apiNotification = JSON.parse( apiJson );
            if ( apiNotification.event === "record.success" ) {
                var videoUrl = apiNotification.project.videoUrl;
                // Download video here
            }
            response.end();
        });
    }
});
app.listen( port, () => console.log( "server ready" ) );

Downloading Videos

WARNING : You have 5 days to download the generated video on your system. After this period, the generated video will be deleted.

Activate the "Hosted Videos" feature on your account to get a permanent video URL. Contact-us to activate the feature on your account.

Multiple Webhooks

You can have multiple webhooks. This can be useful if you are using the API for multiple applications, hosted on different servers.

Enter multiple comma separated webhook urls in the API settings section of your account. Example:
https://www.webhook-id-0.com,https://www.webhook-id-1.com

When sending a video generation request, you can specify the webhook id the system should use. The first webhook in your list has an id of 0. Not specifying any webhook id will use the first webhook in your list.

PHP PAYLOAD EXAMPLE
$payload = '{
    "webhookId": 1,
    "values": {
        ...
    }
}';

YouTube

You can ask the API to automatically upload your generated videos to your YouTube channel.

First, you must authorize Bloxium to manage your YouTube videos. To start the authorization process, go to the YouTube section of your API account.

The YouTube id of your uploaded video will be returned to your webhook.

YouTube Upload Options

To activate the YouTube upload, you must add a "youtube" object in your payload JSON. The "youtube" object accepts the following values:

Name Description
title
( required )
Video title that should be displayed on YouTube.
description
( optional )
Video description that should be displayed on YouTube.
channelId
( optional )
The channelId where the video should be uploaded. If not specified, the video will be uploaded to your default channel.
privacyStatus
( optional )
The privacy status of the video. Valid values are "private" or "public". Default is public.
PHP PAYLOAD EXAMPLE
$payload = '{
    "youtube": {
        "title": "My New Video",
        "description": "This is a great description.",
        "channelId": "UCKVLoEu5NG3xjBHLwK34BpB",
        "privacyStatus": "public"
    },
    "values": {
        ...
    }
}';

Errors

  • Successful requests will return the http response code 200.
  • Errors will return the http response code 400.

An error will also send back a JSON string containing the error message:

Templates

This resource represents video templates. A video template is a starting point you can use to create a new video project. Click here to create a template.

ENDPOINTS
  • POST
    /v1/templates/:id/record -> Generate a video
  • GET
    /v1/templates/:id -> Get one template

Templates: Generate a video

ENDPOINT
  • POST
    /v1/templates/:id/record

Description

Creates a video. Applies the posted JSON values to the templateId, and renders the video. Rendering a video takes around 200 seconds. When done, calls the webhook url that is set in your API settings. This creates a new project available in your account.

Parameters

Name Description
values
( required )
A JSON string representing the custom values you want to apply to the template. Urls pointing to images should return a valid image content type header.
webhookId
( optional )
The id of the webhook the system should call when the video generation is completed. Needed only if you use multiple webhooks. Look at the webhook section for more details.
metadata
( optional )
Use this parameter to attach additional key-value data to the generated video project. For example, if you are generating real estate videos, you could attach a propertyId corresponding to a unique identifier from your system. Your metadata will be part of the data sent back to your webhook.
audioId
( optional )
Set this value to the audioId you want to apply to your video. Audio files can be uploaded from your account. Once an audio file is uploaded use the generated audioId.

Returns

Returns a JSON representation of the newly created video project, or an error.

Example

PHP
$url = 'https://api.bloxium.com/v1/templates/5d8e07d6e82a28452b1e4503/record';
$username = 'YOUR_API_USERNAME';
$password = 'YOUR_API_PASSWORD';
$payload = '{
    "values": {
        "scenes-LOCKED": [
            {
                "slideshow": [
                    {
                        "image": "images/1-5c656c2bdd607.jpg",
                        "captionDisplay": "block",
                        "caption": "Your first caption here"
                    },
                    {
                        "image": "images/2-5c656c2bdd7d4.jpg",
                        "captionDisplay": "block",
                        "caption": "Your second caption here"
                    },
                    {
                        "image": "images/3-5c656c2bdd8df.jpg",
                        "captionDisplay": "block",
                        "caption": "Your third caption here"
                    },
                    {
                        "image": "images/4-5c656c2bdd9d1.jpg",
                        "captionDisplay": "block",
                        "caption": "Your fourth caption here"
                    },
                    {
                        "image": "images/5-5c656c2bddacc.jpg",
                        "captionDisplay": "block",
                        "caption": "Your fifth caption here"
                    }
                ]
            },
            {
                "title": "Anita Boringer",
                "subtitle": "Palm Beach County Realtor<br>493-235-3898<br>anitab@yourdomain.com",
                "imageDisplay": "block",
                "image": "../images/headshot-5c7e76d02dd79.jpg"
            }
        ],
        "watermarkImage": "images/logo.png",
        "watermarkText": "Made with Bloxium",
        "backgroundImage": "../images/5ae1d5c41416e81fb48b458e.jpg",
        "watermarkDisplay": "flex",
        "watermarkImageDisplay": "none",
        "watermarkTextDisplay": "block"
    }
}';

$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_TIMEOUT, 30 );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
curl_setopt( $ch, CURLOPT_USERPWD, $username . ':' . $password );
curl_setopt( $ch, CURLOPT_POST, 1 );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $payload );
$response = json_decode( curl_exec( $ch ), TRUE );
$statusCode = curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );

print_r( $response );
RESPONSE
{ "status": "success", "data": { "projectId": "5d8e07d6e82a28452b1e4503", "title": "Demo Template", "creationTime": "2019-09-27 09:00:06", "metadata": { ... } // Present only if there is metadata } }

Webhook

When done, the default webhook you've set in your account, will be called using the POST method. Check the webhook section for more details.

Templates: Generate a preview

ENDPOINT
  • POST
    /v1/templates/:id/preview

Description

Use this endpoint to create a preview of the video that will be generated. Applies the posted JSON values to the templateId, and returns an iframe URL you can use to render the preview in your application. Rendering a preview takes around 5 to 7 seconds.

You should call this endpoint everytime you want to preview new custom values. Then refresh your iframe's src attribute with the new preview url in the response.

Make sure you activate the preview feature in your template's settings.

Parameters

Name Description
values
( required )
A JSON string representing the custom values you want to apply to the template. Urls pointing to images should return a valid image content type header.

Returns

Returns a JSON object containing the URL you should use to display the preview in an iframe, or an error.

Example

PHP
$url = 'https://api.bloxium.com/v1/templates/5d8e07d6e82a28452b1e4503/preview';
$username = 'YOUR_API_USERNAME';
$password = 'YOUR_API_PASSWORD';
$payload = '{
    "values": {
        "scenes-LOCKED": [
            {
                "slideshow": [
                    {
                        "image": "images/1-5c656c2bdd607.jpg",
                        "captionDisplay": "block",
                        "caption": "Your first caption here"
                    },
                    {
                        "image": "images/2-5c656c2bdd7d4.jpg",
                        "captionDisplay": "block",
                        "caption": "Your second caption here"
                    },
                    {
                        "image": "images/3-5c656c2bdd8df.jpg",
                        "captionDisplay": "block",
                        "caption": "Your third caption here"
                    },
                    {
                        "image": "images/4-5c656c2bdd9d1.jpg",
                        "captionDisplay": "block",
                        "caption": "Your fourth caption here"
                    },
                    {
                        "image": "images/5-5c656c2bddacc.jpg",
                        "captionDisplay": "block",
                        "caption": "Your fifth caption here"
                    }
                ]
            },
            {
                "title": "Anita Boringer",
                "subtitle": "Palm Beach County Realtor<br>493-235-3898<br>anitab@yourdomain.com",
                "imageDisplay": "block",
                "image": "../images/headshot-5c7e76d02dd79.jpg"
            }
        ],
        "watermarkImage": "images/logo.png",
        "watermarkText": "Made with Bloxium",
        "backgroundImage": "../images/5ae1d5c41416e81fb48b458e.jpg",
        "watermarkDisplay": "flex",
        "watermarkImageDisplay": "none",
        "watermarkTextDisplay": "block"
    }
}';

$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_TIMEOUT, 30 );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
curl_setopt( $ch, CURLOPT_USERPWD, $username . ':' . $password );
curl_setopt( $ch, CURLOPT_POST, 1 );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $payload );
$response = json_decode( curl_exec( $ch ), TRUE );
$statusCode = curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );

print_r( $response );
RESPONSE
{ "status": "success", "data": { "preview": { "url": "https://www.bloxium.com/editor/save/alias-values-api-preview/5d8e07d6e82a28452b1e4503/65ec9bc6e82a2831dc233df2/"" } } }

Webhook

Your webhook is not called for this endpoint.

Displaying the preview

HTML / CSS
<style>
    iframe {
        --preview-width: 500px; /* Preview width */
        --preview-aspect-ratio: calc( 16/9 ); /* Template ratio: 1/1, 16/9 or 9/16 */
        width: var( --preview-width );
        height: calc( var( --preview-width ) / var( --preview-aspect-ratio ) + 50px );
        overflow: hidden;
        border: 1px solid #333333;
    }
</style>
<iframe src="***** PREVIEW URL RETURNED BY API *****"></iframe>

Templates: Get one template

ENDPOINT
  • GET
    /v1/templates/:id

Description

Retrieves the template associated to the template id in the request URL.

Returns

Returns a JSON representation of the template, or an error.

Example

CURL
curl https://api.bloxium.com/v1/templates/5d8e07d6e82a28452b1e4503 \ -u YOUR_API_USERNAME:YOUR_API_PASSWORD
RESPONSE
{ "status": "success", "data": { "templateId": "5d8e07d6e82a28452b1e4503", "title": "Demo Template", "creationTime": "2019-09-27 09:00:06", "values": {...} } }

Projects

This resource represents video projects.

ENDPOINTS
  • GET
    /v1/projects/:id -> Get one project

Projects: Get one project

Contact-us to unlock this endpoint on your account.

ENDPOINT
  • GET
    /v1/projects/:id

Description

Retrieves the project associated to the project id in the request URL.

Returns

Returns a JSON representation of the project, or an error.

Example

GET /v1/projects
curl https://api.bloxium.com/v1/projects/5d8e07d6e82a28452b1e4503 \ -u YOUR_API_USERNAME:YOUR_API_PASSWORD
RESPONSE
{ "status": "success", "data": { "projectId": "5d8e07d6e82a28452b1e4503", "title": "Demo Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": "https://...", // Present only if the video was generated "metadata": { ... } // Present only if there is metadata } }