Documentation

Source


The source is defined by using the set keyword. Supported URL protocols are (S)FTP, HTTP(S).

set source = https://silo.videoapi.cloud/videos/123.avi

Variables


Variables can be defined with this syntax $variablename and can be used anywhere in the job file.

The reserved variables that can be used are:

VariableTypeDescription
$source_mime_typestring
$source_sizeintsize in bytes
$source_formatstring
$source_widthint
$source_heightint
$source_fpsfloat
$source_ifpsint
$source_video_bitrateintbitrate in kbps
$source_rotationintrotation in degrees. 0 if video is not rotated.
$source_is_hdbooltrue if at least 720p
$source_is_audio_onlybooltrue if audio only
$source_durationintduration in second
$source_video_codecstring
$source_audio_codecstring
$source_channelsint2 for stereo, 1 for mono, 0 for no audio
$source_audio_bitrateintbitrate in kbps
$source_sample_rateintsample rate in Hz

The reserved variables can be combined with the if-statement.

For example we transcode the video based on the original video resolution:

-> mp4:720p  = $cdn/video_720p.mp4 , if=$source_width >= 1280 
-> mp4:1080p = $cdn/video_1080p.mp4, if=$source_width >= 1980

Video Encoding


To convert a video encoding job the output must be prefixed by the keyword -> followed by the container format.

NameTypeDefaultRequired
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No

Options

NameTypeDefaultRequired
keep
Will keep the original spec(s). Values can be
video_bitrate fps resolution audio_bitrate sample_rate channels
Example: keep = resolution,video_bitrate will keep the original video resolution and bitrate
string[,] No
deinterlace
Will deinterlace the video if enabled
bool false No
fit

Option to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop
width and height are required.
string pad No

Rotation

NameTypeDefaultRequired
transpose
Rotate the video
0 90CounterCLockwise and Vertical Flip (default)
1 90Clockwise
2 90CounterClockwise
3 90Clockwise and Vertical Flip
We automatically use transpose for videos taken in portrait mode.
int 0 No
vflip
Vertically Flip the video
We automatically use vflip for videos taken upsidedown.
bool false No
hflip
Horizontally Flip the video
We automatically use hflip for videos taken upsidedown.
bool false No

Cut

NameTypeDefaultRequired
duration
Max duration in second of the video. if 10, the encoded video length will be 10 seconds.
int No
offset
Will start the encoding at the given offset in second.
int No

Watermark

NameTypeDefaultRequired
watermark_url
URL of the png image that will be incrusted in the video. Transparent and semi-transparent images are compatible.
URL No
watermark_position
Position of the watermark.
topleft topright bottomleft bottomright
string topleft No

For example:

var cdn = s3://accesskey:secretkey@bucket

-> webm     = $cdn/webm/video.webm
-> mp4:360p = $cdn/mp4/video_360p.mp4
-> mp4:720p = $cdn/mp4/video_720p.mp4

Video Previews


To create a video preview job the output must be prefixed by the keyword -> followed by the container format.

Thumbnails

Thumbnails can be either jpg or png. The output filename must contain the special variable #num# which will be replaced by the sequence number. The sequence number is mandatory if number > 1.

Creating a storyboard image

Using the storyboard option you can create a storyboard like image.

Parameters

NameTypeDefaultRequired
if
If the given condition is false, the current section won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No
number
Number of thumbnail you want to generate. Must be <= 100. Use either number or offsets, not both.
int 1 No
offsets
Offset(s) in second where you want to extract the thumbnail(s).
[int,] No
every
Generate thumbnails every X seconds.

If 0, will calculate the right gap in second according to the source video duration:
every 2 sec if duration <= 2 min
every 5 sec if duration <= 10 min
every 10 sec if duration <= 30 min
every 20 sec if duration <= 60 min
every 30 sec if duration > 60 min
int No
square
The image will be cropped to a square. Use the width value to determine the size.
width and height are required.
bool false No
fit
Option to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop
width and height are required.
string pad No
sprite
We group every thumbnails into a single image called sprite. The sprite is 4 columns wide. Best for network optimization if you have a lot of thumbnails and if you want to show tooltip like thumbnail within your player.
bool no No
vtt
Generate a WebVTT file that includes a list of cues with either individual thumbnail or sprite with the right coordinates
bool no No
storyboard
Generate a storyboard like image
bool no No
storyboard_template
Specify the storyboard template type. Can be a,b,c,d,e
string a No
storyboard_border_color
Specify the border color (hex) for the storyboard generation. For example: #fcfcfc
string black No

Animated GIF

The output format must be: gif:$widthx and width must be < 500px.The GIF maximum duration is 5 seconds. The height is automatically calculated according to the given width and the original aspect ratio.

-> gif:340x = sftp://user:passwd@host/previews/animated_preview.gif


Parameters

NameTypeDefaultRequired
if
If the given condition is false, the current section won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No
offset
Will start the animation from the given offset in second
int video_length / 3 No

HTTP Stream


To create an http stream job the output must be prefixed by the keyword -> followed by the container format httpstream. The output value is the URL without a filename

NameTypeDefaultRequired
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT..
string No
variants
A list of container formats separated by commas
The formats specs:
• container must be mp4
• Video codec must be either h264, novideo
• Audio codec must be either aac or noaudio
format ID[,] mp4:x:64k,
mp4:x,
mp4:240p_400k:x,
mp4:360p_600k:x,
mp4:360p_1000k:x,
mp4:480p_1500k:x,
mp4:720p:x
mp4:1080p:x
No
playlist_name
The filename without extension that will be used for every playlist or manifest names.
string master No
dash
Enable packaging into MPEG-Dash. Value is the relative path where the different files will be uploaded.
string No
dash+hlsfmp4
Enable packaging into MPEG-Dash and HLS fMP4 (Fragmented MP4 Files). Value is the relative path where the different files will be uploaded.
string No
hls
Enable packaging into HLS (.TS Files). Value is the relative path where the different files will be uploaded.
string No

DRM and Encryption

Widevine (Dash only)

NameTypeDefaultRequired
dash_widevine_pssh
Widevine PSSH
string No
dash_encryption_key
Encryption key.
Syntax is: KeyIDHex:KeyHex
string No

Playready (Dash only)

NameTypeDefaultRequired
dash_playready_laurl
The license Acquisition URL
URL No
dash_encryption_key
Encryption key.
Syntax is: KeyIDHex:KeyHex
string No

Fairplay (HLS only)

NameTypeDefaultRequired
hls_encryption_mode
Must be SAMPLE-AES
string No
hls_encryption_key
DRM Encryption Key. With FairPlay, the key and IV are delivered together. The first 32 characters are used in the key file for "key" and the last 32 characters are used for "iv"
string No
hls_encryption_key_uri
DRM server URI
string No

Simple HTTP Key Delivery (HLS only)

NameTypeDefaultRequired
hls_encryption_mode
Must be AES-128
string AES-128 No
hls_encryption_key
Hexadecimal key to enable AES-128 encryption.
string No
hls_encryption_key_uri
Encryption key URI (may be a relative or absolute URI).
string key.bin No

Variants

It is important that you separate the video from the audio track to be compliant with the DASH-if guidelines.

To use a video only format, name it like this mp4:720p:x. For an audio only format: mp4:x:64k.

Webhooks

A webhook is mandatory and must be defined in a job file. When the job is complete you can receive an HTTP notification to the given URL server side script in JSON format. You can also receive the metadata of the source and specific events trigggered by setting the options metadata and events accordingly.

List of events

Event typeDescription
job.completed When the job is completed.
source.transferred When the source file is transferred to VideoAPI.cloud. All the output jobs are then created. You also get the current progress of the job.
source.failed When the source file couldn't be transferred to VideoAPI.cloud. The job is aborted and the webhook `job.completed` is immediately sent.
output.processed When an output job just finished processing. You also get the current progress of the job.
output.failed When an error occurred while processing.

Usage example:

set webhook = https://app.videoapi.cloud/tools/webhooks/1234/user, events=true, metadata=true

Supported CDN


Amazon S3 & S3-compatible services

The URL pattern and the special headers have this format:

s3://access_key:secret_key@bucket/object_key?x-amz-storage-class=REDUCED_REDUNDANCY

The define the S3 service use the host parameter:

s3://access_key:secret_key@bucket/object_key?host=https://nyc3.digitaloceanspaces.com

Permissions are needed to upload files to your bucket. To allow VideoAPI.cloud to do that please setup the correct policies to your bucket. An example follows:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:PutObjectAcl",
        "s3:GetBucketAcl",
        "s3:GetObjectAcl"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

FTP

The URL format is:

ftp://login:password@host:port/path/filename

SFTP

The URL format is:

sftp://login:password@host:port/path/filename

HTTP(S)

The URL format is:

http://yourhost.com/your_upload/script

The default parameter form name used to upload the file is encoded_video. To change it use the query string http_file_name=output_data so output_data will have the file data. To upload the file VideoAPI.cloud uses a multipart form POST request

Windows Azure

The URL format is:

az://account:access_key@container/filename

Format Specification


The format specification follows this syntax:

$container:$video_specs:$audio_specs:$format_options

Most of the times only the container name is needed because VideoAPI.cloud has already chosen the best video and audio specifications for you.

ContainerVideo specsAudio specs
mp4h264 0x0 1000k 0fpsaac 44100hz 128k stereo
mp4:hevchevc 0x0 1000k 0fpsaac 44100hz 128k stereo
webmvp8 0x0 1000k 0fpsvorbis 44100hz 128k stereo
webm:vp9vp9 0x0 1000k 0fpsvorbis 44100hz 128k stereo
avi
Aliases: divx xvid
mpeg4 0x0 1000k 0fpsmp3 44100hz 128k stereo
asf
Alias: wmv
wmv2 0x0 1000k 0fpswmav2 44100hz 128k stereo
mpegtsh264 0x0 1000k 0fpsaac 44100hz 128k stereo
movh264 0x0 1000k 0fpsaac 44100hz 128k stereo
flv
Alias: flash
flv 0x0 1000k 0fpsmp3 44100hz 128k stereo
mkvh264 0x0 1000k 0fpsaac 44100hz 128k stereo
3gph263 0x0 1000k 0fpsaac 44100hz 32k stereo
ogv
Alias: theora
theora 0x0 1000k 0fpsvorbis 44100hz 128k stereo
oggvorbis 44100hz 128k stereo
mp3mp3 44100hz 128k stereo
jpgjpg 0x0
pngpng 0x0
gifgif 0x0


Video specs

Video specs must be separated by the underscore character _ and are all optional.

To disable video, set the video specs to x. For instance: mp4:x mp4:x:256k_48000hz.

• Resolution

Default resolution if not specified: 0x0 (=Original resolution)

There are two ways to specify the resolution: either with the classic widthxheight or with the *p notation like 720p or 1080p. Note that for thumbnails, GIF, only the notation widthxheight is working.

If you use the latter, the video bitrate is automatically set for you:

DefinitionResolutionAspectBitrate (Kbit/s)
240p0x240*500k
360p0x360*800k
480p0x480*1000k
720p1280x72016:92000k
1080p1980x108016:94000k
2160p3840x216016:98000k


If you set the width or height to 0, we will automatically calculate the value for you according to the aspect ratio of the source video. 0x0 means that the original resolution will be kept.

Note that the video bitrate can still be overriden when using *p notation: mp4:720p_1800k.

• Video codec

Here is the list of video codecs we support:

mpeg4 xvid flv h263 mjpeg mpeg1video mpeg2video qtrle svq3 wmv1 wmv2 huffyuv rv20 h264 hevc vp8 vp9 theora dnxhd prores

Example: mp4:hevc_1080p_2000k avi:mpeg4_640x320

Note that we always set the right video codec associated to the right container for you. So unless you want HEVC or VP9, you can leave the video codec setting to us.

• Video bitrate

Default video bitrate if not specified: 1000k

The video bitrate must be given in kbps and always ends with k. Value must be < 200000k

Example: mp4:1080p_6000k webm:1200k

• FPS

Default FPS if not specified: 0fps (=original FPS)

The FPS value must ends with fps, here are the possible FPS you can provide: 0fps 15fps 23.98fps 25fps 29.97fps 30fps

Note that 0fps means keep original FPS.

Example: mp4:240p_15fps mp4:720p_30fps

Audio specs

Audio specs must be separated by the underscore character _ and are all optional.

To disable audio, set the audio specs to x. Example: mp4:720p:x mp4:hevc_1080p:x

• Audio codec

Here is the list of audio codecs we support:

mp3 mp2 aac amr_nb ac3 vorbis flac pcm_u8 pcm_s16le pcm_alaw wmav2

Example: mkv:mpeg4:mp3 mpegts::mp3

Note that we always set the right audio codec associated to the right container for you. However you can customize it if you need to.

• Audio bitrate

Default audio bitrate if not specified: 128k

The audio bitrate must be given in kbps and always ends with k. Value must be <= 512k.

Example: mp4:1080p:512k webm:1200k:256k

• Sample rate

Default sample rate if not specified: 44100hz

The sample rate value must ends with hz, here are the possible sample rate you can provide:

8000hz 11025hz 16000hz 22000hz 22050hz 24000hz 32000hz 44000hz 44100hz 48000hz

Example: mp4:240p:64k_22050hz mp4:720p:48000hz

• Audio Channel

Default channel if not specified: stereo

Possible channel values are mono stereo

Example: mp4:240p:64k_mono

Format options

H264 and HEVC:

• vprofile: baseline main high high10 high422 high444

• level: 10 11 12 13 20 21 22 30 31 32 40 41 42 50 51

Example: mp4:1080p::vprofile=high,level=50

Prores:

• vprofile: 0(Proxy) 1(LT) 2(SQ) 3(HQ)

• quality: Target a visual quality instead of a bitrate. From 1 (worst) to 5 (visually lossless) quality.

3 is pretty good quality with a good ratio quality / size.

Note that when using quality option, the video bitrate is ignored. Only works with H264, HEVC, VP8 and VP9.

Example: mp4:1080p::quality=4

• pix_fmt: Set pixel format. Can be: yuv420p yuv422p

• 2pass: Enable 2pass encoding. For instance: mp4:720p::2pass

Error Codes


API errors

CodeMessage
config_not_validThe config file must specify the `source' video location, a `webhook' URL and at least 1 output
outputs_out_of_rangeYou can't submit more than 30 Outputs
params_out_of_rangeYou can't set more than 15 params in a request
output_must_have_one_parameterAn output must contains at least one parameter
authentication_failedAuthentication failed, check your API key
account_suspendedAccount temporarily suspended, contact us for more info

Common errors

CodeMessage
unknown_errorUnknown error
output_url_not_validOutput URL is not valid. Supported schemes are s3 ftp sftp http https az

Source errors

CodeMessage
source_http_404_errorHTTP status code: 404
source_bad_address_errorBad address
source_http_401_errorHTTP status code: 401
source_http_403_errorHTTP status code: 403
source_http_500_errorHTTP status code: 500
source_url_not_validURL is not valid
source_is_not_a_valid_fileVideo is not a valid video file
source_video_too_long__free_plan_limitationSource video is too long (> 2min). Please upgrade your plan

Video encoding errors

CodeMessage
transcoding_unsupported_audio_codecUnsupported audio codec
transcoding_unsupported_video_codecUnsupported video codec
transcoding_cant_be_encodedThis video cannot be encoded in this format
transcoding_wrong_audio_settingsWrong settings for audio
transcoding_wrong_video_settingsWrong settings for video
transcoding_cant_retrieve_infoCannot retrieve info from this video
transcoding_not_a_video_fileNot a video file
transcoding_video_too_longVideo too long
transcoding_container_not_supportedThe container of this video is not supported yet
transcoding_audio_cant_be_resampledThe audio can't be resampled
transcoding_format_doesnt_existFormat doesn't exist

HTTPStream errors

CodeMessage
httpstream_unknown_errorUnknown error
httpstream_packaging_errorError while packaging
httpstream_upload_errorCouldn't upload the the media files

Thumbnail errors

CodeMessage
thumbnail_not_uploadedThumbnails not uploaded successfully
thumbnail_creation_failedThumbnail generation failed
thumbnail_filename_has_no_num_varFilename parameter needs to have the special var #num#
thumbnail_image_format_must_be_png_or_jpgImage Format must be png or jpg

Animated GIF errors

CodeMessage
gif_not_uploadedGIF animation not uploaded successfully
gif_creation_failedGIF generation failed
gif_width_out_of_rangeWidth must be > 0px and < 500px

Storyboard errors

CodeMessage
storyboard_not_uploadedStoryboard not uploaded successfully
storyboard_creation_failedStoryboard generation failed
storyboard_width_out_of_rangeWidth must be between 100px and 1280px

Format ID errors

CodeMessage
format_width_not_in_rangeWidth value is not between 0 and 1920
format_height_not_in_rangeHeight value is not between 0 and 1080
format_video_bitrate_not_in_rangeVideo bitrate value is not between 30 and 10000
format_audio_bitrate_not_in_rangeAudio bitrate value is not between 8 and 512
format_wrong_containerWrong video container
format_wrong_video_codecWrong video codec
format_wrong_fpsWrong FPS value
format_wrong_audio_codecWrong audio codec
format_wrong_sample_rateWrong sample rate value

Handling webhook data on the server side


Handling webhook data is very simple, here's an example:

{
  "id": 1234,
  "output_urls": {
    "mp4": "http://mybucket.s3.amazonaws.com/abc1234/videos/mp4/demo.mp4",
    "mp4:360p": "http://mybucket.s3.amazonaws.com/abc1234/videos/mobile/demo.mp4",
    "httpstream": {
      "hls": "http://mybucket.s3.amazonaws.com/abc1234/videos/hls/demo.m3u8"
    },
    "jpg:200x": [
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_01.jpg",
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_02.jpg",
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/small/demo_03.jpg"
    ],
    "jpg:640x": [
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_01.jpg",
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_02.jpg",
      "http://mybucket.s3.amazonaws.com/abc1234/thumbnails/large/demo_03.jpg"
    ],
    "storyboard:640x": "http://mybucket.s3.amazonaws.com/abc1234/storyboard/demo.png"
  },
  "errors": {
    "output": {
      "webm": "output_audio_cant_be_resampled",
      "gif:300x": "gif_not_uploaded"
    }
  },
  "event": "job.completed"
}

REST API


The REST API allows any user with an videoapi.cloud account to request information from our servers programmatically and in a standardized manner, using JSON.

All requests are made against https://api.videoapi.cloud and are authenticated by sending the API key or the username and password used on SignUp

API Key

The API Key can be found in your account settings.If compromised, a new API key can be generated.

API endpoints

POST /v1/job

To create a job, you just need to make a single HTTP request to the URL https://api.videoapi.cloud/v1/job

curl https://api.videoapi.cloud/v1/job \
-u "API-KEY": \
-d '
set source = http://s3.amazonaws.com/videoapicloud/file.webm
set webhook = https://app.videoapi.cloud/tools/webhooks/12345/user

-> mp4 = s3://access:secret@videoapicloud/mp4/file.mp4'
GET /v1/jobs/:jobid
curl https://api.videoapi.cloud/v1/jobs/1048576 -u "API-KEY":
GET /v1/metadata/jobs/:jobid
curl -u "API-KEY": https://api.videoapi.cloud/v1/metadata/jobs/1048576
GET /v1/metadata/jobs/:jobid/:source_or_outputname
curl -u "API-KEY": https://api.videoapi.cloud/v1/metadata/jobs/1048576/mp4:720p