VideoAPI.cloud 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:

Variable	Type	Description
`$source_mime_type`	string
`$source_size`	int	size in bytes
`$source_format`	string
`$source_width`	int
`$source_height`	int
`$source_fps`	float
`$source_ifps`	int
`$source_video_bitrate`	int	bitrate in kbps
`$source_rotation`	int	rotation in degrees. 0 if video is not rotated.
`$source_is_hd`	bool	true if at least 720p
`$source_is_audio_only`	bool	true if audio only
`$source_duration`	int	duration in second
`$source_video_codec`	string
`$source_audio_codec`	string
`$source_channels`	int	2 for stereo, 1 for mono, 0 for no audio
`$source_audio_bitrate`	int	bitrate in kbps
`$source_sample_rate`	int	sample 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.

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

Options

Name	Type	Default	Required
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

Name	Type	Default	Required
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

Name	Type	Default	Required
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

Name	Type	Default	Required
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

Name	Type	Default	Required
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

Name	Type	Default	Required
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

Name	Type	Default	Required
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)

Name	Type	Default	Required
dash_widevine_pssh Widevine PSSH	string		No
dash_encryption_key Encryption key. Syntax is: `KeyIDHex:KeyHex`	string		No

Playready (Dash only)

Name	Type	Default	Required
dash_playready_laurl The license Acquisition URL	URL		No
dash_encryption_key Encryption key. Syntax is: `KeyIDHex:KeyHex`	string		No

Fairplay (HLS only)

Name	Type	Required
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)

Name	Type	Default	Required
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 type	Description
`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.

Container	Video specs	Audio specs
`mp4`	`h264` `0x0` `1000k` `0fps`	`aac` `44100hz` `128k` `stereo`
`mp4:hevc`	`hevc` `0x0` `1000k` `0fps`	`aac` `44100hz` `128k` `stereo`
`webm`	`vp8` `0x0` `1000k` `0fps`	`vorbis` `44100hz` `128k` `stereo`
`webm:vp9`	`vp9` `0x0` `1000k` `0fps`	`vorbis` `44100hz` `128k` `stereo`
`avi` Aliases: `divx` `xvid`	`mpeg4` `0x0` `1000k` `0fps`	`mp3` `44100hz` `128k` `stereo`
`asf` Alias: `wmv`	`wmv2` `0x0` `1000k` `0fps`	`wmav2` `44100hz` `128k` `stereo`
`mpegts`	`h264` `0x0` `1000k` `0fps`	`aac` `44100hz` `128k` `stereo`
`mov`	`h264` `0x0` `1000k` `0fps`	`aac` `44100hz` `128k` `stereo`
`flv` Alias: `flash`	`flv` `0x0` `1000k` `0fps`	`mp3` `44100hz` `128k` `stereo`
`mkv`	`h264` `0x0` `1000k` `0fps`	`aac` `44100hz` `128k` `stereo`
`3gp`	`h263` `0x0` `1000k` `0fps`	`aac` `44100hz` `32k` `stereo`
`ogv` Alias: `theora`	`theora` `0x0` `1000k` `0fps`	`vorbis` `44100hz` `128k` `stereo`
`ogg`		`vorbis` `44100hz` `128k` `stereo`
`mp3`		`mp3` `44100hz` `128k` `stereo`
`jpg`	`jpg` `0x0`
`png`	`png` `0x0`
`gif`	`gif` `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:

Definition	Resolution	Aspect	Bitrate (Kbit/s)
`240p`	`0x240`	`*`	`500k`
`360p`	`0x360`	`*`	`800k`
`480p`	`0x480`	`*`	`1000k`
`720p`	`1280x720`	`16:9`	`2000k`
`1080p`	`1980x1080`	`16:9`	`4000k`
`2160p`	`3840x2160`	`16:9`	`8000k`

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

Code	Message
`config_not_valid`	The config file must specify the `source' video location, a `webhook' URL and at least 1 output
`outputs_out_of_range`	You can't submit more than 30 Outputs
`params_out_of_range`	You can't set more than 15 params in a request
`output_must_have_one_parameter`	An output must contains at least one parameter
`authentication_failed`	Authentication failed, check your API key
`account_suspended`	Account temporarily suspended, contact us for more info

Common errors

Code	Message
`unknown_error`	Unknown error
`output_url_not_valid`	Output URL is not valid. Supported schemes are `s3` `ftp` `sftp` `http` `https` `az`

Source errors

Code	Message
`source_http_404_error`	HTTP status code: 404
`source_bad_address_error`	Bad address
`source_http_401_error`	HTTP status code: 401
`source_http_403_error`	HTTP status code: 403
`source_http_500_error`	HTTP status code: 500
`source_url_not_valid`	URL is not valid
`source_is_not_a_valid_file`	Video is not a valid video file
`source_video_too_long__free_plan_limitation`	Source video is too long (> 2min). Please upgrade your plan

Video encoding errors

Code	Message
`transcoding_unsupported_audio_codec`	Unsupported audio codec
`transcoding_unsupported_video_codec`	Unsupported video codec
`transcoding_cant_be_encoded`	This video cannot be encoded in this format
`transcoding_wrong_audio_settings`	Wrong settings for audio
`transcoding_wrong_video_settings`	Wrong settings for video
`transcoding_cant_retrieve_info`	Cannot retrieve info from this video
`transcoding_not_a_video_file`	Not a video file
`transcoding_video_too_long`	Video too long
`transcoding_container_not_supported`	The container of this video is not supported yet
`transcoding_audio_cant_be_resampled`	The audio can't be resampled
`transcoding_format_doesnt_exist`	Format doesn't exist

HTTPStream errors

Code	Message
`httpstream_unknown_error`	Unknown error
`httpstream_packaging_error`	Error while packaging
`httpstream_upload_error`	Couldn't upload the the media files

Thumbnail errors

Code	Message
`thumbnail_not_uploaded`	Thumbnails not uploaded successfully
`thumbnail_creation_failed`	Thumbnail generation failed
`thumbnail_filename_has_no_num_var`	Filename parameter needs to have the special var #num#
`thumbnail_image_format_must_be_png_or_jpg`	Image Format must be png or jpg

Animated GIF errors

Code	Message
`gif_not_uploaded`	GIF animation not uploaded successfully
`gif_creation_failed`	GIF generation failed
`gif_width_out_of_range`	Width must be > 0px and < 500px

Storyboard errors

Code	Message
`storyboard_not_uploaded`	Storyboard not uploaded successfully
`storyboard_creation_failed`	Storyboard generation failed
`storyboard_width_out_of_range`	Width must be between 100px and 1280px

Format ID errors

Code	Message
`format_width_not_in_range`	Width value is not between 0 and 1920
`format_height_not_in_range`	Height value is not between 0 and 1080
`format_video_bitrate_not_in_range`	Video bitrate value is not between 30 and 10000
`format_audio_bitrate_not_in_range`	Audio bitrate value is not between 8 and 512
`format_wrong_container`	Wrong video container
`format_wrong_video_codec`	Wrong video codec
`format_wrong_fps`	Wrong FPS value
`format_wrong_audio_codec`	Wrong audio codec
`format_wrong_sample_rate`	Wrong 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