The XML API Overview
XML format for user’s API request
Server Response XML format
Error Messages
Encoding Result XML format

The XML API Overview

The communication with the encoding.com is realized through a single interface: by sending HTTP(S) requests to the manage.encoding.com/. All client requests and server answers use XML format. Client must send HTTP(S) POST request with single parameter named xml.
The server response is a normal XML document.

XML format for user’s API request

<?xml version="1.0"?>

<query>

<!-- Main fields -->

    <userid>[UserID]</userid>

    <userkey>[UserKey]</userkey>

    <action>[Action]</action>

    <mediaid>[MediaID]</mediaid>

    <source>[SourceFile]</source>

    <notify>[NotifyURL]</notify>

    <format>

<!-- Format fields -->

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

        <size>[Size]</size>

        <crop_left>[Crop Left]</crop_left>

        <crop_top>[Crop Top]</crop_top>

        <crop_right>[Crop Right]</crop_right>

        <crop_bottom>[Crop Bottom]</crop_bottom>

        <thumb_time>[Thumb time]</thumb_time>

        <thumb_size>[Thumb size]</thumb_size>

        <add_meta>[yes/no]</add_meta>

<!-- Destination fields -->

        <destination>[DestFile]</destination>

        <thumb_destination>[Thumb Dest]</thumb_destination>     

    </format>

</query>

Fields values

Main fields

UserID – an unique user identifier. Can be taken from user’s page.
UserKey – user’s key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
- AddMedia – add new media to user’s media list, creates new items in a queue according to formats specified in XML
- AddMediaBenchmark - add new media to user's media list and set a flag for NOT processing it after downloading. Format fields could be specified as well. If NotifyURL is set, a notification will be sent after the media will have been ready for processing.
- UpdateMedia – replace information about existing media's formats. All old format items will be deleted, and the new ones added.
- ProcessMedia - start encoding of previously downloaded media (one that added with AddMediaBenchmark action)
- CancelMedia – delete specified media and all its items in queue
- GetMediaList – return list of user’s media
- GetStatus – return information about selected user’s media and all its items in queue
- GetMediaInfo - returns some video parameters of the specified media, if available
MediaID – an unique identifier of media. This field must be specified for the following actions: UpdateMedia, CancelMedia, GetStatus.
SourceFile – media source file. It can be in the following formats: http://[user]:[password]@ [server]/[path]/[filename] or ftp://[user]:[password]@[server]/[path]/[filename] or sftp://[user]:[password]@[server]/[path]/[filename] or http://[bucket].s3.amazonaws.com/[filename] – 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. This field must be specified only for AddMedia and AddMediaBenchmark actions.
NotifyURL – could be either an HTTP(S) URL of the script the result would be posted to, or a mailto: link with email address the result info to be sent. This field may be specified for AddMedia and AddMediaBenchmark actions.

Format fields

Note: There may be more than one <format> elements in a single query

Output (required) – output format. Specify format of encoded file.

Allowed values:
flv, fl9, wmv, 3gp, mp4, m4v, ipod, iphone, appletv, psp, zune, vp6* and thumbnail**.
Default: none
* - see VP6 Features chapter below
** - see Thumbnail Features chapter below

size [optional] - Video frame size.

Allowed values:

All: WxH, whereW and N are any non-zero even integers.
3gp: 128x96, 176x144, 352x288, 704x576, 1408x1152
ipod: 320x240, 640x480
iphone: 480x368
appletv: 710x480
zune: 320x180, 320x240

Default:

All: none
3gp: 176x144
iphone: 480x368
appletv: 710x480
psp: 368x192
zune: 320x180

bitrate [optional] - Video bitrate.

Allowed values:

Nk - where N is any non-zero integer.

Default:

All: 512k
3gp: 256k
ipod, iphone, psp: 1024k

framerate [optional] - Frame rate.

Allowed values:

any non-zero integer or N/M where N and M are non-zero integers.

Default:

All: 25
psp: 30000/1001

video_codec [optional] - Video codec.

Allowed values:

flv: flv
fl9: libx264
wmv, zune: wmv2, msmpeg4
3gp: h263
mp4, m4v, ipod, iphone, appletv, psp: mpeg4

Default:

flv: flv
fl9: libx264
wmv, zune: wmv2
3gp: h263
mp4, m4v, ipod, iphone, appletv, psp: mpeg4

audio_bitrate [optional] - Audio bitrate.

Allowed values:

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, zune: 32k, 40k, 48k, 56k, 64k, 80k, 96k, 112k, 128k, 144k, 160k, 192k, 224k, 256k, 320k

Default:

All: 64k
3gp: 12.2k
ipod, iphone, psp: 128k

audio_sample_rate [optional] - Audio sampling frequency (Hz).

Allowed values:

All: any non-zero integer.
3gp: 8000
flv: 11025, 22050, 44100
wmv, zune: 11025, 22050, 32000, 44100, 48000

Default:

All: none
3gp: 8000
flv, zune: 44100

audio_codec [optional] - Audio codec.

Allowed values:

flv: libmp3lame
fl9, mp4, m4v, ipod, iphone, appletv, psp: libfaac
wmv, zune: wmav2, libmp3lame
3gp: libamr_nb

Default:

flv: libmp3lame
fl9, mp4, m4v, ipod, iphone, appletv, psp: libfaac
wmv, zune: wmav2
3gp: libamr_nb

audio_channels_number [optional] - Number of audio channels.

Allowed values:

All: any non-zero integer.
3gp: 1

Default:

All: 2
3gp: 1

two_pass [optional] - Whether to use 2-pass encoding

Allowed values:

yes, no

Defualt:

cbr [optional] - Whether to use CBR (Constant bitrate)

Allowed values:

yes, no

Defualt:

deinterlacing [optional] - Whether to use de-interlacing

Allowed values:

yes, no

Defualt:

crop_top [optional] - Top crop band size (in pixels).

Allowed values:

even integer

Default:

None

crop_left [optional] - Left crop band size (in pixels).

Allowed values:

even integer

Default:

None

crop_right [optional] - Right crop band size (in pixels).

Allowed values:

even integer

Default:

None

crop_bottom [optional] - Bottom crop band size (in pixels).

Allowed values:

even integer

Default:

None

thumb_time [optional] - Timestamp (in seconds) to capture thumbnail.

Allowed values:

integer

Default:

None

thumb_size [optional] - Thumbnail size (in pixels).

Allowed values:

WxH, where W and H are any non-zero integers.

Default:

None

add_meta [optional] - FLV only. Whether to add meta data to the file.

Allowed values:

yes, no.

Default:

All: None
flv: no

Destination fields

destination [optional] - The destination URL to put the encoded file.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename][?passive=yes],
sftp://[user]:[password]@[server]/[path]/[filename],
http://[bucket].s3.amazonaws.com/[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).

Default:

None

thumb_destination [optional] - The destination URL to put the thumbnail.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename],
http://[bucket].s3.amazonaws.com/[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).

Default:

None

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.

VP6 Features

If you choose vp6 for output format, your XML query will differ (you can specify only two parameters in addition to output at format fields section):

    <format>

    <!-- Format fields -->

        <output>vp6</output>

        <profile>[VP6 profile]</profile>

        <size>[Size]</size>

    <!-- Destination fields -->

        <destination>[DestFile]</destination>

    </format>

The specific parameter profile is added:

profile [optional] – VP6 profile.

Allowed values:

VP6-E, VP6-S

Default: VP6-E

destination [required] - The destination URL to put the encoded file.

Note: There must be only one <format> for each profile per one source media. In other words, you must not send more than two vp6 <format> items per media, and they must have different profiles.

Thumbnail Features

Instead of using thumb_ parameters within <format>, you can specify 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>

With the following specific parameters:

time [optional] – Timestamp (in seconds) to capture thumbnail.

Allowed values:

Non-negative number greater than 0.01 or hh:mm:ss.ms

Default: 5

width [optional] - Thumbnail width (in pixels)

Allowed values:

Non-negative integer

Default: none

height [optional] - Thumbnail height (in pixels)

Allowed values:

Non-negative integer

Default: none

destination [optional] - The destination URL to put the thumbnail.

If you specify both width and height, you'll get a thumbnail with these dimensions, and if your video have another aspect ratio than the thumbnail, black spaces will be added to the picture.
If you specify only one parameter from this pair, the other one will be calculated according to your video size.
If none of those parameters specified, the thumbnail will have the same size as your video have.
Now only JPEG format is supported for thumbnails.

Server Response XML format

The response for API request can vary depending on action:

AddMedia action

<?xml version="1.0"?>

<response>

    <message>Added</message>

    <MediaID>[MediaID]</MediaID>

</response>

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

GetStatus action

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

    </format>

    <format>

    …

    </format>

</response>

Where Date is of the format: YYYY-MM-DD HH:MM:SS
FormatFields is a set of fields corresponding to <format> section of an user’s API request
TotalTimeLeft is an estimated time until the media processing would be finished
StatusTimeLeft is an estimated time left for the media's current status
TotalProgress is an estimated progress for entire media processing (in percent)
StatusProgress is an estimated progress for the media's current status (in percent)
TempS3Link S3 URL of the encoded file, if the <destination> was empty

GetMediaInfo action

<?xml version="1.0"?>

<response>

    <bitrate>364k</bitrate>

    <duration>175.21</duration>

    <video_codec>h264</video_codec>

    <frame_rate>23.98</frame_rate>  

    <audio_sample_rate>44100</audio_sample_rate>        

    <size>352x288</size>

</response>

Other actions

<?xml version="1.0"?>

<response>

    <!-- Message section -->

    <message>[Message]</message>

    <!-- Errors section -->

    <errors>

        <error>[Error]</error>

        <error>[Error]</error>

        …

    </errors>

</response>

Error Messages

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

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 has not in the list of allowed actions

Authentication Errors

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