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]</region> 
        <audio_sync>[1..N]</audio_sync> 
        <force_interlaced>tff|bff|no</force_interlaced>
    </format> 
</query>

* Video codec settings

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>

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

Note: Not available for the following formats: image.

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

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

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

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

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

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  

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

source - Set original rotation value

Server Response XML format

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

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

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

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>

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

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

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

Note: for each particular media, some parameters can be omitted.

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

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

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/userkey pair was not found

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> 

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