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


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" ) );

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 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 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": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/1-5c656c2bdd607.jpg",
                        "captionDisplay": "block",
                        "caption": "Your first caption here"
                    },
                    {
                        "image": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/2-5c656c2bdd7d4.jpg",
                        "captionDisplay": "block",
                        "caption": "Your second caption here"
                    },
                    {
                        "image": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/3-5c656c2bdd8df.jpg",
                        "captionDisplay": "block",
                        "caption": "Your third caption here"
                    },
                    {
                        "image": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/4-5c656c2bdd9d1.jpg",
                        "captionDisplay": "block",
                        "caption": "Your fourth caption here"
                    },
                    {
                        "image": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/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": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/headshot-5c7e76d02dd79.jpg"
            }
        ],
        "watermarkImage": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/images/logo.png",
        "watermarkText": "Made with MakerMoon",
        "backgroundImage": "https://www.bloxium.com/temp/templates/5c3426e31416e835a78b4568/5c7eaa88e82a2867cb3d4703/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": "Default Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": false // Will be populated once the video is generated } }

Webhook

When done, the 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": "Default Template", "creationTime": "2019-09-27 09:00:06" "values": {...} }, { "templateId": "5d8e07d6e82a28452b1e4503", "title": "Default 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": "Default 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": "Default Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": "https://..." // false if no video was generated }, { "projectId": "5d8e07d6e82a28452b1e4503", "title": "Default Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": "https://..." } ] }

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": "Default Template", "creationTime": "2019-09-27 09:00:06", "videoUrl": "https://..." // false if no video was generated } }