Ankoder | Video Transcoding Tasks

Methods:

[POST] http://api.ankoder.com/job
[GET] http://api.ankoder.com/job/{id}

[POST] http://api.ankoder.com/job

Parameters

Required	Name	Description
required	original_file_id	id of source video to convert
	profile_id	id of Profile to be converted with
	upload_url	Destination of the converted file Support S3, FTP, SFTP : s3://bucket_name ftp://username:password@ftpdomain.com/folder sftp://username:password@ftpdomain.com/folder
	thumbnail_upload_url	Destination of the thumbnail Support S3, FTP, SFTP : s3://bucket_name ftp://username:password@ftpdomain.com/folder sftp://username:password@ftpdomain.com/folder
	postback_url	Url where the result should be posted to e.g. http://www.ankoder.net/ankoder_notification
*	video_format	output format. Specify format of encoded file. Allowed values: 3g2 3gp asf avi dvd flv mjpeg mov mp3 mp4 mpeg mpeg2video mpegts ogg psp rm svcd vcd vob matroska wmv
*	video_codec	Allowed values: flv h263 h264 huffyuv mjpeg mp4 wmv1 wmv2 xvid mpeg4 theora msmpeg4v2
*	audio_codec	Allow values: aac ac3 amr flac mp3 vorbis wmav2 mpeg4aac mp2
	width	Video frame width Allowed values: non-zero integer
	height	Video frame height Allowed values: non-zero integer
	video_bitrate	video bitrate Allowed values: integer less than 10000
	video_fps	video frame rate Allowed values: non-zero integer
	audio_bitrate	Audio bitrate Allowed values: non-zero integer
	audio_sample_rate	Audio sampling frequency Allowed values: any non-zero integer.
	audio_channel	Number of audio channel Allowed values: 1, 2
	keep_aspect	Fit video within width and height instead of stretching Allowed values: 0, 1
	add_padding	Add padding to fit the specified size Allowed values: 0, 1
	suffix	Suffix of output file
	trim_begin	Start encoding from (sec) Allowed values: non-negative integer.
	duration	Duration (sec) Allowed values: positive integer.
	bitrate_tolerance	Default value: the same as video_bitrate
	thumbnail_width	Thumbnail width Allowed values: non-negative integer. Default value: the width of the video
	thumbnail_height	Thumbnail height Allowed values: non-negative integer. Default value: the height of the video
	thumb_moments	Timestamp (in seconds) to capture thumbnail Allowed values: non-negative number greater than 0.01
	thumb_amount	Number of additional thumbnails to generate Allowed values: non-negative integer Default value: 0
	thumb_start	Period (in seconds) start point to generate additional thumbnails Allowed values: non-negative number greater than 0.01 Default value: the start of the video
	thumb_end	Period (in seconds) end point to generate additional thumbnails Allowed values: non-negative number greater than 0.01 Default value: the end of the video
	thumb_way	The way to generate additional thumbnails in the specified period Allowed values: even, rand Default value: none
	watermark_url	The URL of the logo image. The image format can be GIF, JPG or PNG.
	watermark_transparent	Whether enable transparent watermark Allowed values: 0, 1
	watermark_size	The size of the watermark relative to the video Allowed values: no-negative integer less than 100
	watermark_top	top offset of watermark image Allowed values: non-negative integer
	watermark_left	left offset of watermark image Allowed values: non-negative integer
	segment_duration	Segment videos according to Apple’s HTTP Live Streaming Specifications, Segment duration in seconds Allowed values: integer equal or bigger than 5

NOTE: If profile_id is not specified, the items marked with * are mandatory. If profile_id is specified, additional parameters will override values in the specified profile.

HTTP/1.1 200 OK indicate that the job is successfully created.

Success Response Example:

<job>
  <id>55</id>
  <status>submitting</status>
  <original_file>
    <id>175</id>
    <filename>bb5a492984c4c06e8d32f08c117a1b5ffd3b6a47.flv</filename>
    <readable>true</readable>
    <size>29714</size>
    <audio codec="mp3"/>
    <video codec="flv" fps="25"/>
    <spec height="240" width="320" content_type="video/x-flv"/>
    <duration>100</duration>
    <progress>0</progress>
    <created_at>2009-08-17 11:15:59 UTC</created_at>
  </original_file>
  <profile>
    <id>2</id>
    <name>psp</name>
    <created_at>2007-12-27 06:33:39 UTC</created_at>
    <width>480</width>
    <height>272</height>
    <video_format>mp4</video_format>
    <video_fps>29.97</video_fps>
    <video_bitrate>768.0</video_bitrate>
    <video_codec>h264</video_codec>
    <audio_channel>2</audio_channel>
    <audio_codec>aac</audio_codec>
    <audio_bitrate>128.0</audio_bitrate>
    <audio_rate>48000</audio_rate>
    <thumbnail_width></thumbnail_width>
    <thumbnail_height></thumbnail_height>
    <trim_begin></trim_begin>
    <max_duration></max_duration>
    <add_padding>false</add_padding>
    <keep_aspect>false</keep_aspect>
  </profile>
  <convert_progress></convert_progress>
  <created_at>2009-08-18 09:45:47 UTC</created_at>
</job>

HTTP/1.1 422 Unprocessable Entity indicate that the job is failed to create

Failed Response Example:

Status: 422 Unprocessable Entity
<errors>
  <error>Original file can't be blank</error>
</errors>

Testing with Curl

$curl -H "Accept: text/xml"  -X POST -d "original_file_id=5134&profile_id=1" http://username:password@api.ankoder.com/job -i
HTTP/1.1 200 OK

Notification Messages

Convert Notification

When the conversion is completed, our system will POST a notification message in JSON format to your “notification url” – which can be set in your user settings.

result	success or fail
name	filename of output video
error	empty or an error message
type	Convert
is_trimmed	true or false
convert_video_id	ID of output video; e.g. 1456
thumbanil_result	success or fail or partial_success

Success Example

message={
  "name":"179_bb5a492984c4c06e8d32f08c117a1b5ffd3b6a47_55.mp4",
  "result":"success",
  "convert_video_id":"179",
  "is_trimmed":false,
  "original_video_id":"30",
  "type":"Convert",
  "thumbnail_result":"success",
  "Job":"55",
  "error":""}
&signature=JmpnJoMQrdhdXcunbI+j2VVxtZM=

Failed Example

message={
  "result":"fail",
  "is_trimmed":false,
  "original_video_id":"30",
  "type":"Convert",
  "Job":"55",
  "error":"Original video is corrupted"}
&signature=thLXP8YPRgJesf9W0jmiI4JWc1o=

Upload Notification

If you set “external storage” in user settings, our system will upload the output file to your external storage and POST an additional notification message to your “notification url” after it is done.

type	Upload
result	success or fail
error	empty or an error message
job	job details. children: profile, input_file, output_file, id, status
profile	profile the job used, children: id, name
input_file	details of the input video file, children: duration, size, name, id, height, width
output_file	details of the output video file, children: duration, size, name, id, height, width, url, filename, thumbnails
thumbnails	an array of filenames of thumbnails uploaded to your thumbnail destination
filename	filename of output video
id	id of the item
name	name of the item, in the input_file and output_file situation, it’s the orginal file of the video
duration	duration of the video
size	file size of the video file
height	height of the video
width	width of the video
url	the resource identifier of the video
status	status of the job

Success Example

message={
  "result":"success",
  "error":"",
  "type":"Upload",
  "job":{
	"id":"75",
	"status":"completed",
  	"profile":{
		"id":"1057165111",
		"name":"high"
	}
	"input_file":{
		"duration":"11540",
		"name": "lake.avi",
		"size":"876986",
		"id":"137",
		"height":"480",
		"width":"720"
	}
	"output_file":{
		"duration":"11540",
		"name":"lake.mp4",
		"size":"2964981",
		"url":"ftp:\/\/user:incorrect_password@ftp.your.server\/138_03727d8f4f7fa0c4229db60f254b86d0e0f72960_75.mp4",
		"id":"138",
		"height":"720",
		"width":"1280",
		"filename":"138_03727d8f4f7fa0c4229db60f254b86d0e0f72960_75.mp4",
		"thumbnails":[\"138-5.77-1280x720.png\"]
	}
}
&signature=EeyStcSQJ9MnCgDc7Jj/CTGQhfg=

Failed Example

message={
  "result":"fail",
  "error":"Authentication failed",
  "type":"Upload",
  "job":{
	"id":"75",
	"status":"completed",
  	"profile":{
		"id":"1057165111",
		"name":"high"
	}
	"input_file":{
		"duration":"11540",
		"name": "lake.avi",
		"size":"876986",
		"id":"137",
		"height":"480",
		"width":"720"
	}
	"output_file":{
		"duration":"11540",
		"name":"lake.mp4",
		"size":"2964981",
		"url":"ftp:\/\/user:incorrect_password@ftp.your.server\/138_03727d8f4f7fa0c4229db60f254b86d0e0f72960_75.mp4",
		"id":"138",
		"height":"720",
		"width":"1280",
		"filename":"138_03727d8f4f7fa0c4229db60f254b86d0e0f72960_75.mp4",
		"thumbnails":[\"138-5.77-1280x720.png\"]
	}

}
&signature=jrggBD1PwPvgd+MsashIK2BhdOg=

[GET] http://api.ankoder.com/job/{id}

HTTP/1.1 200 OK indicate that the job is can be found.

Success Response Example:

<job>
  <id>55</id>
  <status>completed</status>
  <original_file>
    <id>175</id>
    <filename>bb5a492984c4c06e8d32f08c117a1b5ffd3b6a47.flv</filename>
    <readable>true</readable>
    <size>29714</size>
    <audio codec="mp3"/>
    <video codec="flv" fps=""/>
    <spec height="240" width="320" content_type=""/>
    <duration>100</duration>
    <progress>0</progress>
    <created_at>2009-08-17 11:15:59 UTC</created_at>
  </original_file>
  <convert_file>
    <id>175</id>
    <filename>bb5a492984c4c06e8d32f08c117a1b5ffd3b6a47.flv</filename>
    <readable>true</readable>
    <size>29714</size>
    <audio codec="mp3"/>
    <video codec="flv" fps=""/>
    <spec height="240" width="320" content_type=""/>
    <duration>100</duration>
    <progress>0</progress>
    <created_at>2009-08-17 11:15:59 UTC</created_at>
  </convert_file>
  <profile>
    <id>2</id>
    <name>psp</name>
    <created_at>2007-12-27 06:33:39 UTC</created_at>
    <width>480</width>
    <height>272</height>
    <video_format>mp4</video_format>
    <video_fps>29.97</video_fps>
    <video_bitrate>768.0</video_bitrate>
    <video_codec>h264</video_codec>
    <audio_channel>2</audio_channel>
    <audio_codec>aac</audio_codec>
    <audio_bitrate>128.0</audio_bitrate>
    <audio_rate>48000</audio_rate>
    <thumbnail_width></thumbnail_width>
    <thumbnail_height></thumbnail_height>
    <trim_begin></trim_begin>
    <max_duration></max_duration>
    <add_padding>false</add_padding>
    <keep_aspect>false</keep_aspect>
  </profile>
</job>

HTTP/1.1 404 Not Found indicate that the job doesn’t exist

Failed Response Example:

HTTP/1.1 404 Not Found

Testing with Curl

curl -H "Accept: text/xml" -X GET  http://username:password@api.ankoder.com/job/29 -i

Video encoding on demand

Transcoding Job

Methods:

[POST] http://api.ankoder.com/job

Parameters

Success Response Example:

Failed Response Example:

Testing with Curl

Notification Messages

Convert Notification

Success Example

Failed Example

Upload Notification

Success Example

Failed Example

[GET] http://api.ankoder.com/job/{id}

Success Response Example:

Failed Response Example:

Testing with Curl