Complete API Documentation - API Docs

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

The XML API Overview

To send API requests to Encoding.com, please send HTTP(S) post requests to 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.

Complete Example of an API Post

<?xml version="1.0"?>
<query>
<!-- Main fields -->
    <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>[SourceFileN]</source>
    <notify>[NotifyURL]</notify>
    <instant>[yes|no]</instant>
    <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_volume>[Volume]</audio_volume>       
        <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_transparent>[LogoTransparent]</logo_transparent> 
        </logo> 

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

        <region>[us-east-1|us-west-1|us-west-2|eu-west-1|ap-southeast-1|ap-northeast-1|sa-east-1]</region> 
        <audio_sync>[1..N]</audio_sync> 
        <force_interlaced>tff|bff|no</force_interlaced>
        <strip_chapters>[yes|no]</strip_chapters> 
    </format> 
</query>

* Video codec settings

Concatenate Videos

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>
<!-- Main fields -->
    <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>[SourceFileN]</source>

Main Fields

Format Name	Description
UserID	A unique user identifier. This 3-5 digits number can be found in the My Account tab of the Client Interface.
UserKey	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 (see list immediately below for definitions).
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 is specified.
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.
MediaID	A unique identifier for each media. This field must be specified for the following actions: UpdateMedia, CancelMedia, GetStatus.
SourceFile	Source media file. Must be specified only for AddMedia and AddMediaBenchmark actions. It can be in the following formats: 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] 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 http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees 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: 1ZG3YAKJ8W0VOA9L7WT6 lQT5MsQLirc8owb: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 http://en.wikipedia.org/wiki/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 (TM) 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
SourceFile1..SourceFileN	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.
NotifyURL	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.
instant	Set to 'yes' to initiate the encoding process immediately when source video begins downloading to our processing center as opposed to waiting until after the download has completed. Also, this feature can be used when source media is still uploading to the specified source FTP location - our system will recognize if the source file size increases while downloading, or soon after, and the "tail" will be downloaded and concatenated.

Logo fields

Note: Not available for the following formats: image.

Format 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, 1	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-digits hexadecimal 000000-FFFFFF	000000

How Mode and Threshold work

logo_mode 0: If the mask color matches the threshold, the logo will be transparent and only the video will be shown.

logo_mode 1: If the mask color is lighter or darker than the threshold value, the logo (watermark) will appear.

Samples:

<logo_threshold>000000</logo_threshold> –– sets color black to transparent mask

<logo_threshold>808080</logo_threshold> –– sets color gray to transparent mask

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

Advanced H.264 Parameters

Could be specified in such way:

<format>
            ...
            <video_codec_parameters>
                <keyint_min>25</keyint_min>
                ...
                ...
            </video_codec_parameters>
</format>

To see all available parameters please follow this link

Profile option

Format 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

VP6 Features

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 a multiple of 16.

Note: old-style requests with

vp6

are deprecated and will be automatically converted to the new form. parameter will be ignored at all.

VP6 Flix Features

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

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

With the following specific parameters:

Format Name	Allowed Values	Default Values
vp6_profile Encoding profile	1 - VP6_E or 2 - VP6_S	1
noise_reduction Determines the level of noise filtering to apply in the preprocessor. 0 is no preprocessing, 6 is extreme preprocessing.	[0,6]	Bits per pixel dependent
upct Parameter for undershoot percentage	0-100 percentage	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 or 2 — BEST	1

Image 2 Image Features

<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>
        <sharpen_radius>1</sharpen_radius>
        <sharpen_sigma>0.5</sharpen_sigma>
        <remove_metadata>no</remove_metadata>
    <!-- Destination fields -->
        <destination>[DestFile]</destination>
    </format>

Format 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. If either width or height is set to 0, keep_aspect_ratio will be yes.	yes, no	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
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 (incl. EXIF)	yes, no	no

Turbo Encoding option

Format 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
NOTE: Additional encoding bandwidth charges apply. Please view the Turbo Encoding Help Article for more details.

Thumbnail Features

To generate thumbnail images, please specify a separate encoding task with output = thumbnail:

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

Thumbnail specific parameters:

Format 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

Destination: The destination URL to put the thumbnail.

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.

Destination fields

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

Allowed Values

Default Values

destination

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:

1ZG3YAKJ8W0VOA9L7WT6
lQT5MsQLirc8owb: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 http://docs.amazonwebservices.com/AmazonS3/latest/dev/index.html?ACLOverview.html for more details.

- See http://en.wikipedia.org/wiki/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

http(s)://[access_key]@[account].blob.core.windows.net/[container]/path

access_key should be urlencoded

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

None

Metadata fields

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.

title — Title of the media
copyright — Copyright information
author — Source author
description — Media description
album — Media album
copy — copy metatags from the source media

iPhone Streaming Features

<format>
    <!-- Format fields -->
        <output>[iphone_stream|ipad_stream]</output>
        <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>
    <!-- Destination fields -->
        <destination>[DestFile]</destination> <!-- REQUIRED -->
    </format>

Format Name	Allowed Values	Default Values
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	no
encryption Encrypt TS segements using AES-128	yes, no	no
encryption_key Encryption key	32 hexidecimal characters ([0-9a-f])	None
encryption_key_file Encryption key file URL	HTTP, FTP, SFTP or S3/CloudFiles URL	None

Server Response XML format

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

Format Fields

One or more <format> elements are required for AddMedia and UpdateMedia actions. They may contain the following child elements:

source - Set original rotation value

Option	Allowed Values	Default Values
(required) output Format type	flv, fl9, wmv, 3gp, mp4, m4v, ipod, iphone, ipad, android, ogg, webm, appletv, psp, zune, mp3, wma, m4a, thumbnail, image, 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, vidly, kindle_fire.	None.
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).
bitrate Video bitrate	All: Nk (where N is any non-zero integer)	All: None 3gp: 256k iOS, Android, PSP: 1024k
framerate Frame rate	All: any non-zero integer or N/M where N and M are non-zero integers	All: none psp: 30000/1001
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	flv: flv fl9, ipod, iphone, ipad: libx264 wmv, zune: wmv2 3gp: h263 mp4, m4v,appletv, psp, android: mpeg4 ogg: libtheora webm: libvpx mpeg2: mpeg2video
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
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_codec Audio codec	mp3: libmp3lame m4a: libfaac flv: libmp3lame, libfaac fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp: libfaac wmv, wma, zune: wmav2, libmp3lame ogg, webm: libvorbis 3gp: libamr_nb android: libamr_nb, libfaac mpeg2: pcm_s16be, pcm_s16le mpegts: ac3	flv, mp3: libmp3lame fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp: libfaac wmv, zune: wmav2 ogg, webm: libvorbis 3gp, android: libamr_nb mpeg2: pcm_s16be 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_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 (%)	non-negative integer	100
two_pass 2-pass encoding toggle	yes, no	no
cbr CBR (Constant bitrate) toggle	yes, no	no
acbr CBR (Constant bitrate) for audio stream toggle. Use only with vorbis (Ogg, Webm).	yes, no	no
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
bufsize Rate control buffer size (bits)	N or Nk - where N is any non-zero integer	None
keyframe Keyframe period (in frames)	positive integer	300
start Start encoding from (sec)	non-negative integer	None
duration Duration (sec)	positive 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
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). If you will specify this parameter equal to 0, fade out effect will be applied to the end of video/audio FadeOutDuration - duration of fadeOut effect (in seconds)	None
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
keep_aspect_ratio 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	None
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
rotate Rotate video picture. Only works with video files.	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
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
keyframe	12 [12 PAL DVD] , 15 [15 NTSC DVD], 25 [25 PAL Long GOP], 30 [30 NTSC Long GOP]	15
bframes	2 [on = IBBPBBP], 0 [off = IPPPPPP]	2
gop	sgop [Strict (Locked)], cgop [Closed (Scene Detection)]	cgop
maps Only works for `output=muxer`. To extract tracks from different media	file#:track#,file#:track#	None
target Only works for `output=muxer`.	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
luma_spatial Spatial luma strength	[0,255]	4
chroma_spatial Spatial chroma strength	[0,255]	3
luma_temp Temporal luma strength	[0,255]	6
region Allow you to specify instance's region where your file should be processed	us-east-1 - US (Nothern Verginia), us-west-1 - US (Nothern 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 Amerika (Sou Paulo)	us-east-1
two_pass_decoding Decode to a lossless format prior to encoding to reduce errors.	1	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
force_interlaced Interlaced encoding type	mpegts: tff,bff,no	mpegts: tff
strip_chapters Strip chapters markers	yes, no	no

Twin-Turbo Encoding option

Format Name	Allowed Values	Default Values
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.

Server Response XML format

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

GetMediaList action

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

AddMedia action

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

GetStatus action — Simple Mode

Simple mode

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

Format 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 action — Extended (Batch) Mode

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

Request:

<query>
        <action>GetStatus</action>
        <userid>[UserID]</userid>
        <userkey>[UserKey]</userkey>
        <extended>yes</extended>
        <mediaid>[CommaSeparatedList]</mediaid>
</query>

Response:

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

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

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

Encoding Result XML — XML Callback

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>

Fields values

Format Name	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 http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees 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

Common Errors

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

Authentication Errors

Wrong user id or key — The user ID/userkey pair was not found

Source Media Handling Errors

Format Name	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 Handling Errors

Format Name	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

Muxing from different sources

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

<?xml version="1.0"?>
<query>
  <action>AddMedia</action>
  <userid/>
  <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>

Wowza Multi-Bitrate Features

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

Format 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

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

Sample XML API Format

Additional XML API Calls

XML API Error Messages

The XML API Overview

Complete Example of an API Post

Concatenate Videos

Main Fields

Logo fields

How Mode and Threshold work

Advanced H.264 Parameters

Profile option

VP6 Features

VP6 Flix Features

Image 2 Image Features

Turbo Encoding option

Thumbnail Features

Thumbnail time in intervals

Destination fields

Metadata fields

iPhone Streaming Features

Server Response XML format

Format Fields

Twin-Turbo Encoding option

Server Response XML format

GetMediaList action

AddMedia action

GetStatus action — Simple Mode

Simple mode

GetStatus action — Extended (Batch) Mode

GetMediaInfo action

Parameters Description

Other actions

Encoding Result XML — XML Callback

Fields values

Common Errors

Authentication Errors

Source Media Handling Errors

Queue Handling Errors

Muxing from different sources

Wowza Multi-Bitrate Features

Video Format Conversions

Mobile Encoding

Features

Follow us

Subscribe to the Encoding Newsletter

Who is Clive?

Service Descriptions

Developer Resources

Support

Get Started

Legal Eagle