Guide

Introduction

This guide will explain how to use our public API to transcode video's.

Requirements

To be able to use our API, an authorization key is required. If you don't have an authorization key yet, fill in the contact form.

Without a key you won't be able to connect to our API.

Installation

Our RESTful API is openly available, and you are free to develop your own tools to make use of it. In addition, to simplify things, we have an PHP client library available for your convenience.

The client library could either be downloaded from GitHub and use included autoloader to load the files or installed through Composer. Click here if you've never used Composer.

Add the following to your composer.json file in the "require" section:

"issetbv/hatchery-api-client": "3.*"
            

If you've installed Composer on your machine and added the requirement to your projects composer.json go to your terminal of choice and run the command:

composer update
            

When using the composer.phar, use the following command instead.

php composer.phar update
            

API Client Usage

The process is simple, after installing with Composer, the bundle is autoloaded and ready for use.

$client  = new Hatchery\Client('http://admin.video-transcoder.com/', 'api-key');  
$payload = $client->createJobAddPayload('preset', 'ftp-in', 'ftp-out');         
            

An offset and duration (in seconds) can be added:

$payload->addDuration(10.050);
$payload->addOffset(10);
            

To generate stills, use the following:

$payload->addStills(
    'ftp-stills-directory',
    'stills_name_{number}',
    5, //number of stills
    400, //width in pixels
    300, //height in pixels
);
            

After that, send the payload to the API

$response = $client->sendPayload($payload);      
            

To keep track of the job, fetch the location from the response

$location = $response->getLocation();  
            

Getting task information:

$payload    = $client->createJobStatusPayload($location);
$response   = $client->sendPayload($payload);
$content    = $response->getJsonResponse();
            

RESTful API Usage

If you do not wish to use the API Client library, you can use our API with HTTP calls.

As soon as you receive an API key, you can access our admin interface, with full API docs and a sandboxed test environment.

The following is an example of a standard transcode job with a specific start and duration, in seconds.

To add a job, use the following. The stills and most of the options are optional and can be skipped, but using a preset is highly recommended.

POST http://admin.video-transcoder.com/api/v2/jobs
Content-Type: application/json
x-auth-token: your_api_key
{
    "input":"ftp-in-filename",
    "output":{
        "url":"ftp-out-filename",
        "preset":"H264-854x480-1024k-HQ",
        "stills":{
            "base_url":"ftp-out-stills-directory",
            "format":"jpg",
            "amount":5,
            "filename":"name_{number}"
        },
        "output_length":10,
        "seek_offset":20
    }
}
            

This will return an HTTP statuscode and a header with the location to keep track of your video transcode job.

HTTP/1.1 200 OK
Content-Type: application/json
Location: /api/v2/jobs/1
            

Thats all it takes to create a transcode job to your liking. To keep track of the the status of the job, simple use the following call with the ID retreived from the location header.

GET http://admin.video-transcoder.com/api/v2/jobs/1
            

This concludes the guide. For more information, simply use the contact form and we will answer as soon as possible.