API Documentation
BetterEncoding API allows you to interface with our encoding system in five simple steps. The API can be called via HTTP or HTTPs, and it returns standard XML messages.
Upload & Encode
Send an "encode" API request to start uploading and encoding a video file.
Input HTTP(s) request:
GET request:
https://betterencoding.com/api?action=encode&email=user@domain.com&
password=userpass&rc=vbr&preset=aQ&location=http://domain.com/videos/&
filename=video.avi&type=mp4
POST request using curl:
curl -d 'action=encode&email=user@domain.com&
password=userpass&rc=vbr&preset=aQ&location=http://domain.com/videos/&
filename=video.avi&type=mp4' https://betterencoding.com/api
Output XML message:
<api>
<action>
<encode>
<input_file>
video.avi
</input_file>
<output_file>
video.mp4
</output_file>
<pid>
122ed233a328bdea34233772538031d6
</pid>
<date>
09-18-2011
</date>
<status_description>
encoding
{ // Available status descriptions are:
failure - encoding process didn't start (file doesn't exist).
encoding - encoding process starts.
}
</status_description>
<status_code>
1
{ // Available status codes are:
0 - API request failure.
1 - API request success.
}
</status_code>
</encode>
</action>
</api>
Monitor
Monitor the encoding progress of the currently encoded file.
Input HTTP(s) request:
GET request:
https://betterencoding.com/api?action=file_data&email=user@domain.com&
password=userpass&filename=video.avi
### OR ###
https://betterencoding.com/api?action=file_data&email=user@domain.com&
password=userpass&unique_id=122ed233a328bdea34233772538031d6
POST request using curl:
curl -d 'action=file_data&email=user@domain.com&password=userpass&
filename=video.avi' https://betterencoding.com/api
### OR ###
curl -d 'action=file_data&email=user@domain.com&password=userpass&
unique_id=122ed233a328bdea34233772538031d6'
https://betterencoding.com/api
Output XML message:
<api>
<action>
<file_data>
<stack_size>
1 files
</stack_size>
<input_file>
video.avi
</input_file>
<output_file>
video.mp4
</output_file>
<unique_id>
122ed233a328bdea34233772538031d6
</unique_id>
<input_filesize>
2.1 MB
</input_filesize>
<output_filesize>
900 KB
</output_filesize>
<output_file_location>
http://intercdn.betterencoding.com/09-18-2011/video.mp4
</output_file_location>
<output_thumbnail_location>
http://intercdn.betterencoding.com/09-18-2011/video.jpg
</output_thumbnail_location>
{ // Will be returned only if thumbnails_interval has been called.
<multiple_thumbnails>
...video-0.jpg
...video-1.jpg
...video-2.jpg
</multiple_thumbnails>
}
<output_video_bitrate>
40 kbit/s
</output_video_bitrate>
<output_audio_bitrate>
48 kbit/s
</output_audio_bitrate>
<output_display_size>
360p
{ // Available display sizes are:
240p - low definition.
360p - standard definition.
480p - high definition.
720p - high definition, high quality.
1080p - high definition, full quality.
}
</output_display_size>
<output_length>
0h1m25s
</output_length>
<download_progress>
100%
</download_progress>
<encoding_progress>
100%
</encoding_progress>
<date>
09-18-2011
</date>
<status_description>
success
{ // Available status descriptions are:
encoding - encoding process runs.
wait - encoding process waits.
failure - encoding process failed.
success - encoding process succeeded.
}
</status_description>
<status_code>
1
{ // Available status codes are:
0 - API request failure.
1 - API request success.
}
</status_code>
</file_data>
</action>
</api>
Download
Once the "file_data" API request indicates that the encoding process has finished, download the output file and output thumbnail to a desired location (local machine, remote server etc.).
Delete
Delete the encoded file, or skip this step if you want to leave it on the system.
Input HTTP(s) request:
GET request:
https://betterencoding.com/api?action=delete&email=user@domain.com&
password=userpass&filename=video.avi
### OR ###
https://betterencoding.com/api?action=delete&email=user@domain.com&
password=userpass&unique_id=122ed233a328bdea34233772538031d6
POST request using curl:
curl -d 'action=delete&email=user@domain.com&password=userpass&
filename=video.avi' https://betterencoding.com/api
### OR ###
curl -d 'action=delete&email=user@domain.com&password=userpass&
unique_id=122ed233a328bdea34233772538031d6'
https://betterencoding.com/api
Output XML message:
<api>
<action>
<delete>
<stack_size>
1 files
</stack_size>
<input_file>
video.avi
</input_file>
<output_file>
video.mp4
</output_file>
<pid>
122ed233a328bdea34233772538031d6
</pid>
<date>
09-18-2011
</date>
<status_description>
deleting
{ // Available status descriptions are:
failure - delete process didn't start (file doesn't exist).
deleting - delete process starts.
}
</status_description>
<status_code>
1
{ // Available status codes are:
0 - API request failure.
1 - API request success.
}
</status_code>
</delete>
</action>
</api>
List
Verify that the encoded file was deleted or saved on the system.
Input HTTP(s) request:
GET request:
https://betterencoding.com/api?action=list&email=user@domain.com&
password=userpass&status=all
POST request using curl:
curl -d 'action=list&email=user@domain.com&password=userpass&
status=all' https://betterencoding.com/api
Output XML message:
<api>
<action>
<list>
<stack_size>
1 files
</stack_size>
<total_input_filesize>
2.1 MB
</total_input_filesize>
<total_output_filesize>
900 KB
</total_output_filesize>
<input_file>
video.avi
</input_file>
<output_file>
video.mp4
</output_file>
<unique_id>
122ed233a328bdea34233772538031d6
</unique_id>
<input_filesize>
2.1 MB
</input_filesize>
<output_filesize>
900 KB
</output_filesize>
<output_file_location>
http://intercdn.betterencoding.com/09-18-2011/video.mp4
</output_file_location>
<output_thumbnail_location>
http://intercdn.betterencoding.com/09-18-2011/video.jpg
</output_thumbnail_location>
<date>
09-18-2011
</date>
<status_description>
success
{ // Available status descriptions are:
encoding - encoding process runs.
wait - encoding process waits.
failure - encoding process failed.
success - encoding process succeeded.
}
</status_description>
<status_code>
1
{ // Available status codes are:
0 - API request failure.
1 - API request success.
}
</status_code>
</list>
</action>
</api>
Syntax
The API requests can be executed only through the following address:
https://betterencoding.com/api
Option Values
Requested API Action - action: {list | file_data | delete | encode}
Rate Control Mode - rc: {cbr | vbr}
Preset Type - preset: {aQ | sQ | cQ}
aQ = Auto adjusted preset, video quality is set automatically by the encoder.
sQ = Specially designed for slow devices (Legacy iPhone/iPod, Zune etc).
cQ = Customizable preset, allows the user to adjust the following parameters:
vb = Video bitrate in kbit/s (20 - 8000 kbit/s).
ab = Audio bitrate in kbit/s (48 - 72 kbit/s).
kf = Keyframes interval (1 - 250, Recommended: 250).
width = Width size in pixels (100px - 1920px or auto).
height = Height size in pixels (100px - 1080px or auto).
* If width and height are both set to auto, the output resolution will be equal to
the input resolution.
Custom Quality Example:
GET request:
https://betterencoding.com/api?action=encode&email=user@domain.com&
password=userpass&rc=vbr&preset=cQ&location=http://domain.com/videos/&
vb=1200&ab=48&kf=250&width=1280&height=auto&filename=video.avi&type=mp4
POST request using curl:
curl -d 'action=encode&email=user@domain.com&password=userpass&
rc=vbr&preset=cQ&location=http://domain.com/videos/&vb=1200&ab=48&
kf=250&width=1280&height=auto&filename=video.avi&type=mp4'
https://betterencoding.com/api
Thumbnail extraction position (in seconds) - thumbnail_position: {int}
Thumbnails extraction interval (in seconds) - thumbnails_interval: {int}
* thumbnail_position and thumbnails_interval can't be used simultaneously.
Encoding start position (in seconds) - start_position: {int}
Encoded stream duration (in seconds) - stream_duration: {int}
Watermark HTTP(s) location - watermark_location: {domain name}
Watermark filename (only the PNG file format is valid) - watermark_filename: {str}
AWS S3 Upload:
AWS access key ID (used for interfacing with S3) - aws_access_key_id: {str}
AWS secret access key (used for interfacing with S3) - aws_secret_access_key: {str}
The S3 bucket name that the encoded files will be uploaded to - s3_bucket_name: {str}
FTP Upload:
FTP server url (e.g. ftp.yourdomain.com) - ftp_server: {str}
FTP path, where the encoded file/s should be uploaded to - ftp_path: {str}
FTP username (a valid FTP account username) - ftp_username: {str}
FTP password (a valid FTP account password) - ftp_password: {str}
Encoding type - type: {mp4 | webm | ts}
Encoding process status - status: {all | wait | encode | success | failure}
Callback URL - callback_url: {URL}
The callback_url function will return the following information:
{URL}?input=$input&output=$output&unique_id=$unique_id&status=$status
Callback URL Example:
GET request:
https://betterencoding.com/api?action=encode&email=user@domain.com&
password=userpass&rc=vbr&preset=cQ&location=http://domain.com/videos/&
vb=1200&ab=48&kf=250&width=1280&height=auto&filename=video.avi&type=mp4&
callback_url=http://www.yourdomain.com/yourscript.php
POST request using curl:
curl -d 'action=encode&email=user@domain.com&password=userpass&
rc=vbr&preset=cQ&location=http://domain.com/videos/&vb=1200&ab=48&
kf=250&width=1280&height=auto&filename=video.avi&type=mp4&
callback_url=http://www.yourdomain.com/yourscript.php'
https://betterencoding.com/api
* The callback_url function can be added to all of the system's encoding presets.
** The callback_url function returns data via the HTTP Post method only.