API 1.0

From Aviberry API

Jump to: navigation, search

Aviberry API calls can be executed by requests via GET and POST methods. Generally, URL request for GET method looks this way: 

http://api_key:api_pass@aviberry.com/api/v1/protocol/method?param=value

, where

  • api_key and api_pass - key and password of user authentication while API calling (mandatory fields);
  • protocol - working data-interchange protocol: "json" or "xml" (mandatory field);
  • method - method name of call (mandatory field);
  • param and value - name and value of parameter transferred to method.


Therefore if the call is executed via GET method, than method name and corresponding parameters are included into the URL request. URL request for POST method looks in other way: 

http://api_key:api_pass@aviberry.com/api/v1/protocol/

In this case name and parameters of called method are coded in the body of POST request. For JSON-RPC protocol there should be a JSON-encoded object with method and parameters coded in terms of standard in the body of request, and XML-RPC protocol should contain XML-encoded object with the same coded appropriate methods and parameters of request. Depending on the protocol the call has been executed, server will respond in the according format. All transferred string data should be in UTF-8 charset unless otherwise specified.

Key and password for API access are generated and re-generated by user on his/her account page at any time.


Contents


API methods

All API methods have camelCase - style names, and should be pointed in such a way during call: both in URL request for GET method and in the body of request for POST method. While API GET method call all parameters values should be coded according to the standard.

There are the following types of methods parameters: string, array or object. Object parameters allow additional nesting levels, as subobjects. All API methods return objects with call results as their output: JSON-object for JSON-RPC or XML-structure for XML-RPC.

"Object" can be defined as an associated array,i.e set of pairs name=value. Depending on the protocol request such an "object" should be displayed either as JSON-object for JSON-RPC or as XML-structure for XML-RPC.

For GET method calls, the "object" should be transferred according to the arrangement where each object property with specified value should be coded in the URL and each element appears as separate parameter: 

object[property]=value
object[property][subproperty]=value
object[property][subproperty][subsubproperty]=value
 and so on

, where [ and ] symbols are mandatory syntax items. Furthermore, object properties will be indicated according to the syntax.

"Array" can be defined as usual array where elements are indexed from 0. Depending on the protocol request such an "array" should be displayed either as JSON-array for JSON-RPC or as XML-array for XML-RPC.

For GET method calls, the "array" should be transferred according to the arrangement where each array element with specified value should be coded in the URL and each element appears as separate parameter: 

object[]=value // object[0]
object[]=value // object[1]
object[]=value // object[2]
and so on

, where [ and ] symbols are mandatory syntax items.

For GET method calls, boolean value true can be coded as '1', 'true' or 'yes'. Other values are considered as false.

Proposed implementaton of GET method object transfer "violates" an official specification. According to specification objects are not transferred via GET at all, but not-associated one-dimension array can be executed. Given statement is right only for JSON-RPC. For XML-RPC GET requests are not prescribed in standard but they will be accepted and processed in case of described above execution. For JSON-RPC there is no standard "violation" but separate parameters which are specially called can be transferred.

Developers can use external libraries for Aviberry API calls, so they can avoid manual forming body of request as well as processing server response. Below there is a list of popular libraries for different programming languages:

PHP
JSON-RPC for PHP
XML-RPC for PHP

Using these libraries one should send all requests by POST method because no one external library knows about described above agreement for GET method parameters transfer. The possibility of API GET method calls is available for general "completeness" of solution and can be useful in special situations because sending GET method request is an easy and fast way to call any Aviberry API method avoiding external means.

startConversion

This method creates and starts conversion with required parameters and returns the object with information about method execution.

Signature 

object startConversion(
    mixed  source_url,
    string target_url,
    object converter,
    object preview = {},
    object callback = {},
    object params = {},
    object data = {}
)

Parameters

Parameter Type Description
source_url mixed Video file source URL or an array of URLs. When URL array is specified, all converted source files will be joined into one target file defined in target_url. Such behavior is similar to turned-on join function in desktop converters. The following URL types are accepted: 
http|https://[user[:password]@]hostname[:port]/[path]/[filename]
ftp|ftps://[user[:password]@]hostname[:port]/[path]/[filename]
http://[user:password@]bucket.s3.amazonaws.com/[path]/[filename]

URL should be formalized according to standard, i.e all special symbols should be "percent-encoded".

target_url string URL where the file will be located after conversion. URL must include the name of file-output.There is an error message in case of no name pointed. All symbols after last slash / considered as file name. The following URL types are accepted: 
ftp|ftps://[user[:password]@]hostname[:port]/[path]/filename
http://user:password@bucket.s3.amazonaws.com/[path]/filename
mailto:email

In last case an email will be sent with a message about conversion and a link to file download. File output name is not specified and will be automtically generated. After conversion completion aviberry.com provides the hosting to file-output for 24-hour period, when file should be downloaded. At the expiration of the mentioned period the link to download will be invalid.

URL should be formalized according to standard, i.e all special symbols should be "percent-encoded".

converter object Mandatory object with converter settings:
Property Type Description
format_id integer Digital format identifier. Mandatory property. See section Supported formats.
preset_id integer Preset identifier which should be used for the format. Preset can be pre-defined or created by user. See section Formats and presets.
preset_data string JSON-string which is encoded object with specific preset settings. Each supported format has a set of specific preferences. See section Presets parameters
transform object Object with transformation settings of target file. The object's properties are necessary actions for target file. See section Transformations.

The object properties with converter settings are processed in the following way:

  • If only converter[format_id] property is specified, than source file will be converted to the specified format. Default preset will be used for the given format(the first preset specified for the format in the table of section Pre-defined presets).
  • If both properties converter[format_id] and converter[preset_id] are specified, than source file will be converted to the specified format using the required preset.
  • If all properties converter[format_id], converter[preset_id] and converter[preset_data] are specified, than source file will be converted to the specified format using the required preset, but specified settings will be overridden with individual ones.
  • If only converter[format_id] and converter[preset_data] properties are specified, than source file will be converted to the specified format using only pointed individual preset settings.
preview object Optional object with preview settings. Preview is a picture from the centre of video file. Object with settings has the following properties:
Property Type Description
width integer Desired width of picture preview in pixels. 160 pixels are by default.
height integer Desired height of picture preview in pixels. 120 pixels are by default.
resize_method integer See mapping ResizeMethod. RM_LETTERBOX is by default, i.e. 1.
resize_quality integer See mapping ResizeQuality. RQ_BEST is by default, i.e. 1.

Any preview parameter can be omitted. In this case specified default values will be used. Link to the picture preview will be available in case of finished conversion status(see method getProgress) and is generated in the following way: preview_url = target_url + '.jpg'.

callback object Optional object with settings of callback function that will be called after conversion completion. Possible keys and values:
Property Type Description
url string API address with callback function.
method string Name of necessary callback function.
protocol string Protocol which should be used for call. The value should be the string "json" for JSON-RPC protocol call.

There will be an RPC call of callback[method]method done by means of POST request to the address callback[url] according to RPС protocol specified in the parameter callback[protocol]. During the call the following parameters will be transferred to the method:

Parameter Type Description
conversion object Conversion information is the same as from getConversion method.

An example of request sending by JSON-RPC protocol: 

?
POST <URI, received from callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Hostname, received from callback[url]>
Content-Type: application/json
Content-Length: ...

{
    "version" : "1.1",
    "method" : "callback[method]",
    "params" : 
    {
        "conversion" : {...}
    }
}


An example of request sending by XML-RPC protocol: 

?
POST <URI, received from callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Hostname, received from callback[url]>
Content-Type: text/xml
Content-length: ...

<?xml version="1.0"?>
<methodCall>
    <methodName>callback[method]</methodName>
    <params>
        <param>
            <value>
                <struct>
                    <member>
                        <name>conversion</name>
                        <value><struct>...</struct></value>
                    </member>
                </struct>
            </value>
        </param>
    </params>
</methodCall>

params object Optional object with additional parameters of method execution. Every object property corresponds to some parameter. At the moment the following properties/parameters are defined:
Property Type Description
overwrite_target_file boolean Should file in target_url be overwritten in case of already existing file. 1 - overwrite, 0 - not overwrite. Default value is 0, i.e. at the try to overwrite existing file an exception will be thrown.
source_url_encoding string Encoding of transferred source filename. Default value is UTF-8. See about parameter in details in section Encoding.
source_filename_encoding string Actual source filename encoding which is required for file access in the file system. Default value is UTF-8. See about parameter in details in section Encoding.
target_url_encoding string Same as source_url_encoding, but for target_url. Default value is UTF-8.
target_filename_encoding string Same as source_filename_encoding, but for target_url. Default value is UTF-8.
s3_storage_class string Storage class for files located on Amazon S3. Possible values are STANDARD or REDUCED_REDUNDANCY. Default value is STANDARD.

Any parameter can be omitted. In this case specified default values will be used.

data object Optional object with user data that will be associated with creating conversion. The given object will be returned for conversion received via different methods, for example getConversion or getConversions. Actually, the object contains user data in form of pairs key/value.

Return object

Property Type Description
conversion_id string Identifier of created conversion.

cancelConversion

This method cancels the conversion started by startConversion method. If the conversion process already started, i.e source files started to convert, then the process would be stopped.

Signature 

object cancelConversion(
    string conversion_id
)

Parameters

Parameter Type Description
conversion_id string Identifier of conversion that should be canceled.

Return object

Property Type Description
success boolean Flag of call output(success/fail).

deleteConversion

This method deletes the conversion. "Delete" means that specified conversion will not be in the output of getConversions method. Only finished or canceled conversion can be deleted (see section Conversion statuses). All finished or canceled conversions which were not deleted by user keep available during limited time only. After expiration they will be deleted automatically. Currently, availability period is set up 1 week.

Signature 

object deleteConversion(
    string conversion_id
)

Parameters

Parameter Type Description
conversion_id string Identifier of conversion that should be deleted.

Return object

Property Type Description
success boolean Flag of call output(success/fail).

getConversion

This method returns the complete information about separate conversion. The function accepts a parameter - an identifier of conversion which is returned by startConversion method. Returns either JSON-object or XML-structure with data about specified conversion according to used protocol.

Signature 

object getConversion(
    string conversion_id
)

Parameters

Parameter Type Description
conversion_id string The identifier of conversion with necessary information to get.

Return object

Property Type Description
conversion_id string The identifier of conversion for which the information returned.
source_url array The value represents source_url, specified during conversion creation. Note that URL array returns always. I.e if at the beginning of conversion only one URL as string parameter is specified in source_urlparameter while startConversion method, then the array with one element will be returned.
target_url string The value represents target_url, specified during conversion creation.
converter object The value represents an actual object with converter settings converter, specified during conversion creation. Hereinafter, the term "actual object" means an original object whose unused properties were changed by default values.
preview object The value represents an actual object with preview settings preview, specified during conversion.
callback object The value represents an actual object with callback function settings callback, specified during conversion.
params object The value represents an actual object with execution settings params,specified during conversion.
data object The object with user data data, associated with creating conversion.
status string Conversion status which can contain one of the values specified in section Conversion statuses. In order to get more detailed information about current conversion status one should use getProgress method.
result_url string Link to conversion output. Depending on the selected receiver it can differ from target_url.
preview_url string Link to preview picture.
time_created string GMT time of conversion creation and queueing. Time is displayed in the format of YYYY-MM-DD HH:MM:SS.
time_started string GMT time of starting conversion process. Time is displayed in the format of YYYY-MM-DD HH:MM:SS.
time_finished string GMT time of termination conversion process. Time is displayed in the format of YYYY-MM-DD HH:MM:SS.
error_code integer Error code. See section Error codes list.
error_mess string Extended error message. See section Error codes list.

getConversions

This methods returns the information about existing conversions.

Signature 

object getConversions(
    object filter = null
)

Parameters

Parameter Type Description
filter object Optional object with filter settings for conversion sorting. The object is designed for future usage.

Return object

Return object contains the pairs key/value, where key - is a conversion identifier, and value - the information about corresponding conversion which is identical to conversion data returned by getConversion method.

getProgress

After starting the conversion passes through variety of statuses. One can get the detailed information about current conversion status by means of this function.

Signature 

object getProgress(
    string|array(string) conversion_id
)

Parameters

Parameter Type Description
conversion_id string|array(string) The identifier of conversions whose progress is neccessary to get.

Return object

  • If the conversion identifier was specified as string in conversion_id parameter, then the object is returned.
  • If the conversion identifier was specified as array of strings in conversion_id parameter, then the array of objects is returned.
Property Type Description
conversion_id string The identifier of conversion for which the information returned.
status string Conversion status which can contain one of the values specified in section Conversion statuses. In order to get more detailed information about current conversion status one should use getProgress method.
percent integer The percentage of subtask execution from 0 till 100.
elapsed_time integer Time in seconds passed since conversion start, i.e actual value is contained only for сonverting status.
remaining_time integer Time in seconds left till the end of conversion, i.e actual value is contained only for сonverting status.
error_code integer Error code. See section Error codes list.
error_mess string Extended error message. See section Error codes list.

getTraffic

Returns the information about user traffic.

Signature 

object getTraffic()

Parameters

Absent.

Return object

Returns the object with 3 properties: total, tariffed and purchased. Each property is an object with total, tariffed and purchased traffic information with its own properties used and limit, described below.

Property Type Description
limit string Limit of traffic in bytes available for user. As byte value can be large enough and exceed "standard" integer - 4 bytes, then value is returned as string. The client should convert it into required numerical representation if necessary.
used string Value of already used traffic in bytes. As byte value can be large enough and exceed "standard" integer - 4 bytes, then value is returned as string. The client should convert it into required numerical representation if necessary.

Conversion statuses

Status Description
notfound Conversion with specified identifier is not found.
queued Conversion is queued.
downloading File for conversion is downloading.
сonverting File converting.
uploading Conversion result is uploading.
finished Conversion is finished.
canceled Conversion is canceled by user.


Conversion is queued at the creation and start (queued). After its turn came the conversion starts processing. Source file for conversion is downloading (downloading)and converting (сonverting). Then the result is uploading to the specified resource (uploading). After uploading conversion is finished (finished).

Conversion is finished in case of error at any processing stage (finished), herein error_code will be non-zero and error_mess will contain the extended error message.

Queued but not processing conversion can be canceled. In this case the conversion becomes canceled (canceled).

Formats and presets

Conversion process consists in file recoding from current format to another specified format where converting into target format takes place with certain settings. The suite of such settings for the target format is called preset. Initially one or more commonly used presets for all formats are preinstalled already and they are available via corresponding identifier. User is also allowed to create and save his/her own presets on the account page for further usage as well as to use the identifiers of created presets in API calls (see description of startConversion method). Tables of supported formats, pre-defined presets and possible preferences are presented below.

Supported formats

Identifier Name File output extension
16500 AVI (DIVX; XVID; etc) avi
16501 MPEG1;2 (DVD; SVCD; VCD) mpg
16503 WMV wmv
16505 MPEG4 (iPod; MP4) mp4
16506 3GPP (GSM) 3gp
16507 3GPP2 (CDMA) 3gp2
16508 QuickTime mov
16509 Flash flv
16511 MP3 mp3
16520 WebM webm

Pre-defined presets

Identifier Name
AVI
442 AVI - Audio-Video Interleaved
MPEG1,MPEG2
8 DVD PAL Compatible
7 DVD NTSC Compatible
3 VCD NTSC Compatible
4 VCD PAL Compatible
5 SVCD NTSC Compatible
6 SVCD PAL Compatible
891 MPEG Best Quality
WMV
1493 WMV Video
13 WMV 9 for VHS quality video
14 WMV 9 for DVD quality video (1 mbps)
15 WMV 9 for DVD quality video (2 mbps)
468 WMV HD Video (720p, 4:3)
469 WMV HD Video (1080p, 4:3)
467 WMV HD Video (720p, 16:9)
470 WMV HD Video (1080p, 16:9)
2334 Video for PowerPoint
MPEG4
446 MPEG4 Video
2336 MPEG4 Video (High Quality)
896 HD MPEG4 720p
2734 HD MPEG4 720p (High Quality)
899 HD MPEG4 1080p
3148 HD MPEG4 1080p (High Quality)
901 HD H.264 720p
3150 HD H.264 720p (High Quality)
903 HD H.264 1080p
2736 HD H.264 1080p (High Quality)
920 iPod (320x240)
2739 iPod (320x240) (High Quality)
921 iPod 5G (640x480)
2740 iPod 5G (640x480) (High Quality)
924 iPhone (480x320)
2744 iPhone (480x320) (High Quality)
934 Video for PSP
2746 Video for PSP (High Quality)
3GP
894 Mobile Phone 3GP Video (352x288)
3GP2
895 Mobile Phone 3GP2 Video (352x288)
MOV
892 MOV - QuickTime Video
Flash
533 FLV - Optimal Quality (320x240, H.264/AAC)
542 FLV - Normal Quality (384x288, H.264/AAC)
543 FLV - Best Quality (480x360, H.264/AAC)
948 FLV - H.264 Flash Video
949 FLV - H.263 Flash Video
MP3
120 Audio Only: MP3 High Quality
WebM
2335 WebM

Presets parameters

Lists of possible presets parameters for each format with corresponding values for pre-defined presets are presented below. Lists are displayed according to JSON-notation.

AVI 


442

AVI - Audio-Video Interleaved
{
    [+] "VideoCodec" : 879783277,
    
        Description
    
    [+] "Width" : 320,

        Description2
    
    [+] "Height" : 240,
    
        Description3
    
    [+] "WPerc" : 100,
    
        Description4
    
    [+] "HPerc" : 100,
    
        Description5
    
    [+] "FrameRate" : "25",
    
        Description6
    
    [+] "LinkSizes" : true,
    
        Description7
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        Description8
    
    [+] "ResizeQuality" : RQ_BEST,
    
        Description9
    
    [+] "VideoSAsInput" : false,
    
        Description10
    
    [+] "AudioCodec" : -1,
    
        Description
    
    [+] "Freq" : FQ_44KHZ,
    
        Description
    
    [+] "Channels" : 2
    
        Description13
    
}

MPEG 1, 2 


8 | 7 | 891 | 3 | 4 | 6

DVD PAL Compatible
{
    [+] "Type" : 222002,
    
        0 - MPEG1, 2 - MPEG2.
    
    [+] "VideoBitrate" : 402540254025115011502415,
    
       Description
    
    [+] "VBRQuality" : 0,
    
       Description
    
    [+] "VideoSAsInput" : falsefalsetruefalsefalsefalse,
    
       Description
    
    [+] "Width" : 720720720352352480,
    
       Description
    
    [+] "Height" : 576480576240240576,
    
       Description
    
    [+] "ResizeMethod" : RM_LETTEROX,
    
        See mapping ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        See mapping ResizeQuality.
    
    [+] "FrameRate" : "25""29.97""25""29.97""25""25",
    
    
    [+] "AspectRatio" : 220002,
    
        Description
    
    [+] "IsSound" : true,
    
        Description
    
    [+] "AudioBitrate" : 224,
    
        Description
    
    [+] "Frequency" : FQ_48KHZFQ_48KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZ,
    
        Description
    
    [+] "Channels" : 2,
    
        Description
    
    [+] "JointStereo" : false,
    
       Description
    
}

WMV 

	
1493 | 13 | 14 | 15 | 468 | 469 | 467 | 470 | 2334	
WMV Video	
{	
    [+] "VideoCodec" : 861293911,
	
        Description.	
    	
    [+] "VideoBitrate" : -1326656999424199987247994888192000479948881920002048000,    
 		
        Description. -1 = auto.	
    	
    [+] "VideoQuality" : 857075858585858585,
 		
        Description.	
    	
    [+] "VideoSAsInput" : truefalsefalsefalsefalsefalsefalsefalsefalse,
	
        Description.	
    	
    [+] "Width" : 1280320640640960144012801920640,
    
 	Description.	
    	
    [+] "Height" : 72024048048072010807201080480,
    
 	Description.	
    	
    [+] "ResizeMethod" : RM_LETTEROX,
 		
        See mapping ResizeMethod.	
    	
    [+] "ResizeQuality" : RQ_BEST,
 		
        See mapping ResizeQuality.	
    	
    [+] "FrameRate" : "2529.9729.9729.972525252530",
 		
        Description.	
    	
    [+] "VideoBuffer" : 5000,
 		
        Description.	
    	
    [+] "ProfileNum" : 0,
 		
        Description.	
    	
    [+] "WMV" :
 		
        Description.	
    	
    {	
        [+] "VBR" : 0,
 		
        Description.	
        	
        [+] "VBRMaxBitrate" : 0,
	
         Description.	
        	
        [+] "VBRQuality" : 0,	
    
 	Description.	
        	
        [+] "VidBuffer" : 5000,
 	
        Description.	
        	
        [+] "VBRMaxBuff" : 0,
 	
        Description.	
        	
    }	
    [+] "AudioCodec" : 353,
 		
        Description.	
    	
    [+] "AudioBitrate" : 192000640006400064000192000192000192000192000192000,
 		
        Description.	
    	
    [+] "Frequency" : FQ_48KHZ,
 		
        Description.	
    	
    [+] "Channels" : 2,
 		
        Description.	
    	
    [+] "AudioBuffer" : 5000-1-1-150005000500050005000,
 		
        Description. -1 = auto	
    	
    [+] "WMA" :
 		
        Description.	
    	
    {	
        [+] "IsAV" : false,	
 		
        Description.	
        	
        [+] "VBR" : 0,
 		
        Description.	
        	
        [+] "VBRQuality" : 192656565192192192192192, 	

        Description.	
        	
    }

MPEG 4 


446 | 896 | 899 | 901 | 903 | 920 | 921 | 924 | 934

MPEG4 Video
{
    [+] "VideoCodec" : C_MPEG4C_MPEG4C_MPEG4C_H264C_H264C_MPEG4C_MPEG4C_MPEG4C_MPEG4,
    
        See mapping Codec.
    
    [+] "Width" : 3201280192012801920320640480368,
    
       Description
    
    [+] "Height" : 24072010887201088240480320208,
    
       Description
    
    [+] "WPerc" : 100,
    
       Description
    
    [+] "HPerc" : 100,
    
       Description
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        See mapping ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        See mapping ResizeQuality.
    
    [+] "FrameRate" : "25""25""25""25""25""25""25""25""29.97",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "MPEG4""MPEG4""MPEG4""H264""H264""MPEG4""MPEG4""MPEG4""MPEG4" : 

        
        {
	    [+] "Profile" : 244244244448888,
    
               Description
            
	    [+] "Bitrate" : 250000010000000150000001000000150000057200025000001000000504000,
    
               Description
            
	    [+] "Quality" : 333223333
    
               Description
            
            [+] "VBR" : false
    
               Description
            
        }
    }

    [+] "AudioCodec" : C_ACC,
    
        See define Codec.
    
    [+] "Frequency" : FQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_48KHZFQ_48KHZFQ_24KHZ,
    
        Description
    
    [+] "Channels" : CH_STEREO,
    
        Description
    
    [+] "AParams" : 
    
    
    {
        [+] "ACC" : 

        
        {
	    [+] "Profile" : 2,
    
                Description
            
	    [+] "Bitrate" : 12800019200019200019200019200012800012800012800096000,
    
               Description
            
	    [+] "Quality" : 100
    
               Description
            
	}
    }

    [+] "PSPMode" : falsefalsefalsefalsefalsefalsefalsetrue,
    
        Description
    
    [+] "VideoSAsInput" : truefalsefalsefalsefalsefalsefalsefalsetrue,
    
        Description
    
    [+] "LinkSizes" : true,
    
        Description
    
}

3GP 


894

Mobile Phone 3GP Video (352x288) 
{
    [+] "VideoCodec" : C_H263,
    
        See mapping Codec.
    
    [+] "Size" : 11534480,
    
        Description
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        See mapping ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        See mapping ResizeQuality.
    
    [+] "FrameRate" : "15",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H263" : 

        
        {
	    [+] "Bitrate" : 128000,
    
               Description
            
	    [+] "Quality" : 30
    
               Description
            
	    [+] "VBR" : false,
    
               Description
            
	    [+] "MotionSrchRng" : 15,
    
               Description
            
	}
    }

    [+] "AudioCodec" : C_AMR,
    
        See mapping Codec.
    
    [+] "Frequency" : FQ_8KHZ,
    
        Description
    
    [+] "Channels" : CH_MONO,
    
        Description
    
    [+] "AParams" : 
    
    
    {
        [+] "AMR" : 

        
        {
	    [+] "Bitrate" : 12200,
    
                Description
            
	}
    }
}

3GP2 


895

Mobile Phone 3GP2 Video (352x288)
{
    [+] "VideoCodec" : C_H263,
    
        See mapping Codec.
    
    [+] "Size" : 11534480,
    
        Description
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        See mapping ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        See mapping ResizeQuality.
    
    [+] "FrameRate" : "15",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H263" : 

        
        {
	    [+] "Bitrate" : 128000,
    
                Description
            
	    [+] "Quality" : 30
    
                Description
            
	    [+] "VBR" : false,
    
                Description
            
	    [+] "MotionSrchRng" : 15,
    
                Description
            
	}
    }

    [+] "AudioCodec" : C_AMR,
    
        See mapping Codec.
    
    [+] "Frequency" : FQ_8KHZ,
    
        Description
    
    [+] "Channels" : CH_MONO,
    
        Description
    
    [+] "AParams" : 
    
    
    {
        [+] "AMR" : 

        
        {
	    [+] "Bitrate" : 12200,
    
                Description
            
	}
    }
    [+] "b3GPP2Mode" : true,
    
        Description
    
}

MOV

Flash 


533 | 542 | 543 | 948 | 949

FLV - Optimal Quality (320x240, H.264/AAC)
{
    [+] "VideoCodec" : C_H264,
    
        See mapping Codec.
    
    [+] "Width" : 320384480320320,
    
        Description
    
    [+] "Height" : 240288360240240,
    
        Description
    
    [+] "WPerc" : 100,
    
        Description
    
    [+] "HPerc" : 100,
    
        Description
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        See mapping ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        See mapping ResizeQuality.
    
    [+] "FrameRate" : "15""25""25""25""25",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H264" : 

        
        {
            [+] "AvcC" : true,
    
                Description
            
	    [+] "Profile" : 2,
    
                Description
            
	    [+] "Bitrate" : 51200076800010000001200000128000,
    
                Description
            
	    [+] "Quality" : 000015
    
                Description
            
	}
    }

    [+] "Frequency" : 44100,
    
        Description
    
    [+] "Channels" : CH_MONOCH_STEREOCH_STEREOCH_STEREOCH_STEREO,
    
        Description
    
    [+] "AudioBitrate" : 64128160128128,
    
        Description
    

    [+] "VideoSAsInput" : falsefalsefalsetruetrue,
    
        Description
    
    [+] "LinkSizes" : true,
    
        Description
    
    [+] "IsSound" : true,
    
        Description
    
}

MP3 


120

Audio Only: MP3 High Quality
{
    [+] "Frequency" : 0,
    
        Description
    
    [+] "Channels" : CH_AUTO
    
        Description13
    
    [+] "Bitrate" : 2
    
        Description13
    
    [+] "StereoMode" : 2
    
        Description13
    
    [+] "VBR" : -1
    
        Description13
    
}

WebM 


2335

WebM
{
   [+] "VideoBitrate" :         1000000,
 	
        Description.
     
     [+] "VideoQuality" : 1,
 		
        Description.
     
     [+] "VideoSAsInput" : true,
 		
        Description. 	
     
    [+] "Width" : 240,
 		
        Description. 	
     
    [+] "Height" : 320,
 		
        Description. 		
     
    [+] "ResizeMethod" : RM_LETTEROX,    
 		
        See mapping ResizeMethod.	
    	
    [+] "ResizeQuality" : RQ_BEST,
 		
        Seemapping ResizeQuality. 		
     		
    [+] "FrameRate" : "25",
 		
        Description. 	
    	
    [+] "Audio" : true,
 		
        Description.	
    	
    [+] "AudioBitrate" : 128000,
 	
        Description. 	
    	
    [+] "Frequency" : FQ_44KHZ,
 		
        Description. 		
    	
    [+] "Channels" : 2,
 		
        Description. 		
    	
}

Transformations

During the file conversion process you can edit your video to enhance movie, improve its quality and apply different effects to it. For example, you can crop video, change its contrast settings or add a watermark to the video and so on. All possible transformations are listed below. Transformations is specified in startConversion method.

Cutting video

This transformation cuts out a part of your video. Operation name which should be used for customization - cut. The format of parameters specification: 

start_interval units, end_interval units
Parameter Type Description
start_interval integer The interval where the cut fragment is started from. If the parameter is omitted, the fragment will be cut from the beginning of file. The length of interval is defined by units parameter.
end_interval integer The interval where the cut fragment is stopped. If the parameter is omitted, the fragment will be cut till the end of file. The length of interval is defined by units parameter.
units string Interval unit. The possible values are: 'h' (hours), 'm' (minutes), 's' (seconds), 'ms' (milliseconds).

At least one parameter should be specified during customization. Intervals can be complex. Examples: 

converter[transform][cut] = '1000,10s' //Cuts out 9 seconds of video, starting from the 1st second of file.
converter[transform][cut] = '1m,' //Cuts out the fragment from 1 minute till the end of file.
converter[transform][cut] = ',10m17s'//Cuts out 10 minutes 17 seconds of video from the start of file.

Splitting video

This transformation splits the file by size or time of playing. Operation name which should be used for customization - split. The format of parameters specification: 

amount units
Parameter Type Description
amount integer Time duration or fragment size of video splitting. The parameter depends on units parameter.
units string The unit of amount parameter. The possible values are: 'h' (hours), 'm' (minutes), 's' (seconds), - then amount is considered as time duration of fragment, or: 'gb' (gigabytes), 'mb' (megabytes), 'kb' (kilobytes), - then amount is considered as size of fragment.

Both parameters are mandatory. If the time duration is specified, then minimal possible unit is 1 minute ('1m' = '60s'). If the fragment size is specified, then minimal possible unit is 10 Mb ('10mb' = '1024kb').

Interval or size can be complex.Examples: 

converter[transform][split] = '1m30s' // Splits video into fragments of 1m30s duration.
converter[transform][split] = '1h'   // Splits video into fragments of 1h duration.
converter[transform][split] = '50mb'   // Splits video into fragments of 50 Mb size.

Cropping video

This transformation crops the part of video fragment remained beyond the borders. Operation name which should be used for customization - сrop. The format of parameters specification: 

top, right, bottom, left

or 

padding
Parameter Type Description
top float Padding top. Relative value which is defined as ratio of padding to frame height. Default value is 0.0.
right float Padding right. Relative value which is defined as ratio of padding to frame width. Default value is 0.0.
bottom float Padding bottom. The same as top. Default value is 0.0.
left float Padding left. The same as right. Default value is 0.0.
padding float Equal padding for top, right, bottom and left.

During the first format using at least one of the mentioned parameters should be specified. Omitted parameters accept default values. During the second format using the only option is mandatory. Examples: 

converter[transform][crop] = '0.2,0.1,0.2,0.1' // Crops the fragment on top/ bottom by 20% and right/left by 10% of its original size.
converter[transform][crop] = ',0.1,,0.1' // Crops the fragment on the right/left by 10% of its original size .
converter[transform][crop] = '0.2,0.1,,' //Crops the fragment on top by 20% and on the right by 10% of its original size.
converter[transform][crop] = '0.1'// Crops the fragment by 10% from all sides.

Rotating video

This transformation rotates video picture. Operation name which should be used for customization - rotate. The format of parameters specification: 

mode
Parameter Type Description
mode string Rotation direction. The possible values are: 'cw' (clockwise) - clockwise rotation by 90°, 'ccw' (counterclockwise) - counterclockwise rotation by 90°, 'usd' (upside down) - rotation by 180°.

Example: 

converter[transform][rotate] = 'cw' // Rotates video by 90 degrees clockwise.

Watermark

This transformation adds a "watermark" to the video. Watermark can be either a recognizable image or a text pattern as well as both of them. Operation name which should be used for customization - watermark. To configure watermark one should specify image settings, text settings and general options separately.

Image settings. Operation parameter name which should be used for customization - image.

Parameter Type Description
image string Link to the image file. Mandatory parameter. The following URL types are accepted: 
http|https://[user[:password]@]hostname[:port]/[path/][filename]
ftp|ftps://[user[:password]@]hostname[:port]/[path/][filename]
http://[user:password@]bucket.s3.amazonaws.com/[path/][filename]

URL should be formalized according to standard, i.e all special symbols should be "percent-encoded".

size string Size format: 
scale, aspect
Parameter Type Description
scale float Scaling factor of the block. Relative value, which is defined as the ratio of the final block value to its initial value. "Block" can be regarded as an area occupied by the image or text. For example, scaling factor 2.0 means that the block is increased twice. Optional parameter. Default value is 1.0.
aspect mixed The ratio of block width to its height. "Block" can be regarded as an area occupied by the image or text. Optional parameter. Default value is 0.0, i.e image preserves the original aspect ratio. The value can be specified as a number with a decimal point or as a string of ratio. For example, you can specify either 1.333, or '4:3' as a parameter value.
position string Position format: 
vertical, horizontal

or 

align
Parameter Type Description
vertical float Top (positive value) or bottom (negative value) padding from frame edge to block center. Relative value, which is defined as the ratio of padding to the height of the frame. "Block" can be regarded as an area occupied by the image or text. For example, the coefficient 0.1 means the top padding by 10%, -0.1 means the bottom padding by 10%. Optional parameter. Default value is 0.0.
horizontal float Left (positive value) or right negative value)padding from frame edge to block center. Relative value, which is defined as the ratio of padding to the width of the frame. "Block" can be regarded as an area occupied by the image or text. For example, the coefficient 0.1 means left padding by 10%, -0.1 means right padding by 10%. Optional parameter. Default value is 0.0.
align string The alignment of block as to the frame. "Block" can be regarded as an area occupied by the image or text. Possible values ​​are 'top', 'top_right', 'right', 'bottom_right', 'bottom', 'bottom_left', 'left', 'top_left', 'center'.

During the first format using at least one of the mentioned parameters should be specified. Omitted parameters accept default values. During the second format using the only option is mandatory.

Text settings. Operation parameter name which should be used for customization - text.

Parameter Type Description
text string Text for watermark. Field is mandatory.
size string Parameter equal to size parameter for image.
position string Parameter equal to position parameter for image.
font string Font format 
face, style, size, color
Parameter Type Decription
face string Typeface name. Optional parameter. Default value is 'Arial'.
style string Type style. The possible values are: 'regular', 'bold', 'italic', 'bold_italic'. Optional parameter. Default value is 'regular'.
size float Font size. Relative value, which is defined as the ratio of the font size to the frame size. Optional parameter. Default value is 0.05.
color string Text color in RGB, where each color component is defined by hexadecimal numbers. Optional parameter. Default value is '000000' (black).

General options. Every general option is treated as separate property of operation. List of general options is presented below.

Parameter Type Description
transparency float Transparency of the watermark. The possible values are from 0.0 (opaque) to 1.0 (transparently). Default value is 0.0.

Any optional parameter can be omitted. In this case they accept specified default values.Example: 

converter[transform][watermark][image][image] = 'http://example.org/watermark.png' // Sets the specified image as watermark.
converter[transform][watermark][image][size] = '1.5,4:3' //Increases the picture by 50% and sets the ratio of 4:3 (1.333).
converter[transform][watermark][image][position] = '-0.2,0.3' // Shifts the image by 20% below and by 30% left.
converter[transform][watermark][text][text] = 'My Watermark' //Sets the specified text as watermark.
converter[transform][watermark][text][size] = '2' //Increases text 2 times and the ratio of the text block is left unchanged.
converter[transform][watermark][text][position] = 0.9,0.9 //Shifts the text to the bottom right corner of the frame.
converter[transform][watermark][text][font] = ',italic,,ff0000' // Sets italic font and red color for text.
converter[transform][watermark][transparency] = '0.5' // Makes the watermark half-transparent.

Adjusting video

This transformation enhances your video image. Operation name which should be used for customization - adjust. The operation consists of a set of sub-operations which are treated as separate properties and presented below.

Parameter Type Description
magic_enhance boolean Default value is false.
auto_contrast boolean Automatic contrast adjustment. Default value is false.
auto_whitebalance boolean Auto White Balance. Default value is false.
deblocking boolean Default value is false.
deinterlacing boolean Deinterlace. Default value is false.
brightness integer Brightness. The possible values are from -70 to 70. Default value is 0.
сontrast integer Contrast. The possible values are from 128 to 384. When value is 256 contrast is not changed. Default value is 256.
hue integer Hue. The possible values are from -180 to 180. When value is 0 hue is not changed.
saturation integer Saturation. The possible values are from -100 to 100. When value is 0 saturation is not changed.

Examples: 

converter[transform][adjust][deinterlacing] = true // Removes interlace.
converter[transform][adjust][contrast] = 300    // Defines the contrast.

Mappings

ResizeMethod

Value Name Description
0 RM_STRETCH Aspect-ratio is not saved, the whole source picture is framing without margins.
1 RM_LETTERBOX Aspect-ratio is saved, the whole source picture is framing with black margins.
2 RM_CROP Aspect-ratio is saved, the part of picture is framing without margins.

ResizeQuality

Value Name Description
0 RQ_NORMAL Near approximation (bad quality).
1 RQ_BEST Bilinear approximation (best quality).

Codec

Value Name Description
"mp4v" C_MPEG4 MPEG4 in Wikipedia
"s263" C_H263 H.263 in Wikipedia
"avc1" C_H264 H.264 in Wikipedia
"mp4a" C_AAC AAC in Wikipedia
"samr" C_AMR AMR in Wikipedia

Frequency

Value Name Description
48000 FQ_48KHZ Frequency 48000 Hz.
44100 FQ_44KHZ Frequency 44100 Hz.
32000 FQ_32KHZ Frequency 32000 Hz.
24000 FQ_24KHZ Frequency 24000 Hz.
22050 FQ_22KHZ Frequency 22050 Hz.
16000 FQ_16KHZ Frequency 16000 Hz.
12000 FQ_12KHZ Frequency 12000 Hz.
11025 FQ_11KHZ Frequency 11025 Hz.
8000 FQ_8KHZ Frequency 8000 Hz.
6000 FQ_6KHZ Frequency 6000 Hz.

Channels

Value Name Description
0 CH_AUTO Automatically.
1 CH_MONO Mono (1 channel).
2 CH_STEREO Stereo (2 channel).

Encoding

Filenames

Let's see API method startConversion in details. The section below can be skipped if the filenames contain only Latin symbols. In case there are national characters in the names, the conversion can be not created.

Let's take processing of source_url, i.e. processing of source filename. As it mentioned above, source filename should be formalized according to standard, i.e. all special symbols should be "percent-encoded". After getting this parameter service performs reconversion and receives a "standard" name of source file for further usage.

Determination of source file existance is the next step. New converted filename will be used for that. But actually the source filename in server filesystem where file is located can be in other charset than transferred filename. Then service can not determine file existance using the received name.

With the couple of the following parameters source_url_encoding and source_filename_encoding for source filename, one can tell service that "transferred source filename for method is in source_url_encoding charset, but filename on server filesystem where file is located should be in charset source_filename_encoding (actual encoding)." I.e. it is possible to define some transformation "rule" of transferred source filename, and service will perform this transformation.

Let's see an example. There is a file пример.flv (russian symbols in filename), created in Windows, in the root directory on some FTP-server ftp.example.com. The correct URL of this file for transfer to service is ftp://ftp.example.com/%EF%F0%E8%EC%E5%F0.flv. Let's say there is a HTML form, where user can enter the filename manually and some user has entered our file. User is not a computer and he can type ftp://ftp.example.com/пример.flv instead of ftp://ftp.example.com/%EF%F0%E8%EC%E5%F0.flv and he will be right. If form page encoding is UTF-8, then file URL received from form will look like ftp://ftp.example.com/%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.flv. If that URL is transferred as source filename at conversion creation, then service will return "File not exist" error, i.e. actually file with name %EF%F0%E8%EC%E5%F0.flv is located on filesystem. In order to create a conversion sucessfully it is neccesary to convert the filename taken from form into actual encoding, or to set the optional parameters during conversion creation. In our example one should set source_filename_encoding in Windows-1251.

The defined transformation "rule" of source filename works out only in case if both parameters source_url_encoding and source_filename_encoding are set to different values. If values are equal, then no transformation is performed, i.e. the parameters are ignored, and service use the source filename as it was transferred. Such behavior is default as both parameters values by default are UTF-8.

The process described for source file above is similar to file output. List of supported charsets is displayed in appendix.

So the basic rule for transferring of source filename or output filename with national characters is: filename should be "percent-encoded" in the actual encoding for filesystem where this file is located. Otherwise, API user either should convert the filename in the actual encoding and then transfer it or use the parameters of startConversion method described above.

Supported charsets

byte2be UCS-4BE UTF-8 ISO-2022-JP-MS ISO-8859-10 UHC
byte2le UCS-4LE UTF-7 Windows-1252 ISO-8859-13 ISO-2022-KR
byte4be UCS-2 UTF7-IMAP ISO-8859-1 ISO-8859-14 Windows-1251
byte4le UCS-2BE ASCII ISO-8859-2 ISO-8859-15 CP866
BASE64 UCS-2LE EUC-JP ISO-8859-3 ISO-8859-16 KOI8-R
UUENCODE UTF-32 SJIS ISO-8859-4 EUC-CN ArmSCII-8
HTML-ENTITIES UTF-32BE eucJP-win ISO-8859-5 CP936
Quoted-Printable UTF-32LE SJIS-win ISO-8859-6 HZ
7bit UTF-16 CP51932 ISO-8859-7 EUC-TW
8bit UTF-16BE JIS ISO-8859-8 BIG-5
UCS-4 UTF-16LE ISO-2022-JP ISO-8859-9 EUC-KR

Error codes list

All error codes are equal both for JSON-RPC protocol calls and XML-RPC protocol calls.

Code Description
-32768 .. -32000 Protocol errors.
0 No error, output is available for using.
1 .. 32000 Application errors

Protocol Errors

Code Description
-32700 Parse error.
-32600 Invalid request.
-32601 Method not found.
-32602 Invalid parameters.
-32000 Internal error.

Application errors

List of basic application error codes is displayed below. Actually, some error messages are presented in a more detailed way.

Code Description
1 Unauthorized access to API.
2 Invalid parameter.
3 Account is inactive.
4 Limit exceeded.
5 Traffic exceeded.
6 Invalid output format.
7 File does not exist.
8 File already exists.
9 Unauthorized access to file.
10 Invalid login/password.
11 Callback error.
12 Upload file error.
13 Converter error.
14 Download file error.
15 Unknown optional parameter.
16 Unknown file size.
17 File size limit exceeded.
32000 Internal error.
Languages Language: 

English  • Русский

Retrieved from "http://api.aviberry.com/API_1.0"
Views
Personal tools