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.
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.
curl https://api.bloxium.com/v1/templates \ -u YOUR_API_USERNAME:YOUR_API_PASSWORD
$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. |
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
}
}
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" );
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.
$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. |
$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.
-
POST/v1/templates/:id/record -> Generate a video
-
GET/v1/templates/:id -> Get one template
Templates: Generate a video
-
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
$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 );
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
-
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. |
| audioId ( optional ) |
Set this value to the audioId you want to apply to your video preview. Audio files can be uploaded from your account. Once an audio file is uploaded use the generated audioId. |
Returns
Returns a JSON object containing the URL you should use to display the preview in an iframe, or an error.
Example
$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 );
Webhook
Your webhook is not called for this endpoint.
Displaying the preview
<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
-
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
Projects
This resource represents video projects.
-
GET/v1/projects/:id -> Get one project
Projects: Get one project
Contact-us to unlock this endpoint on your account.
-
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.