Hello Developers.

It's time to plug lighting fast video processing with massive scale into your website or application. With dozens of open source and commercial encoding engines at your fingertips via a single API call, you never need to compile another transcode engine or rack another server again. Let's get started.

Getting Started

Our official in-depth look at the complete API documentation — created by developers for developers.

API Workflow Overview

The Encoding.com API allows you to seamlessly integrate a fast and scalable cloud encoding platform into your application. Our XML API is the most mature, well documented and feature cloud encoding API on the market.

Here is how is works:

Your application sends an API request to Encoding.com which includes:

• The source location of your video.
• One or multiple custom or preset desired encoding recipes.
• One or multiple delivery points for your video.

 

Encoding.com responds immediately with a media ID so your application can track the progress of the job.

With the fastest SLA backed queue times in the industry, Encoding.com processes all of your jobs in parallel on dedicated multi core servers. Chose from three processing speed level, Baseline (4 core), Turbo (8 core), Twin Turbo (16 core). Our platform scales and assigns compute in realtime based on your needs so if you sent us 1 jobs with 1 output, it would process just as fast as if you sent us 250 jobs each with 10 outputs.

When processing is complete we will automatically send your output to your specified delivery point and send a http or email notification to your application.

Our XML API can be quickly integrated into applications written in any language. To accelerate your development we provide and support code libraries in many popular languages: PHP, Java, CFM, C#. There are also dozens of unofficial code libraries.

Some API Features to note:

Easily copy custom or preset XML encoding templates in the client interface and then use with the API
GetStatus: Get rich job progress reporting, Fore sample Media ID 123 is 23% finished downloading, Media ID 456 is 98% finished processing.
Perform advanced editing: watermarks, cropping, thumbnail generation, concatenation, picture in picture, custom text overlay.
GetmediaInfo: Get detailed media information about your source video to store in your application or customize your encoding recipes.
Complete sub user account system let's you manage sub users and isolate sub users encoding usage.

End Point

To send API requests to Encoding.com, please send HTTP(S) post requests to:
http(s)://manage.encoding.com
All client requests and server responses use the XML format. Clients must send the HTTP(S) POST request with a single parameter named xml. The server response will be a normal XML document.

Authentication

UserID

A unique user identifier. This number can be found in the My Account tab of the Client Interface.

UserKey

A user's unique authentication key string. Created automatically when a user is created and can be regenerated at anytime in the My Account tab of the Client Interface.

Complete XML Template

<?xml version="1.0"?>
<query>
<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>[Action]</action>
	<mediaid>[MediaID]</mediaid>
	<source>[SourceFile]</source>

	<!-- if multiple SourceFile added, they will be concatenated or join to split screen-->
	<source>[SourceFile1]</source>
	... 
	<source>[SourceFileN]</source>

	<!-- Split Screen fields (OPTIONAL) -->
	<split_screen>
		<columns>[ColumnsNumber]</columns>
		<rows>[RowsNumber]</rows>
		<padding_left>[PaddingLeftInPx]</padding_left>
		<padding_right>[PaddingRightInPx]</padding_right>
		<padding_bottom>[PaddingBottomInPx]</padding_bottom>
		<padding_top>[PaddingTopInPx]</padding_top>
	</split_screen>

	<region>[us-east-1|us-west-1|us-west-2|eu-west-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|sa-east-1]</region> 
	<notify>[NotifyURL]</notify>
	<notify_encoding_errors>[NotifyEncodingErrorURL]</notify_encoding_errors>
	<format>

		<!-- Format fields -->
		<noise_reduction>luma_spatial:chroma_spatial:luma_temp</noise_reduction>
		<output>[Output format]</output>
		<video_codec>[Video Codec]</video_codec>
		<audio_codec>[Audio Codec]</audio_codec>
		<bitrate>[Video bitrate]</bitrate>
		<audio_bitrate>[Audio bitrate]</audio_bitrate>
		<audio_sample_rate>[Audio quality]</audio_sample_rate>
		<audio_channels_number>[Audio channels number]</audio_channels_number>
		<audio_volume>[Volume]</audio_volume>		 
		<audio_normalization>[0-100]</audio_normalization>		 
		<framerate>[Frame Rate]</framerate>
		<framerate_upper_threshold>[Frame Rate Upper Threshold]</framerate_upper_threshold>
		<size>[Size]</size>
		<fade_in>[FadeInStart:FadeInDuration]</fade_in>
		<fade_out>[FadeOutStart:FadeOutDuration]</fade_out>
		<crop_left>[Crop Left]</crop_left>
		<crop_top>[Crop Top]</crop_top>
		<crop_right>[Crop Right]</crop_right>
		<crop_bottom>[Crop Bottom]</crop_bottom>
		<keep_aspect_ratio>[yes/no]</keep_aspect_ratio>
		<set_aspect_ratio>[ASPECT_RATIO|source]</set_aspect_ratio>
		<add_meta>[yes/no]</add_meta>
		<hint>[yes/no]</hint>
		<rc_init_occupancy>[RC Occupancy]</rc_init_occupancy>
		<minrate>[Min Rate]</minrate>
		<maxrate>[Max Rate]</maxrate>
		<bufsize>[RC Buffer Size]</bufsize>
		<keyframe>[Keyframe Period (GOP)]</keyframe>
		<start>[Start From]</start>
		<duration>[Result Duration]</duration>
		<output>mpeg2</output>
		<keyframe>[12|15|25|30]</keyframe> 
		<bframes>[2|0]</bframes>
		<gop>[cgop|sgop]</gop> 
		<output>[PRESET_NAME]</output>

		<!-- Metadata fields (OPTIONAL) -->
		<metadata> 
			<title>[Title]</title>
			<copyright>[Copyright]</copyright> 
			<author>[Author]</author> 
			<description>[Description]</description> 
			<album>[Album]</album> 
		</metadata> 

		<!-- Destination fields --> 
		<destination>[DestFile]</destination> 
		<destination>[DestFile2]</destination> 
		...
		<destination>[DestFileN]</destination>

		<!-- Logo fields (OPTIONAL) --> 
		<logo> 
			 <logo_source>[LogoURL]</logo_source> 
			 <logo_x>[LogoLeft]</logo_x> 
			 <logo_y>[LogoTop]</logo_y> 
			 <logo_mode>[LogoMode]</logo_mode> 
			 <logo_threshold>[LogoTreshold]</logo_threshold> 
		</logo>

		<!-- Overlay fields (OPTIONAL) -->
		<overlay>
			<overlay_source>[Overlay1Source]</overlay_source>
			<overlay_x>[Overlay1PositionX]</overlay_x>
			<overlay_y>[Overlay1PositionY]</overlay_y>
			<size>[Overlay1Size]</size>
			<overlay_start>[OverlayNStartInSeconds]</overlay_start>
			<overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
		</overlay>
		...
		<overlay>
			<overlay_source>[OverlayNSource]</overlay_source>
			<overlay_x>[OverlayNPositionX]</overlay_x>
			<overlay_y>[OverlayNPositionY]</overlay_y>
			<size>[OverlayNSize]</size>
			<overlay_start>[OverlayNStartInSeconds]</overlay_start>
			<overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
		</overlay>	
	
		<!-- Text Overlay fields (OPTIONAL) -->
		<text_overlay>
			<text>[Font1Source]</text>
			<font_source>[Font1Source]</font_source>
			<font_size>[Font1Size]</font_size>
			<font_rotate>[Font1Rotate]</font_rotate>
			<font_color>[Font1Color]</font_color>
			<align_center>[0|1]</align_center>
			<overlay_x>[TextOverlay1PositionX]</overlay_x>
			<overlay_y>[TextOverlay1PositionY]</overlay_y>
			<size>[TextOverlay1Size]</size>
			<overlay_start>[TextOverlay1StartInSeconds]</overlay_start>
			<overlay_duration>[TextOverlay1DurationInSeconds]</overlay_duration>
		</text_overlay>
		...
		<text_overlay>
			<text>[FontNSource]</text>
			<font_source>[FontNSource]</font_source>
			<font_size>[FontNSize]</font_size>
			<font_rotate>[FontNRotate]</font_rotate>
			<font_color>[FontNColor]</font_color>
			<align_center>[0|1]</align_center>
			<overlay_x>[TextOverlayNPositionX]</overlay_x>
			<overlay_y>[TextOverlayNPositionY]</overlay_y>
			<size>[TextOverlayNSize]</size>
			<overlay_start>[TextOverlayNStartInSeconds]</overlay_start>
			<overlay_duration>[TextOverlayNDurationInSeconds]</overlay_duration>
		</text_overlay>

		
		<!-- Video codec parameters (OPTIONAL, while only for libx264 video codec) --> 
		<video_codec_parameters> To see the example for parameters please follow this link below
		* </video_codec_parameters> 

		<!-- Profile & Level (OPTIONAL, while only for libx264 video codec) --> 
		<profile>[high/main/baseline]</profile>

		<level>[11/30/51]</level><!--drop the decimal, example 3.0 is 30--> 

		<!-- Turbo Encoding switch (OPTIONAL) --> 
		<turbo>[yes/no]</turbo>

		<!-- Video rotation (OPTIONAL) -->
		<rotate>def|0|90|270</rotate>
		<set_rotate>def|0|90|270</set_rotate>

		<audio_sync>[1..N]</audio_sync> 
		<video_sync>old|passthrough|cfr|vfr|auto</video_sync>
		<force_interlaced>tff|bff|no</force_interlaced>
		<strip_chapters>[yes|no]</strip_chapters> 
	</format> 
</query>

* Video codec settings

Browser XML Submission Test

Official API Wrappers

PHP

This sample script allows user to enter parameters and send API request for encoding:

<?php
function sendRequest($xml)
{
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, "http://manage.encoding.com/");
	curl_setopt($ch, CURLOPT_POSTFIELDS, "xml=" . urlencode($xml));
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_HEADER, 0);
	return curl_exec($ch);
} 


// Begin processing User's POST
if(!empty($_POST['source']))
{
	// Preparing XML request
  
	// Main fields
	$req = new SimpleXMLElement('<?xml version="1.0"?><query></query>');
	$req->addChild('userid', MY_ID);
	$req->addChild('userkey', MY_KEY);
	$req->addChild('action', 'AddMedia');
	$req->addChild('source', $_POST['source']);
  
	$formatNode = $req->addChild('format');
	// Format fields
	foreach($_POST['format'] as $property => $value)
	{
		if ($value !== '')
		$formatNode->addChild($property, $value);
	}
  
	// Sending API request
	$res = sendRequest($req->asXML());
  
	try
	{
		// Creating new object from response XML
		$response = new SimpleXMLElement($res);
	  
		// If there are any errors, set error message
		if(isset($response->errors[0]->error[0])) {
			$error = $response->errors[0]->error[0] . '';
		}
		else
		if ($response->message[0]) {
			// If message received, set OK message
			$message = $response->message[0] . '';
		}
	}
	catch(Exception $e)
	{
		// If wrong XML response received
		$error = $e->getMessage();
	}
  
	// Displaying error if any
	if (!empty($error)) {
		echo '<div class="error">' . htmlspecialchars($error) . '</div>';
	}
  
	// Displaying message
	if (!empty($message)) {
		echo '<div class="message">' . htmlspecialchars($message) . '</div>';
	}
	exit;
}
?>

Java

Thanks to Kalpesh Balare from Mediamelon, we have a nice sample script in Java to get you started.

import java.io.*;
import java.net.*;

public class EncodingTest {

	private static int startEncodingWorkflow() {
		// replace ID and key with your own
		String userID = "ID";
		String userKey = "key";
		String mediaID = "1";
		StringBuffer xml = new StringBuffer();
		xml.append("<?xml version='1.0'?>");
		xml.append("<query>");
		xml.append("<userid>"+userID+"</userid>");
		xml.append("<userkey>"+userKey+"</userkey>");
		xml.append("<action>GetMediaInfo</action>");
		xml.append("<mediaid>"+mediaID+"</mediaid>");
		xml.append("</query>");

		URL server = null;

		try {
			String url = "http://manage.encoding.com";
			System.out.println("Connecting to:"+url);
			server = new URL(url);

		} catch (MalformedURLException mfu) {
			mfu.printStackTrace();
			return 0;
		}

		try {
			String sRequest = "xml=" + URLEncoder.encode(xml.toString(), "UTF8");
			System.out.println("Open new connection to tunnel");
			HttpURLConnection urlConnection = (HttpURLConnection) server.openConnection();
			urlConnection.setRequestMethod( "POST" );
			urlConnection.setDoOutput(true);
			urlConnection.setConnectTimeout(60000);
			urlConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
			BufferedWriter out = new BufferedWriter( new OutputStreamWriter( urlConnection.getOutputStream() ) );
			out.write(sRequest);
			out.flush();
			out.close();
			urlConnection.connect();
			InputStream is = urlConnection.getInputStream();
			String str = urlConnection.getResponseMessage();
			System.out.println("Response:"+urlConnection.getResponseCode());
			System.out.println("Response:"+urlConnection.getResponseMessage());
			StringBuffer strbuf = new StringBuffer();
			byte[] buffer = new byte[1024 * 4];

			try {
				int n = 0;
				while (-1 != (n = is.read(buffer))) {
					strbuf.append(new String(buffer, 0, n));
				}

				is.close();

			} catch (IOException ioe) {
				ioe.printStackTrace();
			}

			System.out.println(strbuf.toString()); 

		} catch (Exception exp) {
			exp.printStackTrace();
		}

		return 0;
	}

	public static void main (String[] args) {
		startEncodingWorkflow();
	}
}

Cold Fusion

Now supported by Adobe, take a look at our ColdFusion sample script to get you started.

<!-- Building our query -->
<cfsavecontent variable="xml">
<?xml version="1.0"?>
<query>
	<action>AddMedia</action>
	<userid>0</userid>
	<userkey>your_key</userkey>
	<source>http://your.server.tld/some/path/file</source>
	<format>
		<output>3gp</output>
	</format>
	<format>
		<output>wmv</output>
	</format>
	<format>
		<output>flv</output>
	</format>
</query>
</cfsavecontent>

<!-- Setting up the URL to send the request -->
<cfset theURL = "http://manage.encoding.com">

<!-- Sending the request -->
<cfhttp url="#theURL#" charset="utf-8" method="post">
	<cfhttpparam type="formfield" name="xml" value="#xml#">
</cfhttp>

<!-- Getting the result -->
<cfdump var="#cfhttp.fileContent#">

C#

Integrate into desktop applications using this Microsoft C# sample script. Also, see our VBScript sample script.

static string HTTPPost(string sUrl, string sRequest)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(sUrl);
	request.Method = "POST";
	request.ContentType = "application/x-www-form-urlencoded";
	request.ContentLength = sRequest.Length;
	request.GetRequestStream().Write(Encoding.UTF8.GetBytes(sRequest), 0, sRequest.Length);
	request.GetRequestStream().Close();
	HttpWebResponse response = (HttpWebResponse)request.GetResponse();
	StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8);
	string result = reader.ReadToEnd();
	reader.Close();
	return result;
}

static void Main_Encoding(string origin, string destination)
{
	string xml, sUrl, sRequest, result, userID, userKey;
	//put your real userID and userKey below
	userID = "0";
	userKey = "your_key";
	xml = string.Format(
@"<?xml version=""1.0""?>

<query>
<userid>{0}</userid>
<userkey>{1}</userkey>
<action>AddMedia</action>
<source>{2}</source>
<format>
<output>flv</output>
<destination>{3}</destination>
</format>
</query>", userID, userKey, origin, destination);

	sUrl = "http://manage.encoding.com/";
	sRequest = "xml=" + HttpUtility.UrlEncode(xml);
	result = HTTPPost(sUrl, sRequest);
}

static void Main(string[] args)
{
	string origin = "http://yoursite.com/video/movie.avi";
	string destination = "ftp://username:password@yourftphost.com/video/encoded/test.flv";
	Main_Encoding(origin, destination);
}

Unofficial API Wrappers

Zend Framework

Visit the Zend.com community site for the Encoding.com Zend Framework

Ruby

Thanks to Mick Stauga- ard from podcastemachine.com he has released the following Ruby library into the public domain.

Python

Here's a Python wrapper for the Encoding.com API hosted on Github.

VBScript

This sample script allows to get a list of user's media:

Dim xml, sURL, sRequest, result, userID, userKey
	' put your real userID and userKey below
	userID = "0"
	userKey = "your_key"

	xml = "<?xml version="'1.0'"?>" & VbCrLf
	xmlxml = xml & "<query>" & VbCrLf
	xmlxml = xml & "<userid>" & userID & "</userid>" & VbCrLf
	xmlxml = xml & "<userkey>" & userKey & "</userkey>" & VbCrLf
	xmlxml = xml & "<action>" & "GetMediaList" & "</action>" & VbCrLf
	xmlxml = xml & "</query>" & VbCrLf

	sUrl = "http://manage.encoding.com"
	sRequest = "xml=" & xml
	result = HTTPPost(sUrl, sRequest)

	Function HTTPPost(sUrl, sRequest)
		Set oHTTP = CreateObject("Microsoft.XMLHTTP")
		oHTTP.open "POST", sUrl,false
		oHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
		oHTTP.setRequestHeader "Content-Length", Len(sRequest)
		oHTTP.send sRequest
		HTTPPost = oHTTP.responseText
	End Function

API Main Fields

End Point

To send API requests to Encoding.com, please send HTTP(S) post requests to:
http(s)://manage.encoding.com
All client requests and server responses use the XML format. Clients must send the HTTP(S) POST request with a single parameter named xml. The server response will be a normal XML document.

Authentication

UserID

A unique user identifier. This number can be found in the My Account tab of the Client Interface.

UserKey

A user's unique authentication key string. Created automatically when a user is created and can be regenerated at anytime in the My Account tab of the Client Interface.

Action

The action to be performed in the API request.

Action	Description
AddMedia	Add new media to user's queue. Creates new items in a queue according to formats specified in the XML API request.
AddMediaBenchmark	Add new media to user's queue and sets a flag to NOT process automatically after downloading. Format fields can be specified as well. If NotifyURL is set, a notification will be sent after the media is ready for processing. Note: the media will get 'Ready to process' status only when at least one <format> field is specified. Otherwise, you may retrieve source media information via GetMediaInfo action listed below.
UpdateMedia	Replace information about existing media's formats. All old format items will be deleted and the new ones will be added.
ProcessMedia	Start encoding the previously downloaded media (ones that have been added with an AddMediaBenchmark action).
CancelMedia	Delete specified media and all its items in the queue.
GetMediaList	Returns a list of the user's media in the queue.
GetStatus	Returns information about a selected user's media and all its items in the queue.
GetMediaInfo	Returns video parameters of the specified media when available.
RestartMedia	Complete restart the entire job.
RestartMediaErrors	Only retry tasks ended with error.
RestartMediaTask	Only restart the specified task (format). Additional parameter <taskid> must be specified.
StopMedia	Stop media downloading/processing/uploading. If at least one destination is saved, media will be finished, otherwise it will be stopped.

MediaID

A unique identifier for each media. This field must be specified for the following actions: UpdateMedia, ProcessMedia, CancelMedia, GetMediaInfo, GetStatus.

SourceFile

Source media file. Must be specified only for AddMedia and AddMediaBenchmark actions.
It can be in the following formats:

Source type	Description
HTTP	http://[user[:password]@]hostname[:port]/[path]/[filename] Parameter "?multithread=1" in source URL turns on multithread download
FTP / SFTP	ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes] sftp://[user[:password]@]hostname[:port]/[path]/[filename] Note: Adding ?passive=yes to the FTP URL forces downloader/uploader use Passive Mode for FTP transfer. Also, you can specify ?passive=no (the default) explicitly. It will take the same effect that if you don't specify this parameter at all. Parameter "?multithread=1" in source URL turns on multithread download
Amazon Web Services (S3)	http://[bucket].s3.amazonaws.com/[filename] http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename] — If you don't specify an AWS key/secret, the object must have READ permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users). See Amazon S3 ACL for details. — If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL. If you use the Access key and Secret key, they must be URL encoded. For example, if your Key and the Secret are: 1ZG3YAKJ8W0VOA9L7WT6lQT5MsQLirc8owb:SxX/9EhU4M+QarasFelQ0v2M First, we must URL encode the Secret as it contains special characters: ':','+' and '/'. The URL encoded Secret is now: lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M You should NOT encode the colon between Key and Secret nor the '@' after them. So, the destination URL will be: http://1ZG3YAKJ8W0VOA9L7WT6:lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M@encode.video.s3.amazonaws.com/v/encoded/ Note: — Do not forget to URL encode your AWS_SECRET, specifically replacing '/' with '%2F'. — See Percent-encoding for more details on URLencoding. Also, you can add ?acl=public-read OR ?acl=authenticated-read after the filename. This will explicitly set access rights to the saved object instead of the default settings.
Rackspace CloudFiles	http://[RS_USER:RS_KEY@]storage.cloudfiles.com/[path]/[filename] — Virtual URL for Cloud Files https://storage4.clouddrive.com/v1/MossoCloudFS_cea19775-aa94-4d78-8da9-1a7b4bbbd548/container_name/file.ext?auth-token=c2633419-7b79-3d58-8417-d63666dddfd5 — Real URL for Cloud Files like this if you were authenticated yourself recently
Aspera Server	Please use such URL if your source is on the Aspera Enterprise Server™ or Aspera Connect Server™ fasp://[user[:password]@]hostname/[path]/[filename]
Windows Azure Blob	To access to files stored on azure blob storage use next way: http(s)://[access_key]@[account].blob.core.windows.net/[container]/path access_key should be urlencoded

You can specify several source files within the same API request. All of them will be combined to one file (in sequential order) during the encoding process. You can use different source URLs (HTTP, FTP, S3, CloudFiles) with different media properties (format, frame size, bitrate, codec, etc.) Read more.

Notifications

Notify

Can be either an HTTP(S) URL for the script with which the result will be posted, or a mailto: link with email address for which the result info will be sent. This field may be specified for AddMedia and AddMediaBenchmark actions.

Notify_encoding_errors

Can be either an HTTP(S) URL for the script or a mailto: link with email address for which result info will be sent only if media finished with encoding errors.

XML Callback Format

If an 'http(s)://' link is specified in the <notify> part of the <query>, the HTTP POST request will be sent to the specified location. The POST data will contain one parameter named xml in the following format:

<?xml version="1.0"?>
<result>
    <mediaid>[MediaID]</mediaid>
    <source>[SourceFile]</source>
    <status>[MediaStatus]</status>
    <description>[ ErrorDescription]</description> <!-- Only in case of Status = Error -->
    <format>
        <output>[OutputFormat]</output>
        <destination>[URL]</destination> <!-- Only in case of Status = Finished -->
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
        <destination>[URL_2]</destination>
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status>
        <!-- ... -->
        <destination>[URL_N]</destination>
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status>
        <status>[TaskStatus]</status>
        <description>[ErrorDescription]</description> <!-- Only in case of Status = Error -->
        <suggestion>[ErrorSuggestion]</suggestion> <!-- Only in case of Status = Error -->
    </format>
</result>

Field	Description
MediaID	A unique identifier of the media
SourceFile	Media source file URL
MediaStatus	Could be either Finished or Error
OutputFormat	Format of encoded file, as was requested in the query.
DestFile ThumbDest	Could be one of the following: ftp://[user]:[password]@[server]/[path]/[filename] http://[users.bucket].s3.amazonaws.com/[path]/[filename] — the bucket must have WRITE permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 See Amazon S3 ACL for details OR http://[encoding.bucket].s3.amazonaws.com/[path]/[filename] — if destination was not specified in the query.
TaskStatus	Could be either Finished or Error
ErrorDescription	Description of the error if status is Error
ErrorSuggestion	Description of the error if status is Error and we have a suggestion available for this error

API Output Format Fields

Output

Output format type. Can be one of the following:

• flv
• fl9
• wmv
• mov
• 3gp
• mp4
• m4v
• ipod
• iphone
• ipad
• android
• ogg
• webm
• appletv
• psp
• zune
• mp3
• wma
• m4a
• thumbnail
• image
• mpeg1
• mpeg2 (just experimental feature please use with care, feedback is welcome)
• iphone_stream
• ipad_stream
• muxer
• wowza
• wowza_multibitrate
• roku_800
• roku_1200
• roku_1800
• roku_2700
• roku_hls
• mpegts
• dnxhd
• vidly
• vidly_lite
• kindle_fire
• eac3
• smooth_streaming
• hds

VP6 FLV Output

VP6 (deprecated)

VP6 feature is deprecated and will be automatically converted to the new form. All parameters will be ignored.

If you choose the vp6 codec for flv output, you will have fewer parameter options than if you use the vp6_flix output (see below) and therefore, your XML query will differ:

<format>
    <output>flv</output>
    <video_codec>vp6</video_codec>
    <bitrate></bitrate> <!-- optional -->
    <size></size> <!-- optional -->
    <audio_bitrate>64k</audio_bitrate> <!-- optional -->
    <audio_sample_rate>44100</audio_sample_rate> <!-- optional -->
    <audio_channels_number>2</audio_channels_number> <!-- optional -->
    <framerate></framerate> <!-- optional -->
    <destination></destination> <!-- optional -->
</format>

Note: we strongly recommend using video dimensions that are multiples of 16.

VP6 Flix

To generate vp6 output using the On2 Flix encoder, please use the vp6_flix output format which includes additional optional options:

<format>
    <output>vp6_flix</output>
    <vp6_profile></vp6_profile>
    <noise_reduction></noise_reduction>
    <upct></upct>
    <kfinttype></kfinttype>
    <keyframe></keyframe>
    <sharpness></sharpness>
    <cxmode></cxmode>
</format>

Field Name	Allowed Values	Default Values
vp6_profile Encoding profile	1 — VP6_E 2 — VP6_S	1
noise_reduction Determines the level of noise filtering to apply in the preprocessor.	[0,6] 0 — no preprocessing 6 — extreme preprocessing	Bits per pixel dependent
upct Parameter for undershoot percentage	0-100	90
kfinttype Keyframe interval type	1 — MAX KEYFRAMES 2 — FIXED KEYFRAMES	1
keyframe Keyframe period (in frames)	Non-negative integer	300
sharpness Controls the sharpness of the image in the output	[0,7]	Bits per pixel dependent
cxmode Compress mode	1 — GOOD 2 — BEST	1

Video Settings

Field Name	Allowed Values	Default Values
video_codec Video codec	flv: flv, libx264, vp6 fl9, mpegts: libx264 wmv, zune: wmv2, msmpeg4 3gp, android: h263, mpeg4, libx264 m4v: mpeg4 mp4, ipod, iphone, ipad, appletv, psp: mpeg4, libx264 ogg: libtheora webm: libvpx mp3, wma: none mpeg2: mpeg2video mpeg1: mpeg1video	flv: flv fl9, ipod, iphone, ipad: libx264 wmv, zune: wmv2 3gp: h263 mp4, m4v,appletv, psp, android: mpeg4 ogg: libtheora webm: libvpx mpeg2: mpeg2video mpeg1: mpeg1video
size Video frame size	All: WxH, where W and N are any even integers. 3gp (h263): 128x96, 176x144, 352x288, 704x576, 1408x1152 appletv: 710x480 zune: 320x180, 320x240 vp6: WxH, where W and N are multiple of 16 Custom: To match your source aspect ratio, set X value to zero and Y value to your desired height. For example, 0x360 or 0x480.	All: None (any size possible) 3gp: 176x144 iPhone: 480x368 iPad: 1280x720 Android: 800x400 appletv: 710x480 zune: 320x180 psp: 368x192
Note: You can specify only one dimension: either width or height. In this case, set other dimension to 0. (I.e. 640x0).
keep_aspect_ratio Whether to keep width to height ratio of the original frame size.	yes, no	yes
set_aspect_ratio Display aspect ratio (DAR). When set, the option keep_aspect_ratio will be ignored. The option only works with the following formats: fl9, 3gp, mp4, m4v, ipod, iphone, ipad, android, ogg, webm, appletv, psp, iphone_stream, ipad_stream.	Positive float value or N:M where N and M are any positive integers. source: display aspect ratio will be copied from source file	yes
bitrate video bit rate	All: Nk (where N is any non zero integer)	All: 512k 3gp: 256k iOS, Android, PSP: 1024k
maxrate Maximum allowed video bitrate	N or Nk — where N is any non-zero integer	None
minrate Minimum allowed video bitrate	N or Nk — where N is any non-zero integer	None
cbr Whether to use CBR (Constant bitrate)	yes, no	no
framerate Frame rate	All: any non-zero integer or N/M where N and M are non-zero integers	All: none psp: 30000/1001
framerate_upper_threshold If source frame rate lower then framerate_upper_threshold, then source frame rate will be used	Any non-zero integer or N/M where N and M are non-zero integers	None
Note: If framerate_upper_threshold is specified then framerate parameter will be ignored.
keyframe Keyframe period, in frames	positive integer	300
start Start encoding from (sec)	non-negative integer	None
duration Duration (sec)	positive integer	None

Audio Settings

Field Name	Allowed Values	Default Values
audio_codec Audio codec	mp3: libmp3lame m4a: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2 flv: libmp3lame, libfaac, dolby_aac, dolby_heaac, dolby_heaacv2 fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp, wowza, roku_*, kindle_fire: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2 mov: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2, eac3 iphone_stream, ipad_stream, wowza_multibitrate, roku_hls, smooth_streaming, hds: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2 wmv, wma, zune: wmav2, libmp3lame ogg, webm: libvorbis 3gp: libamr_nb android: libamr_nb, libfaac mpeg2: pcm_s16be, pcm_s16le mpeg1: mp2, copy mpegts: ac3	flv, mp3: libmp3lame fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp, wowza, roku_*, kindle_fire: libfaac mov: libfaac iphone_stream, ipad_stream, wowza_multibitrate, roku_hls, smooth_streaming, hds: libfaac wmv, zune: wmav2 ogg, webm: libvorbis 3gp, android: libamr_nb mpeg2: pcm_s16be mpeg1: mp2 m4a: libfaac
Note: If you specify audio_codec equal to 'copy', the options audio_channels_number, audio_sample_rate, audio_bitrate will be ignored and their values will be copied from your source file.
audio_bitrate Audio bitrate	Nk - where N is any non-zero integer 3gp: 4.75k, 5.15k, 5.9k, 6.7k, 7.4k, 7.95k, 10.2k, 12.2k flv, wmv, mp3, wma, zune: 32k, 40k, 48k, 56k, 64k, 80k, 96k, 112k, 128k, 144k, 160k, 192k, 224k, 256k, 320k ogg, webm: 45k,64k, 80k, 96k, 112k, 128k, 160k, 192k, 224k, 256k, 320k, 500k	All: 64k 3gp, android: 12.2k ipod, iphone, ipad, psp: 128k
acbr Whether to use CBR (Constant bitrate) for audio stream. Only for vorbis (Ogg, Webm)	yes, no	no
audio_sample_rate Audio sampling frequency (Hz)	All: any non-zero integer 3gp: 8000 flv, mp3: 11025, 22050, 44100 ogg, webm: 16000, 32000, 44100, 22050, 11025, 192000 wmv, wma, zune: 11025, 22050, 32000, 44100, 48000 mpeg2: 44100, 48000	All: none 3gp, android: 8000 flv, mp3, zune, mpeg2: 44100
audio_channels_number Number of audio channels	All: any non-zero integer 3gp: 1 android: 1, 2	All: 2 3gp, android: 1
audio_volume Audio volume level, in percent	non-negative integer	100
audio_normalization This option specifies that a gain should be applied so that the final dialogue normalization value of the audio signal is equal to the specified value.	Non-negative integer from 0 to 100	None
audio_sync It adjusts the audio stream to match the timestamps, in # of samples per second. 1 is special value that means automatic.	positive integer	None

Destination

You can use multiple <destination> elements within each <format>.

Destination type	Description
HTTP	http://[user[:password]@]hostname[:port]/[path]/[filename]
FTP / SFTP	ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes] sftp://[user[:password]@]hostname[:port]/[path]/[filename] Note: Adding ?passive=yes to the FTP URL forces downloader/uploader use Passive Mode for FTP transfer. Also, you can specify ?passive=no (the default) explicitly. It will take the same effect that if you don't specify this parameter at all.
Amazon Web Services (S3)	http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&canonical_id=AWS_CANONICAL_USER_ID — If you specify AWS canonical user ID in the URL, FULL_CONTROL on the object will be granted to the specified user. http://[bucket].s3.amazonaws.com/[filename][?acl=public-read&content_type=your-own/content-type — If you specify Content type, then Amazon will add appropriate Content-type header when the object is accessed via the web. http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read] — If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL. If you use the Access key and Secret key, they must be URL encoded. For example, if your Key and the Secret are: 1ZG3YAKJ8W0VOA9L7WT6lQT5MsQLirc8owb:SxX/9EhU4M+QarasFelQ0v2M First, we must URL encode the Secret as it contains special characters: ':','+' and '/'. The URL encoded Secret is now: lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M You should NOT encode the colon between Key and Secret nor the '@' after them. So, the destination URL will be: http://1ZG3YAKJ8W0VOA9L7WT6:lQT5MsQLirc8owb%3ASxX% 2F9EhU4M%2BQarasFelQ0v2M@encode.video.s3.amazonaws.com/v/encoded/ Note: — Do not forget to URL encode your AWS_SECRET, specifically replacing '/' with '%2F'. — If you don't specify AWS key/secret, the bucket must have READ and WRITE permissions for AWS user: 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 — See Amazon S3 ACL for more details. — See Percent-encoding for more details on URLencoding. Also, you can add ?acl=public-read OR ?acl=authenticated-read after the filename. This will explicitly set access rights to the saved object instead of the default settings.
Rackspace CloudFiles	http://[RS_USER:RS_KEY@]storage.cloudfiles.com/[path]/[filename] — Virtual URL for Cloud Files https://storage4.clouddrive.com/v1/MossoCloudFS_cea19775-aa94-4d78-8da9-1a7b4bbbd548/container_name/file.ext?auth-token=c2633419-7b79-3d58-8417-d63666dddfd5 — Real URL for Cloud Files like this if you were authenticated yourself recently
Aspera Server	fasp://[user[:password]@]hostname/[path]/[filename]
Windows Azure Blob	To access to files stored on azure blob storage use next way: http(s)://[access_key]@[account].blob.core.windows.net/[container]/path Also, you can add ?acl=public-read OR ?acl=public-container OR ?acl=private after the filename. This will explicitly set access rights to the container instead of the default settings access_key should be urlencoded
YouTube	http://[YoutubeLogin]:[YoutubePassword]@youtube.com/?title=[VideoTitle]&category=[VideoCategory]&keywords=[VideoKeywords]&description=[VideoDescription]&acl=[ACL] [YoutubeLogin] – Login on YouTube (mandatory) [YoutubePassword] – Password on YouTube (mandatory) [VideoTitle] – Video title on YouTube (optional, default: filename) [VideoCategory] – Video category. Allowed values: Film, Autos, Music, Animals, Sports, Travel, Games, People, Comedy, Entertainment, News, Howto, Education, Tech, Nonprofit (optional, default: Film) [VideoKeywords] – Video keywords on YouTube (optional, default: none) [VideoDescription] – Video description on YouTube (optional, default: none) [ACL] – Access Control List to video on YouTube (optional, default: private). Allowed values: private – only owner can get access to the video, public-read – everyone can get access to the video, unlisted - only users with direct link can get access to the video You can link you encoding.com account with your YouTube account in "My Account" section of User Interface. In that case you may not specify [YoutubeLogin] and [YoutubePassword].

 

Other Format Options

Field Name	Allowed Values	Default Values
profile The standard defines various sets of capabilities, which are referred to as profiles, targeting specific classes of applications.	high, main, baseline	fl9, mpeg4, flv: high mp4, m4v: main ipod, iphone, ipad, 3gp, appletv, psp: baseline
two_pass 2-pass encoding toggle	yes, no	no
two_pass_decoding Decode to a lossless format prior to encoding to reduce errors.	1	None
bufsize Rate control buffer size (bits)	N or Nk - where N is any non-zero integer	None
rc_init_occupancy Initial rate control buffer occupancy (bits)	N or Nk - where N is any non-zero integer	None
deinterlacing De-interlacing toggle	yes, no, auto auto - use de-interlacing if source's scan type is interlaced	auto
force_interlaced Interlaced encoding type. Only works with MPEG-TS.	mpegts: tff,bff,no	mpegts: tff
add_meta Add meta data to the file. Only works with FLV.	yes, no	All: None flv: no
hint Add RTP data (for streaming servers). Only works with MP4.	yes, no	All: None mp4: no
preset Specify format preset. Only works with WebM.	1 — 2-Pass Best Quality VBR Encoding 2 — 2-Pass Faster VBR Encoding 3 — 2-Pass VBR Encoding for Smooth Playback on Low-end Hardware 4 — 2-Pass CBR Encoding for Limited-bandwidth Streaming 5 — 2-Pass VBR Encoding for Noisy / Low-quality Input Source 6 — 1-Pass Good Quality VBR Encoding	6
bframes	2 [on = IBBPBBP], 0 [off = IPPPPPP]	2
gop	sgop [Strict (Locked)], cgop [Closed (Scene Detection)]	cgop
luma_spatial Spatial luma strength.	[0,255]	4
chroma_spatial Spatial chroma strength.	[0,255]	3
luma_temp Temporal luma strength.	[0,255]	6
audio_sync It adjusts the audio stream to match the timestamps, in # of samples per second. 1 is special value that means automatic.	Positive integer	None
video_sync Video sync method.	old — Keep old behavior (for compatibility) passthrough — Each frame is passed with its timestamp from the demuxer to the muxer cfr — Frames will be duplicated and dropped to achieve exactly the requested constant framerate vfr — Frames are passed through with their timestamp or dropped so as to prevent 2 frames from having the same timestamp auto — Chooses between cfr and vfr depending on muxer capabilities	None
strip_chapters Strip chapters markers	yes, no	no
vidly_hls Enables HLS format for Vidly Lite URL	yes, no	no
vidly_hd Enables HD button in Vid.ly player. High Definition (720p) videos will be generated.	yes, no	no
hard_cbr Specify HRD information and pack the bitstream to the specified bitrate	yes, no	no
pix_format Pixel format - ability to lock output to YUV420p colorspace	yuv420p, yuv422p, yuvj420p, yuvj422p, source	yuv420p
Note: If 'source' specified as value, then <pix_format> won't be added to format options.
best_quality Best quality mode (very slow) - dnxhd output only	yes, no	no
interlaced dnxhd output only	yes, no	no
Note: bitrate for dnxhd output is specified separately and the default is 145m

 

Turbo and Twin-Turbo Encoding

Field Name	Allowed Values	Default Values
turbo Send your job to a higher capacity (more CPU and more RAM) server for faster processing.	yes, no	no
twin_turbo Send your job to a higher capacity encoder and turn on multi-threaded encoding (only applicable for modern video codecs such as h.264, vp8 (webm), theora)	yes, no	no
Note: additional encoding bandwidth charges apply. Please view the Turbo Encoding Help Article for more details.

Region

Allow you to specify instance's region where your file should be processed

Option	Location
us-east-1 (default)	US (Northern Virginia)
us-west-1	US (Northern California)
us-west-2	US (Oregon)
eu-west-1	EU (Ireland)
ap-southeast-1	Asia Pacific (Singapore)
ap-northeast-1	Asia Pacific (Tokyo)
sa-east-1	South America (Sao Paulo)
oak-private-clive	Private Cloud (California)

Brightcove™ Batch Provisioning Integration

Encoding.com has developed a special plug-in that enables Brightcove customers to take advantage of Encoding.com's advanced video encoding features. Utilizing the dozens of encoding controls (custom dimensions, bitrate, framerate, 1/2 pass, deinterlacing, etc.) available via the Encoding.com platform, Brightcove customers can now have complete control over their video transcoding and achieve superior quality without having to make an investment in expensive hardware / software solutions. The plug-in will automatically deliver the encoded video library to the Brightcove customer's account (via the Brightcove™ FTP Batch Provisioning) along with the necessary meta data (media title, description, tags, etc.) and is available via Encoding.com's powerful XML API thus enabling seamless integration into internal media workflows, applications and content management systems.

Composing API request

First, add new elements to the AddMedia XML request:

<?xml version="1.0"?>
<query>
    <action>AddMedia</action>
    <userid>xxx</userid>
    <userkey>xxx</userkey>
    <source>http://yoursite.com/media.mov</source>
    <resend_to>http://manage.encoding.com/third_party/brightcove/add_media.php</resend_to>
    <notify>http://manage.encoding.com/third_party/brightcove/add_manifest.php</notify>
    <title>Your media title</title>
    <description>Short description of the media</description>
    <long_description>
        Put
        Long description
        Of the Media Here
    </long_description>
    <bc_userid>12345</bc_userid>
    <bc_mediaid>12345</bc_mediaid>
    <notify_email>user@mail.com</notify_email>
    <link_title>Link title</link_title>
    <link_url>http://encoding.com</link_url>
    <active>true</active>
    <tag>tag's content</tag>
    <format>
        <output>flv</output>
        <destination>ftp://user:password@ftp.brightcove.com/encoded/media.flv</destination>
    </format>
</query>

This process will trigger our system to re-send the API request with <mediaid> element added to the specified URL. Then, the additional information will be stored and associated with newly added media.

The manifest file format

If the media is encoded successfully, the other script specified in the <notify> element will compose and save XML manifest file with the same name as your first result file, but with extension .xml, and to the same FTP folder as was specified in the first <destination>. The file will have the following format (assume the result video format is FLV):

<?xml version="1.0" encoding="utf-8"?>
<publisher-upload-manifest publisher-id="{bc_userid}" preparer="encoding.com" report-success="TRUE">
    <notify email="{notify_email}"/>
    <asset filename="{result_filename}" refid="{result_filename}-{md5_hash}" size="{file_size}" hash-code="{md5_hash}" type="FLV_FULL"/>
    <title name="{title}" refid="{bc_mediaid}" active="{active}" flash-full-refid="{result_filename}-{md5_hash}">
        <short-description>{description}</short-description>
        <long-description>{long_description}</long-description>
        <related-link-url>{link_url}</related-link-url>
        <related-link-text>{link_title}</related-link-text>
        <rendition-refid>{result_filename}-{md5_hash}</rendition-refid>
        <tag>tag's content</tag>
    </title>
</publisher-upload-manifest>

Where {file_size} and {md5_hash} will be calculated according to the result file. The asset nodes will be added only for the following output values: flv, fl9, thumbnail.

Adding thumbnails

If a request contains a thumbnail generation task, <asset type="THUMBNAIL"> or <asset type="VIDEO_STILL"> will be added to the manifest. The type attribute depends on the resulting image width: if it is less than 200 pixels, the type will be THUMBNAIL, otherwise it will be VIDEO_STILL.
The request:

<format>
    <output>flv</output>
    <destination>ftp://user:password@ftp.brightcove.com/encoded/media.flv</destination>
</format>
<format>
    <output>thumbnail</output>
    <destination>ftp://user:password@ftp.brightcove.com/encoded/media_thumb.jpg</destination>
</format>

The manifest:

<asset filename="media.flv" refid="media.flv-896e665b84fd8b59ba8f5930dc61d21b" size="1689452" hash-code="896e665b84fd8b59ba8f5930dc61d21b" type="FLV_FULL"/>
<asset filename="media_thumb.jpg" refid="media_thumb.jpg-0861874e79d02a9cb17642defad47926" size="29863" hash-code="0861874e79d02a9cb17642defad47926" type="THUMBNAIL"/>
<title name="{title}" refid="{bc_mediaid}" active="TRUE" flash-full-refid=" media.flv-896e665b84fd8b59ba8f5930dc61d21b" thumbnail-refid="media_thumb.jpg-0861874e79d02a9cb17642defad47926">

Selecting title ref-id from multiple records with equal formats

If there are several FLV or THUMNAIL tasks in the single request, the same number of <asset> elements will be added to the XML manifest.
Although, only the first task of each group will reflect to the title's flash-full-refid or thumbnail-refid accordingly. So, if you want certain task's asset to reflect into the title, specify this task first in your XML API request.

Specifying different video's renditions

When you specify video frame size and bitrate in your API request, the additional attributes will be added to the appropriate assets in the manifest file.

The request:

<format>
    <output>flv</output>
    <bitrate>300k</bitrate>
    <size>320x240</size>
</format>
<format>
    <output>flv</output>
    <bitrate>750k</bitrate>
    <size>640x480</size>
</format>

The manifest:

<asset filename="media1.flv" refid="media1.flv-896e665b84fd8b59ba8f5930dc61d21b" size="1689452" hash-code="896e665b84fd8b59ba8f5930dc61d21b" type="FLV_FULL" frame-width="320" frame-height="240" encoding-rate="300000"/>
<asset filename="media2.flv" refid="media2.flv-90f044322653e205466de79d4534b84f" size="3542788" hash-code="90f044322653e205466de79d4534b84f" type="FLV_FULL" frame-width="640" frame-height="480" encoding-rate="750000"/>
…  
And within the title:
<rendition-refid>media1.flv-896e665b84fd8b59ba8f5930dc61d21b</rendition-refid>
<rendition-refid>media2.flv-90f044322653e205466de79d4534b84f</rendition-refid>

Adaptive Bitrate Encoding

Apple's HTTP Live Streaming (HLS)

<format>
    <!-- Format fields -->
    <output>[iphone_stream|ipad_stream]</output>
    <size>[CommaSeparatedList]</size>
    <bitrates>[CommaSeparatedList]</bitrates>
    <framerates>[CommaSeparatedList]</framerates>
    <keyframes>[CommaSeparatedList]</keyframes>
    <segment_duration>[Duration]</segment_duration>
    <pack_files>[yes|no]</pack_files>
    <add_audio_only>[yes|no]</add_audio_only>
    <still_image>[no|each_segment|first_segment]</still_image>
    <still_image_time>[Time]</still_image_time>
    <still_image_size>[Size]</still_image_size>
    <encryption>[yes|no]</encryption>
    <encryption_key>[128bit-key]</encryption_key>
    <encryption_key_file>[SourceURL]</encryption_key_file>
    <segmenter>[v1|v2]</segmenter>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>

Field Name	Allowed Values	Default Values
size Comma separated list of video sizes	One or more valid size values separated by commas	iphone_stream: 400x300 ipad_stream: 640x480
bitrates Comma separated list of video bitrates	One or more valid bitrate values separated by commas	iphone_stream: 600k,400k,200k,110k ipad_stream: 1200k,800k,600k,400k,200k,110k
framerates Comma separated list of framerates related to previous parameter	One or more valid framerate values separated by commas	iphone_stream: 29.97,29.97,15,10 ipad_stream: 29.97,29.97,29.97,29.97,15,10
keyframes Comma separated list of keyframe parameters	One or more valid keyframe values separated by commas	iphone_stream: 90,90,45,30 ipad_stream: 90,90,90,90,45,30
segment_duration Segment duration to split media (in seconds)	Non-negative integer	10
pack_files Whether to pack resulting files to a single tarball	yes, no	yes
add_audio_only Whether to add audio-only stream	yes, no	no
still_image Embed still image in the audio-only stream	no, each_segment, first_segment	no
still_image_time The time from the beginning of segment to capture still image	Non-negative number greater than 0.01 or hh:mm:ss.ms	None
still_image_size The size of the still image	WxH where W and H — positive integers	None
encryption Encrypt TS segements using AES-128	yes, no	no
encryption_key Encryption key	32 hexidecimal characters ([0-9a-f])	None
encryption_key Encryption key	32 hexidecimal characters ([0-9a-f])	None
segmenter	v1, v2	v1

 

Adobe's Dynamic Streaming (HDS)

<format>
    <!-- Format fields -->
    <output>hds</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <pack_files>[yes|no]</pack_files>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>

Field Name	Allowed Values	Default Values
bitrates Comma separated list of video bitrates	One or more valid bitrate values separated by commas	300k, 600k, 1200k, 2400k
sizes Comma separated list of video sizes	One or more valid size values separated by commas	None
pack_files Whether to pack resulting files to a single tarball	yes, no	yes

Microsoft's Smooth Streaming (MSS)

<format>
    <!-- Format fields -->
    <output>smooth_streaming</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <pack_files>[yes|no]</pack_files>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>

Wowza Multi-Bitrate (SMIL)

<format>
    <!-- Format fields -->
    <output>wowza_multibitrate</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>

Field Name	Allowed Values	Default Values
bitrates Comma separated list of video bitrates	One or more valid bitrate values separated by commas	270k, 570k, 1000k, 1200k, 1400k
sizes Comma separated list of video sizes	One or more valid size values separated by commas	320x180, 420x270, 720x406, 1024x576, 1080x608

Advanced H.264 Parameters

Could be specified in such way:

<format>
    <video_codec_parameters>
        <keyint_min>25</keyint_min>
		<sc_threshold>40</sc_threshold>
        <!-- other options (see below) -->
    </video_codec_parameters>
</format>

The x264 Project has lead the way on H.264 development by introducing many key features. Variance Adaptive Quantization (VAQ) and Rate–Distortion Optimization (RDO) attempt to preserve video quality and motion estimation against the amount of data required to encode the video. Advanced controls include options for GOP structure, keyframing, scene detection, macroblocking, and interframe quantization. Many of these features are discussed in depth on the x264 forums. A list of the x264 flags available to our API follows:

Frame-Type Options

Option Name	Allowed Values	Default Values
keyint_min The minimum distance between I-frames.	Integer	25
sc_threshold Adjusts the sensitivity of x264's scenecut detection.	Integer	40
bf B-frames.	Integer	16
b_strategy Adaptively decides through a low-resolution lookahead the best number of B-frames.	0, 1, 2	1
flags2 Allows B-frames to be kept as references.	+bpyramid, +wpred, +mixed_refs, +dct8×8, -fastpskip/+fastpskip, +aud	None
coder CABAC is the default entropy encoder used by x264.	0, 1	1(CABAC enabled)
refs This parameter lets one specify how many references can be used, through a maximum of 16.	integer	6
flags Disable loop filter.	-loop/+loop, -psnr/+psnr	+loop (Enabled)
deblockalpha, deblockbeta One of H.264's main features is the in-loop deblocker, which avoids the problem of blocking artifacts disrupting motion estimation.	Integer	0 (Must have '-flags +loop')

Ratecontrol

Option Name	Allowed Values	Default Values
cqp Constant quantizer mode.	Integer	None
crf Constant quality mode (also known as constant ratefactor).	Float	None
qmin Minimum quantizer.	Integer	10
qmax Maximum quantizer.	Integer	50
qdiff Set max QP step.	Integer	4
bt Allowed variance of average bitrate.	Integer	None
i_qfactor Qscale difference between I-frames and P-frames.	Float	0.71
b_qfactor Qscale difference between P-frames and B-frames.	Float	None
chromaoffset QP difference between chroma and luma.	Integer	None
pass	1, 2, 3	None
rc_eq Ratecontrol equation.	String	blurCplx^(1-qComp)
qcomp QP curve compression: 0.0 => CBR, 1.0 => CQP.	Float	0.60
complexityblur Reduce fluctuations in QP (before curve compression).	Float	20.0
qblur Reduce fluctuations in QP (after curve compression).	Float	0.5

Analysis

Option Name	Allowed Values	Default Values
partitions One of H.264's most useful features is the ability to choose among many combinations of inter and intra partitions.	+partp8x8, +partp4x4, +partb8x8, +parti8x8, +parti4x4	None
directpred	Integer	None
flags2 This allows B-frames to use weighted prediction options other than the default. There is no real speed cost for this, so it should always be enabled.	+bpyramid, +wpred, +mixed_refs, +dct8×8, -fastpskip/+fastpskip, –no-fast-pskip/nothing, +aud.	+wpred
me_method	epzs, hex, umh, full	None
me_range MErange controls the max range of the motion search.	Integer	16
subq MErange controls the max range of the motion search.	Integer	6
trellis Trellis chooses the optimal rounding choices for the maximum rate-distortion score, to maximize PSNR relative to bitrate.	0, 1, 2	None

 

Editing Features

Watermarking

Note: Not available for the image output.

<format>
    <!-- Format fields -->
    <logo>
        <logo_source>[LogoURL]</logo_source>
        <logo_x>[LogoLeft]</logo_x>
        <logo_y>[LogoTop]</logo_y>
        <logo_mode>[LogoMode]</logo_mode>
        <logo_threshold>[LogoTreshold]</logo_threshold>
        <logo_transparent>[LogoTransparent]</logo_transparent>
    </logo>
</format>

Field Name	Allowed Values	Default Values
(required) logo_source The URL of the logo image. The image format can be GIF, JPG or PNG.	http://[user[:password]@]hostname[:port]/[path]/[filename] ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes] sftp://[user[:password]@]hostname[:port]/[path]/[filename]	None
logo_x Left offset of logo image	Non-negative integer	10
logo_y Top offset of logo image	Non-negative integer	10
logo_mode Video and watermarking picture mixing mode	0: If the mask color matches the threshold, the logo will be transparent and only the video will be shown. 1: If the mask color is lighter or darker than the threshold value, the logo (watermark) will appear.	1
Note: If your logo source is PNG with alpha-channel, set logo_mode equal to 1 to keep transparency.
logo_threshold Threshold color mask	6-digit hexadecimal 000000—FFFFFF Examples: 000000 — sets color black to transparent mask 808080 — sets color gray to transparent mask	000000

For more information on how to place a watermark, please see here.

Concatenation

With this feature, you can combine multiple source video files into one file. To use this feature via the User Interface, you can add multiple video sources in the "Add Media" section and they will automatically combine into one file (in sequential order) during the encoding process. To utilize this concatenation feature via the API, you should use several <source> elements in your XML request which will be added sequentially during the encoding process. In addition, you can use different source video URLs / locations (HTTP, FTP, S3, CloudFiles) along with different media properties for each source video (format, frame size, bitrate, codec, etc...). [Read more]
For example:

<?xml version="1.0"?>
<query>
    <userid>[UserID]</userid>
    <userkey>[UserKey]</userkey>
    <action>[Action]</action>
    <mediaid>[MediaID]</mediaid>

    <source>[SourceFile]</source>
    <source>[SourceFile1]</source> <!-- if multiple SourceFile added, they will be concatenated -->
    <!-- Source fields -->
    <source>[SourceFileN]</source>

    <!-- Format fields -->
</query>

Closed Captions

<format>
    <!-- Format fields -->
    <closed_captions>
        <source>[CCSource]</source>
        <copy>[yes|no]</copy>
        <extract>[srt|scc]</extract>
		<mux_type>[cea-608|timed-text]</mux_type>
		<language>[LanguageCode]</language>
        <time_offset>[TimeOffset]</time_offset>
	</closed_captions>
</format>

Field Name	Allowed Values	Default Values
source URL to Closed Captions file.	Valid URL to Closed Captions file in one of the following formats: SCC, SubRip, DFXP (TTML), SAMI	None
copy If video has Clossed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and mux them back while encoding. If you want to mux Closed Captions to video in other (than in source video) format, you should specify mux_type.	yes, no	no
mux_type Closed captions mux type	timed-text — Closed Captions would be muxed in video as 3GPP Timed Text track cea-608 — Closed Captions would be muxed in video as cea-608 track (works only with video codec libx264)	None
language Set language of 3GPP Timed Text track. Works only for mux_type=timed-text	either ISO 639-1 2-char code, ISO 639-2 3-char code, or the full language name	None
extract If video has Clossed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and upload them to same destination as result file. If video has multiple text tracks extracted files will have integer suffix.	srt — Closed Captions would be extracted in SubRip format, scc — Closed Captions would be extracted in Scenarist Closed Captions format	None
time_offset Set time offset for time in CC file	positive or negative integer	0

 

Creating Thumbnails

To generate thumbnail images, please specify a separate encoding task with <output>thumbnail</output>

<format>
    <!-- Format fields -->
    <output>thumbnail</output>
    <time>[Time]</time>
    <width>[Width]</width>
    <height>[Size]</height>
    <!-- Destination fields -->
    <destination>[DestFile]</destination>
</format>

Field Name	Allowed Values	Default Values
time Timestamp (in seconds, percentage rate or interval) to capture thumbnail	Non-negative number greater than 0.01 or hh:mm:ss.ms or 1-100% percentage rate. Example 1: use 5! to capture thumbs every 5 seconds. Example 2: use 5% to capture thumbs at 5%.	5
width Thumbnail width (in pixels)	Non-negative integer	None
height Thumbnail height (in pixels)	Non-negative integer	None
use_vtt Join resulting thumbnails in single video tooltip thumbnail (VTT)	yes, no	no
vtt_line_size Set the count of thumbnails in line on VTT image	Non-negative integer	4
Notes: If your specified thumbnail width and height are different from your video's aspect ratio, you may get black spaces added to the thumbnail image. If you specify only width or height, the other will be calculated according to your video size. If both width and height are not specified, the thumbnail will result in the same size as your video. JPEG is the only supported image format for thumbnail images.
Thumbnail time in intervals You can now generate multiple thumbnails in a specified interval using '!'. Thumbnail image files will be named with a number at the end.

 

Video Rotation

Field Name	Allowed Values	Default Values
rotate Video files only. Rotate video picture.	def — don't change anything. Video will be rotated according to Rotation meta data parameter, if it exists 0 — don't rotate and ignore Rotation meta data parameter 90 — rotate by 90 degree CW and ignore Rotation meta data parameter 180 — rotate by 180 degree and ignore Rotation meta data parameter 270 — rotate by 270 degree CW and ignore Rotation meta data parameter	def
set_rotate Set rotation meta-data (MOV only).	0 — don't set anything 90 — rotate by 90 degree CW 180 — rotate by 180 degree 270 — rotate by 270 degree CW source — keep the source value (if any)	0

Cropping

Field Name	Allowed Values	Default Values
crop_top Top crop band size (in pixels)	Even integer	None
crop_left Left crop band size (in pixels)	Even integer	None
crop_right Right crop band size (in pixels)	Even integer	None
crop_bottom Bottom crop band size (in pixels)	Even integer	None

Fade In/Out

Field Name	Allowed Values	Default Values
fade_in Add fade in effect to audio and video streams.	FadeInStart:FadeInDuration — where both parameters are positive float values FadeInStart — start of fade in effect (in seconds) FadeInDuration — duration of fade in effect (in seconds)	None
fade_out Add fade out effect to audio and video streams.	FadeOutStart:FadeOutDuration — where both parameters are positive float values FadeOutStart — start of fade out effect (in seconds) FadeOutDuration — duration of fade out effect (in seconds)	None

Muxing

Note: muxing is supported for only two sources now.
Sample XML to mux video from one source and audio from another:

<?xml version="1.0"?>
<query>
    <action>AddMedia</action>
    <userid>[UserID]</userid>
    <userkey>[UserKey]</userkey>
    <source>[Video source]</source>
    <source>[Audio source]</source>
    <format>
        <output>muxer</output>
        <target>ntsc-dvd</target>
        <maps>0:0,1:0</maps>
    </format>
</query>

Field Name	Allowed Values	Default Values
maps Use to extract tracks from different media	file#:track#, file#:track#	None
target	pal-vcd, pal-svcd, pal-dvd, pal-dv, pal-dv50, ntsc-vcd, ntsc-svcd, ntsc-dvd, ntsc-dv, ntsc-dv50, film-vcd, film-svcd, film-dvd, film-dv, film-dv50	ntsc-dvd

 

Meta Data

Note: Available for the following formats: 3gp, appletv, fl9, iphone, ipod, m4a, mp4, wmv, zune.
Length of metatag value can't be greater than 256 characters.

<format>
    <!-- Format fields -->
    <metadata>
        <title>[Title]</title>
        <copyright>[Copyright]</copyright>
        <author>[Author]</author>
        <description>[Description]</description>
        <album>[Album]</album>
    </metadata>
</format>

Tag Name	Description
author	Source author
title	Title of the media
album	Media album
description	Media description
copyright	Copyright information
copy	Copy metatags from the source media

Split Screen

Combine several sources to one split screen video

<?xml version="1.0"?>  
<query>  
    <!-- Main fields -->
    <source>[SourceFile1]</source>
    ...
    <source>[SourceFileN]</source>
	<split_screen>
        <columns>[ColumnsNumber]</columns>
        <rows>[RowsNumber]</rows>
        <padding_left>[PaddingLeftInPx]</padding_left>
        <padding_right>[PaddingRightInPx]</padding_right>
        <padding_bottom>[PaddingBottomInPx]</padding_bottom>
        <padding_top>[PaddingTopInPx]</padding_top>
    </split_screen>
</query>

Field Name	Allowed Values	Default Values
columns Number of columns in split screen	non-negative integer	Sources count
rows Number of rows in split screen	non-negative integer	1
padding_top Padding (in pixels) from top to split screen's main area	non-negative integer	0
padding_right Padding (in pixels) from right to split screen's main area	non-negative integer	0
padding_bottom Padding (in pixels) from bottom to split screen's main area	non-negative integer	0
padding_left Padding (in pixels) from left to split screen's main area	non-negative integer	0

Video Overlay

<format>
    <!-- Format fields -->
    <overlay>
        <overlay_source>[Overlay1Source]</overlay_source>
        <overlay_x>[Overlay1PositionX]</overlay_x>
        <overlay_y>[Overlay1PositionY]</overlay_y>
        <size>[Overlay1Size]</size>
		<overlay_start>[Overlay1StartInSeconds]</overlay_start>
		<overlay_duration>[Overlay1DurationInSeconds]</overlay_duration>
    </overlay>
    ...
    <overlay>
        <overlay_source>[OverlayNSource]</overlay_source>
        <overlay_x>[OverlayNPositionX]</overlay_x>
        <overlay_y>[OverlayNPositionY]</overlay_y>
        <size>[OverlayNSize]</size>
		<overlay_start>[OverlayNStartInSeconds]</overlay_start>
		<overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
    </overlay>
</format>

Field Name	Allowed Values	Default Values
(required) overlay_source overlay's source URL	Valid url	None
overlay_x overlay's position X	non-negative integer	0
overlay_y overlay's position Y	non-negative integer	0
size overlay's size	WxH where W and H - positive integers	None
overlay_start overlay's start time (in seconds)	positive float value	0
overlay_duration overlay's duration (in seconds)	positive float value	None

Text Overlay

<format>
    <!-- Format fields -->
    <text_overlay>
        <text>[Font1Source]</text>
        <font_source>[Font1Source]</font_source>
        <font_size>[Font1Size]</font_size>
        <font_rotate>[Font1Rotate]</font_rotate>
        <font_color>[Font1Color]</font_color>
        <align_center>[0|1]</align_center>
        <overlay_x>[TextOverlay1PositionX]</overlay_x>
        <overlay_y>[TextOverlay1PositionY]</overlay_y>
        <size>[TextOverlay1Size]</size>
        <overlay_start>[TextOverlay1StartInSeconds]</overlay_start>
        <overlay_duration>[TextOverlay1DurationInSeconds]</overlay_duration>
    </text_overlay>
    ...
	<text_overlay>
        <text>[FontNSource]</text>
        <font_source>[FontNSource]</font_source>
        <font_size>[FontNSize]</font_size>
        <font_rotate>[FontNRotate]</font_rotate>
        <font_color>[FontNColor]</font_color>
        <align_center>[0|1]</align_center>
        <overlay_x>[TextOverlayNPositionX]</overlay_x>
        <overlay_y>[TextOverlayNPositionY]</overlay_y>
        <size>[TextOverlayNSize]</size>
        <overlay_start>[TextOverlayNStartInSeconds]</overlay_start>
        <overlay_duration>[TextOverlayNDurationInSeconds]</overlay_duration>
    </text_overlay>
</format>

Field Name	Allowed Values	Default Values
(required) text Text for overlay	Valid url	None
(required) font_source Font's source URL	Valid url	None
font_size Text font's size	non-negative integer	20
font_rotate Angle on which text should be rotated	integer	0
font_color Font color	6-digits hexadecimal 000000-FFFFFF	000000
align_center Align text by center	0 or 1	0
overlay_x Overlay's position X	non-negative integer	0
overlay_y Overlay's position Y	non-negative integer	0
size Size of the text block	WxH where W and H - positive integers	None
overlay_start Overlay's start time (in seconds)	positive float value	0
overlay_duration Overlay's duration (in seconds)	positive float value	None

Image to Image

<format>
    <!-- Format fields -->
    <output>image</output>
    <image_format>jpg</image_format>
    <resize_method>resize</resize_method>
    <size>560x420</size>
    <keep_aspect_ratio>yes</keep_aspect_ratio>
    <quality>75</quality>
    <dpi>72</dpi>
    <sharpen_radius>1</sharpen_radius>
    <sharpen_sigma>0.5</sharpen_sigma>
    <remove_metadata>no</remove_metadata>
    <!-- Destination fields -->
    <destination>[DestFile]</destination>
</format>

Field Name	Allowed Values	Default Values
(required) image_format Format of resulting image	jpg, png, gif, tiff	jpg
size Size of resulting image	WxH or Wx0 or 0xH or Wx or xH, where W and H are positive integers	None
keep_aspect_ratio Whether to keep width to height ratio of original picture	yes,no	yes
Note: if either width or height is set to 0, keep_aspect_ratio will be yes.
resize_method How the original picture will be transformed to new size	resize, crop, combine	resize
quality JPEG quality	jpg: 1-100 All: none	80
dpi Image DPI	71-1200	72
sharpen_radius Sharpen radius (use 0 in most cases)	0-10	None
sharpen_sigma Sharpen amount (best are 0.5-1.0)	Float: 0, 0.2-10	0
remove_metadata Whether to remove image meta data (including EXIF)	yes, no	no

Slideshow

If you want to create slideshow from your sources you should specify <slideshow>1</slideshow> in Main Fields.

Now we can support following input formats for slideshow: jpeg, png, mpeg audio, mpeg-4, wave.

If audio file was specified - it would be used as audio stream in output slideshow video. If durations of slideshow and audio stream are different - shortest duration will be used.

By default each slide has duration equal to 3 seconds. If you want to change it, you should add duration parameter to your source.

XML example:

<?xml version="1.0"?>
<query>
  <action>AddMedia</action>
  <userid>*</userid>
  <userkey>*</userkey>
  <source>http://www.example.com/Chrysanthemum.jpg</source>
  <source>http://www.example.com/Desert.jpg?duration=5</source>
  <source>http://www.example.com/Hydrangeas.jpg</source>
  <source>http://www.example.com/Jellyfish.jpg</source>
  <source>http://www.example.com/Koala.jpg</source>
  <source>http://www.example.com/Lighthouse.jpg</source>
  <source>http://www.example.com/Penguins.jpg</source>
  <source>http://www.example.com/Tulips.jpg</source>
  <source>http://www.example.com/music.wav</source>
  <slideshow>1</slideshow>
  <region>us-east-1</region>
  <split_screen/>
  <format>
    <output>mp4</output>
    <bitrate>2000k</bitrate>
  </format>
</query>

Sub Account Management

Sub accounts are only a way of a master account to track encoding bandwidth individually among sub accounts, they are not allowed to change from plan to plan, manage billing information or do any actions rather than to create encoding jobs on their own and access limitted client interface. In order to create/manage sub accounts you should recieve permission from Encoding.com administration (contact us!).

Actions

Action	Description
AddSubUser	Add new sub user.
AddTrialUser	Add new Trial user.
UpdateSubUser	Replace information about existing user's data.
DeleteSubUser	Delete specified sub user.
GetUserInfo	Return information about selected user.
GetSubUsers	Return list of all users and all its data.
GetASM	Return average system metric information of selected user.
GetStorageSpace	Return storage space information of selected user.
GetBandwidthStat	Return used encoding traffic of selected user.
GetBandwidthStatGroupDate	Return encoding traffic of selected user. The traffic will be grouped by existing's dates.

 

Parameters

Field	Description
(required) UserID	A unique user identifier. Can be taken from user's page.
(required) UserKey	User's key string. Generated automatically when user is created and can be changed by user.
(required) Action	The action to be performed.
action_user_id	An unique identifier of user. This field is required for the following actions: UpdateSubUser DeleteSubUser GetUserInfo GetASM GetStorageSpace GetBandwidthStat GetBandwidthStatGroupDate
user_data	This data include the registration information (required), and the contact information(optional) about user. This field is required for the following actions: AddSubUser AddTrialUser UpdateSubUser Below you can see the required registration fields: — for AddSubUser action: login, email, password — for AddTrialUser action: login, email, password, phone, first_name, last_name, company The optional contact data may be following: phone first_name last_name company city zip country state addres
date_from date_to	This field may be specified for the GetBandwidthStat and GetBandwidthStatGroupDate actions when you intend to recieve bandwidth's statistic specified interval. The date must be in format: YYYY-MM-DD.

Request XML Format

AddTrialUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>addTrialUser</action>
	<user_data>
		<email>[Email]</email>
		<login>[Login]</login>
		<password>[Password]</password>
		<first_name>[FirstName]</first_name>
		<last_name>[LastName]</last_name>
		<phone>[Phone]</phone>
	</user_data>
</query>

AddSubUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>AddSubUser</action>
	<user_data>
		<email>[Email]</email>
		<login>[Login]</login>
		<password>[Password]</password>
		<first_name>[FirstName]</first_name>
		<last_name>[LastName]</last_name>
		<phone>[Phone]</phone>
	</user_data>
</query>

UpdateUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>UpdateSubUser</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<user_data>
		<email>[New email]</email>
		<phone>[New phone]</phone>
	</user_data>
</query>

DeleteUser action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>DeleteSubUser</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetUserInfo action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetUserInfo</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetSubUsers action

<?xml version="1.0"?>
<query>
<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>getsubusers</action>
</query>

GetASM action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetASM</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetStorageSpace action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetStorageSpace</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetBandwidthStat action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetBandwidthStat</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<date_from>[YYYY-MM-DD]</date_from>
	<date_to>[YYYY-MM-DD]</date_to>
</query>

GetBandwidthStatGroupDate action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetBandwidthStatGroupDate</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<date_from>[YYYY-MM-DD]</date_from>
	<date_to>[YYYY-MM-DD]</date_to>
</query>

Response Format

The response for API request can vary depending on action:

AddTrialUser action

<?xml version="1.0"?>
<response>
	<action>addtrialuser</action>
	<status>Success</status>
	<result>
		<plan>Trial 1 GB</plan>
		<user_id>1839</user_id>
		<user_key>f851cae31d705c08a157b8f32f3cc121</user_key>
		<message>The new trial user has been created</message>
	</result>
</response>

AddSubUser action

<?xml version="1.0"?>
<response>
	<action>addsubuser</action>
	<status>Success</status>
	<result>
		<plan>[Plan]</plan>
		<user_id>1840</user_id>
		<user_key>38772a155045fc49a4b9f6d24efee4e6</user_key>
		<message>The new sub user has been created</message>
	</result>
</response>

UpdateUser action

<?xml version="1.0"?>
<response>
	<action>updatesubuser</action>
	<status>Success</status>
	<result>
		<user_id>1800</user_id>
		<message>The user data was updated</message>
		<email>[New Email]</email>
		<country>[New Country]</country>
	</result>
</response>

DeleteSubUser action

<?xml version="1.0"?>
<response>
	<action>deletesubuser</action>
	<status>Success</status>
</response>

GetUserInfo action

<?xml version="1.0"?>
<response>
	<action>getuserinfo</action>
	<status>Success</status>
	<result>
		<user_id>1800</user_id>
		<ID>1800</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</result>
</response>

GetSubUsers action

<?xml version="1.0"?>
<response>
	<action>getsubusers</action>
	<status>Success</status>
	<result>
	<user_id>6</user_id>
	<user_0>
		<ID>[UserID]</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</user_0>
	<user_1>
		<ID>[UserID]</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</user_1>
	...
	</result>
</response>

GetASM action

<?xml version="1.0"?>
<response>
	<action>getasm</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<encoding_success_rate>
			<percentage>100</percentage>
		</encoding_success_rate>
		<queue_time>
			<second>[average queue time in this month]</second>
		</queue_time>
		<processing_time>
			<second>[average processing time in this month]</second>
		</processing_time>
		<connection_speed>
			<kbs>[average connection speed]</kbs>
		</connection_speed>
		<encoding_bandwidth>
			<gb>[average amount of encoding bandwidth]</gb>
		</encoding_bandwidth>
	</result>
</response>

GetStorageSpace action

<?xml version="1.0"?>
<response>
	<action>getstoragespace</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<gb>[Storage Space]</gb>
	</result>
</response>

GetBandwidthStat action

<?xml version="1.0"?>
<response>
	<action>getbandwidthstat</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<date_from>[Date from]</date_from>
		<date_to>[Date to]</date_to>
		<in>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</in>
		<out>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</out>
		<turbo>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</turbo>
	</result>
</response>

GetBandwidthStatGroupDate action

<?xml version="1.0"?>
<response>
	<action>getbandwidthstatgroupdate</action>
	<status>Success</status>
	<result>
		<user_id>[userID]</user_id>
		<date_[date1]>
			<in>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</in>
			<out>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</out>
		</date_[date1]>
		<date_[date2]>
			<in>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</in>
			<out>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</out>
		</date_[date2]>
		...
	</result>
</response>

Errors

Error Messages appears in the response if the action was failed.

Error	Description
Common errors
No XML	No XML query provided in the request.
Wrong XML	The XML query provided in the request is not well-formed.
Wrong query format	The XML does not contain <query> root element.
Invalid action	The Action parameter is empty or is not in the list of allowed actions.
Authentication Errors
Wrong User ID or Key	The UserID/UserKey pair was not found.
Add/Update sub users validation Errors
You don't have permission to create trial users	You cannot create trial users.
You don't have permission to create sub users	You cannot create sub users.
You don't have permission to manage this user	You can manage only users who had been created by you.
action_user_id : User not found	User with id which you set doesn't exist.
action_user_id : This field is required	action_user_id is required field for following actions: UpdateSubUser DeleteSubUser GetUserInfo GetSubUsers GetASM GetStorageSpace GetBandwidthStat GetBandwidthStatGroupDate

 

API Responses

The response for API request can vary depending on the following actions:

AddMedia

<?xml version="1.0"?>
<response>
	<message>Added</message>
	<MediaID>[MediaID]</MediaID>
</response>

GetMediaList

<?xml version="1.0"?>
<response>
	<media>
		<mediafile>["SourceFile"]</mediafile>
		<mediaid>["MediaID"]</mediaid>
		<mediastatus>Closed</mediastatus>
		<createdate>[Date]</createdate>
		<startdate>[Date]</startdate>
		<finishdate>[Date]</finishdate>
	</media>
	<media>
	...
	</media>
</response>

Where Date is of the format: YYYY-MM-DD HH:MM:SS

GetStatus

<?xml version="1.0"?>
<response>
	<id>[MediaID]</id>
	<userid>[UserID]</userid>
	<sourcefile>[SourceFile]</sourcefile>
	<status>[MediaStatus]</status>
	<notifyurl>[NotifyURL]</notifyurl>
	<created>[Date]</created>
	<started>[Date]</started>
	<finished>[Date]</finished>
	<prevstatus>[MediaStatus]</prevstatus>
	<downloaded>[Date]</downloaded>
	<uploaded>[Date]</uploaded>
	<time_left>[TotalTimeLeft]</time_left>
	<progress>[TotalProgress]</progress>
	<time_left_current>[StatusTimeLeft]</time_left_current>
	<progress_current>[StatusProgress]</progress_current>   
	<format>
		<id>[ID]</id>
		<status>[Status]</status>
		<created>[Date]</created>
		<started>[Date]</started>
		<finished>[Date]</finished>
		[FormatFields]

		<s3_destination>[TempS3Link]</s3_destination> <!-- optional -->
		<cf_destination>[TempCFLink]</cf_destination> <!-- optional -->
		<destination>[URL]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
		<destination>[URL_2]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
		...
		<destination>[URL_N]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
	</format>

	<format>
	…
	</format>
</response>

Field Name	Description
Date	is of the format: YYYY-MM-DD HH:MM:SS
FormatFields	is a set of fields corresponding to the <format> section of a user's API request
TotalTimeLeft	is an estimated time until the media processing will complete
StatusTimeLeft	is an estimated time remaining for the media's current status
TotalProgress	is an estimated progress for the entire media processing (in percent)
StatusProgress	is an estimated progress for the media's current status (in percent)
TempS3Link	S3 URL for the encoded file only if the <destination> was empty and result put to S3
TempCFLink	CDN URL for the encoded file only if the <destination> was empty and result put to Rackspace CloudFiles
MediaStatus	can take the following values: 'New', 'Downloading', 'Ready to process', 'Waiting for encoder', 'Processing', 'Saving', 'Finished', 'Error'.
Status	can take the following values: 'New', 'Waiting for encoder', 'Processing', 'Saving', 'Finished', 'Error'.

GetStatus (extended)

Used to request the status of several medias in a single request:

Request:

<?xml version="1.0"?>
<query>
	<action>GetStatus</action>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<extended>yes</extended>
	<mediaid>[CommaSeparatedList]</mediaid>
</query>

Response:

<?xml version="1.0"?>
<response>
	<job>
		<id>[MediaID]</id>
		<userid>[UserID]</userid>
		<sourcefile>[SourceFile]</sourcefile>
		<status>[MediaStatus]</status>
		<notifyurl>[NotifyURL]</notifyurl>
		<created>[Date]</created>
		<started>[Date]</started>
		<finished>[Date]</finished>
		<prevstatus>[MediaStatus]</prevstatus>
		<downloaded>[Date]</downloaded>
		<filesize>[FileSize]</filesize>
		<processor>[AMAZON | RACKSPACE]</processor>
		<progress>[TotalProgress]</progress>
		<time_left>[TotalTimeLeft]</time_left>

		<format>
			<id>[ID]</id>
			<status>[Status]</status>
			<created>[Date]</created>
			<started>[Date]</started>
			<finished>[Date]</finished>
			<s3_destination>[TempS3Link]</s3_destination> <!-- optional -->
			<cf_destination>[TempCFLink]</cf_destination> <!-- optional -->
			<convertedsize>[FileSize]</convertedsize>
			<time_left>[TotalTimeLeft]</time_left>
			<progress>[TotalProgress]</progress>
			<time_left_current>[StatusTimeLeft]</time_left_current>
			<progress_current>[StatusPorgress]</progress_current>
			<file_size>[FileSize]</file_size>
			<destination>[URL]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
			<destination>[URL_2]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
			...
			<destination>[URL_N]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
		</format>

		<format>
		…
		</format>
	</job>

	<job>
	...
	</job>
</response>

GetMediaInfo

<?xml version="1.0"?>
<response>
	<bitrate>1807k</bitrate>
	<duration>6464.83</duration>
	<video_codec>mpeg4</video_codec>
	<video_bitrate>1679k</video_bitrate>
	<frame_rate>23.98</frame_rate>
	<size>640x352</size>
	<pixel_aspect_ratio>1:1</pixel_aspect_ratio>
	<display_aspect_ratio>20:11</display_aspect_ratio>
	<audio_codec>ac3</audio_codec>
	<audio_sample_rate>48000</audio_sample_rate>
	<audio_channels>2</audio_channels>
</response>

Parameters Description

Field Name	Description
bitrate	Total bitrate for the media file.
duration	Tracks duration in seconds.
pixel_aspect_ratio	Pixel's rectangle width/height ratio (1:1 = square pixel).
display_aspect_ratio	Video frame's width/height ratio.
audio_channels	Number of audio channels (commonly 1, 2 or 5.1).
Note: for each particular media, some parameters can be omitted.

Other Actions

<?xml version="1.0"?>
<response>
	<!-- Message section -->
	<message>[Message]</message>
	<!-- Errors section -->
	<errors>
		<error>[Error]</error>
		<error>[Error]</error>
		…
	</errors>
</response>

API Error Responses

Common Errors

Error Message	Description
No XML	No XML query provided in the request
Wrong XML	The XML query provided in the request is not correctly formatted
Wrong query format	The XML does not contain root element
Invalid action	The Action parameter is empty, or is not in the list of allowed actions
Wrong user id or key	The user ID / user key pair was not found

Media Errors

Error Message	Description	Actions
Media ID is not indicated	The MediaID parameter is omitted in the query	UpdateMedia, GetStatus
Wrong source file URL	The URL provided in the query does not match a single URL of valid formats	AddMedia, UpdateMedia
Source file is not indicated	The SourceFile parameter is empty	AddMedia, UpdateMedia
Wrong Media ID	The media with such ID was not found	UpdateMedia, GetStatus

Queue Errors

Error Message	Description	Actions
No formats specified	There is no single <format> element present in the query	AddMedia, UpdateMedia
No output format specified	The <output> element of the format is omitted or has an empty value	AddMedia, UpdateMedia
Output format [Output] is not allowed	The <output> element of the format is not in the list of allowed formats	AddMedia, UpdateMedia
Wrong destination file URL	The URL provided in the query does not match a single URL of valid formats.	AddMedia, UpdateMedia
Internal Error	Internal program error. A description will follow.	All

 

Recent API Changes