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 Video description that should be displayed on YouTube.
PHP PAYLOAD EXAMPLE
$payload = '{
    "youtube": {
        "title": "My New Video",
        "description": "This is a great description."
    },
    "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 -> Get all templates
  • 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.

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: Get all templates

ENDPOINT
  • GET
    /v1/templates

Description

Lists all the available templates in your account.

Returns

Returns a JSON representation of the video templates, or an error.

Example

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

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 -> Get all projects
  • GET
    /v1/projects/:id -> Get one project

Projects: Get all projects

ENDPOINT
  • GET
    /v1/projects

Description

Lists all the available projects in your account.

Returns

Returns a JSON representation of the video projects, or an error.

Example

CURL
curl https://api.bloxium.com/v1/projects \ -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 }, { "projectId": "5d8e07d6e82a28452b1e4503", "title": "Demo Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": "https://...", "metadata": { ... } } ] }

Projects: Get one project

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 } }