API Documentation

API Guide

Supported codecs

Plugins

Overview

EncoderCloud offers a flexible API for seamlessly integrating our cloud based transcoding services directly into your own applications. The following section will address the methods made available through the EncoderCloud API. All methods are made available by using an HTTP(S) POST to the appropriate EncoderCloud URL for the method being accessed. Included with each POST are parameters required or optional for each method. Client must send HTTP(S) POST request with single parameter named "q". All client requests and server answers use JSON format.

Workflow

1. Your application sends a request to EncoderCloud telling it where the source video is located and what encoding profile to use.
2. EncoderCloud immediately responds back with the job ID that you may later use to track the status of your transcoding job.
3. Our system performs video conversion and uploads the file to your specified destination.
4. Request is made to your application notifying it about the completion of the job.

Basics

Each request must be sent to either of the following URLs:

http://www.encodercloud.com/api/action
https://www.encodercloud.com/api/action

Each request must also include the following parameters:

api_keystring, required

Your assigned API key.

actionstring, required

The action to be performed. Action values will be listed below next to the available requests.


New job requestAction name: AddJob

Add new media file to the processing queue.

custom_idstring, optional

Your custom file ID.

sourcestring, required

Media source file, it can be in the following formats:

  • http[s]://[user[:password]@]hostname[:port]/[path]/[filename]
  • ftp[s]://[user[:password]@]hostname[:port]/[path]/[filename][?passive=1]
  • http[s]://[AWS_KEY:AWS_PWD@][bucket].s3.amazonaws.com/[path] (amazon s3)
  • http[s]://[RCF_KEY:RCF_PWD@]rackspacecloud.com/[container]/[filename] (rackspacecloud files)

If you include username or password, make sure to URL encode them.

postbackstring, optional

HTTP(S) URL of the script the result would be posted to.

formatsarray, required

Output formats array. You can request up to 50 different formats to encode your input video into.

formats[profile_id]integer, required

Profile ID to use for encoding.

formats[destination]string, required

Destination URL to upload encoded file to (must include trailing slash):

  • ftp[s]://[user[:password]@]hostname[:port]/[path]/[?passive=1]
  • http[s]://[AWS_KEY:AWS_PWD@][bucket].s3.amazonaws.com/[path][?acl=private|public-read|authenticated-read] (amazon s3)
  • http[s]://[RCF_KEY:RCF_PWD@]rackspacecloud.com/[container]/ (rackspacecloud files)

If you include username or password, make sure to URL encode them.

Below is an example code in PHP that notifies EncoderCloud when new file is available for conversion.

$api_key = "Insert your API key here";
$action = "AddJob";
$custom_id = "Your optional custom file ID here";
$source = "ftp://john:password@mysite.com/media/videos/video.avi";
$postback = "http://www.mysite.com/process_video.php";
$profile_id = "Insert your profile ID here";
$destination = "ftp://john:password@mysite.com/media/videos/";
$url = "http://www.encodercloud.com/api/action";
$query = array(
	"api_key" => $api_key,
	"action" => $action,
	"custom_id" => $custom_id,
	"source" => $source,
	"postback" => $postback",
	"formats" => array(
		array(
			"profile_id" => $profile_id,
			"destination" => $destination,
		),
	),
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, "q=".urlencode(json_encode($query)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
$response = curl_exec($ch);

print_r(json_decode($response)); // output results for display purposes

If request was successful, you will receive the following output. Note that it includes a job ID that has been assigned by EncoderCloud. In the future if you would like to check job status in your application, you will need to reference this job ID to do so. 

stdClass Object
(
    [status] => success
    [job_id] => 36
)

If request has failed for some reason, you will receive the following output. 

stdClass Object
(
    [status] => error
    [message] => Invalid action.
)

Job statusAction name: JobStatus

Get current job status.

job_idinteger, required

Job ID assigned by EncoderCloud at the time new video request was made.

Below is an example code in PHP that notifies EncoderCloud when new file is available for conversion.

$api_key = "Insert your API key here";
$action = "JobStatus";
$job_id = "123"; // job ID assigned by EncoderCloud
$url = "http://www.encodercloud.com/api/action";
$query = array(
	"api_key" => $api_key,
	"action" => $action,
	"job_id" => $job_id,
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, "q=".urlencode(json_encode($query)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
$response = curl_exec($ch);

print_r(json_decode($response)); // output results for display purposes

If request was successful, you will receive the following output.

stdClass Object
(
   [job_id] => 123 // job ID assigned by EncoderCloud
   [custom_id] => 442 // custom ID of your file
   [process_start] => 1289328816 // unix time stamp when file was accepted
   [process_end] => 1289328833 // unix time stamp when job was finished
   [download_start] => 1289328816 // unix time stamp when file download started
   [download_end] => 1289328833 // unix time stamp when file download finished
   [message] =>
   [formats] => Array
   (
      [0] => stdClass Object
      (
         [encode_start] => 1289328818 // unix time stamp when profile conversion started
         [encode_end] => 1289328833 // unix time stamp when profile conversion finished
         [upload_start] => 1289328818 // unix time stamp when file upload started
         [upload_end] => 1289328833 // unix time stamp when file upload finished
         [status] => success
         [message] =>
      )
   )
)

Job detailsAction name: JobDetails

Get job details such as input/output video details, and current processing status.

job_idinteger, required

Job ID assigned by EncoderCloud at the time new video request was made.

Below is an example code in PHP that notifies EncoderCloud when new file is available for conversion.

$api_key = "Insert your API key here";
$action = "JobDetails";
$job_id = "123"; // job ID assigned by EncoderCloud
$url = "http://www.encodercloud.com/api/action";
$query = array(
	"api_key" => $api_key,
	"action" => $action,
	"job_id" => $job_id,
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, "q=".urlencode(json_encode($query)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
$response = curl_exec($ch);

print_r(json_decode($response)); // output results for display purposes

If request was successful, you will receive the following output.

stdClass Object
(
   [job_id] => 123 // job ID assigned by EncoderCloud
   [custom_id] => 442 // custom ID of your file
   [source] => ftp://john:password@mysite.com/media/videos/input.avi
   [filename] => input.avi
   [filesize] => 3899690 // file size in bytes
   [postback] => http://www.mysite.com/processvideo.php
   [process_start] => 1289328816 // unix time stamp when file was accepted
   [process_end] => 1289328833 // unix time stamp when job was finished
   [download_start] => 1289328816 // unix time stamp when file download started
   [download_end] => 1289328833 // unix time stamp when file download finished
   [video_codec] => mpeg4
   [video_size] => 800x340
   [video_duration] => 372 // video duration in seconds
   [video_bitrate] => 912
   [video_frame_rate] => 24
   [audio_codec] => mp3
   [audio_bitrate] => 128
   [audio_sample_rate] => 44100
   [audio_channels] => 2
   [status] => success
   [message] =>
   [formats] => Array
   (
      [0] => stdClass Object
      (
         [destination] => ftp://john:password@mysite.com/media/videos/
         [filename] => 1_41_41_HbUVRUCprNWb.flv // file name assigned by EncoderCloud
         [filesize] => 3274622 // file size in bytes
         [encode_start] => 1289328818 // unix time stamp when profile conversion started
         [encode_end] => 1289328833 // unix time stamp when profile conversion finished
         [upload_start] => 1289328818 // unix time stamp when file upload started
         [upload_end] => 1289328833 // unix time stamp when file upload finished
         [output_format] => flv
         [video_codec] => h264
         [video_size] => 640x480
         [video_aspect] => 1 // 1 - preserve, 2 - crop, 3 - pad, 4 - stretch
         [video_upscale] => 0
         [video_bitrate] => 912
         [video_max_bitrate] => 0
         [video_buffer_size] => 0
         [video_frame_rate] => 24
         [video_key_frame] => 0
         [video_deinterlace] => 0
         [audio_codec] => mp3
         [audio_bitrate] => 128
         [audio_sample_rate] => 44100
         [audio_channels] => 2
         [thumbnails] => 1
         [thumb_size] => 100x100
         [thumb_crop] => 0
         [watermark_url] => empty
         [watermark_position] => 0
         [status] => success
         [message] =>
      )
   )
)

Notifications

If you have provided a postback URL when adding a job, EncoderCloud will send a POST request once conversion is complete.

This document is subject to change. Last updated October 15th, 2010.