API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

Configuration sample

# -----------------------------------------------------------------------------+
#                                                                              |
#                        Coconut configuration sample                         |
#                                                                              |
# -----------------------------------------------------------------------------+
#
# Coconut uses a simple configuration format to describe a specific
# encoding workflow.
# Once written, you just have to submit it with an HTTP POST
# request. Here is an example with curl:
#
# curl https://api.coconut.co/v1/job \
# -u api-key: \
# -T coconut.conf
#
#
# Variable declarations
# ---------------------
#
# A variable starts with the keyword `var` and can be used
# by calling it `$varname` anywhere in the config file.
#
# We declare a post ID variable that we will use in our webhook URL
# so we will know the relation between the webhook request and
# the post ID in our database. The post ID is totally made-up,
# it is just for the sample.
var post = 1234

# Since we want all media files to be uploaded to our S3 account,
# we declare the access key, secret key and an existing bucket to store
# the media files in variables
var access_key = accesskey # AWS access key
var secret_key = secretkey # AWS secret key
var bucket     = mybucket

# Here is the full S3 URL that is required by Coconut.
# Every media files will be uploaded to this S3 account.
#
# We support many other CDN and protocols like FTP, SFTP, Windows Azure,
# Rackspace cloud files, OpenStack, etc. Here are some usage examples:
#
# FTP server:
# var url = ftp://user:passwd@host/$post
#
# Rackspace cloud files:
# var url = cf://username:api_key@container/$post
#
# Windows Azure:
# var url = az://account:access_key@container/$post
#
# OpenStack:
# var url = os://auth_token@host/v1/account/container/$post
var url = s3://$access_key:$secret_key@$bucket/media/$post


# Settings
# --------
#
# To define a setting, simply use the keyword `set`.
#
# We must set the `source` video location to convert which can be
# an HTTP(s), FTP or SFTP URL. This parameter is mandatory.
set source  = http://mysite.com/uploads/inputfile.mp4

# To be notified when a job is completed, we need to set
# the `webhook` URL as well. The URL must be public.
#
# We use the `post` variable declared above so we know that
# when the job is completed, it is related with
# our post having the ID=1234
set webhook = http://site.com/webhooks?post_id=$post
#
# To receive the metadata of the source and all the output videos directly
# into the webhook:
# set webhook = http://site.com/webhooks?post_id=$post, metadata=true


# Outputs
# -------
#
# To create an output, you must use the special keyword `->`
# (right arrow) followed by the format you want to use.
#
# There are 3 categories of format:
#
# 1) Video Formats constructed like this:
# $container:$video_specs:$audio_specs:$format_opts
# It's entirely dynamic. Only the container is mandatory
# which is nice because we select the best specs for you.
#
# Examples:
# mp4, mp4:720p, mp4:360p_1000k, webm, webm:400x200_600k,
# ios:300x0_400k, mp4:hevc_720p, etc
#
# 2) Video previews constructed like this:
# $type_$widthx$height. Only the type is mandatory.
# The type can be:
# `jpg` or `png` for thumbnails
# `gif` for animated GIF
# `storyboard` for storyboard (png format)
#
# 3) HTTP Live Streaming format
# The only format is `hls`.
#
# 4) MPEG-Dash format
# The only format is `dash`
#
#
# All outputs take as first value the output URL which is
# the _full_ location URL where you want the final file
# to be uploaded to. It must includes the URL and the final
# filename with the file extension.
# We declared our AWS S3 bucket in `$url` so we can use
# it in all outputs without repeating ourselves.
#
# This is a simple MP4 transcoding. The transcoded video will
# be uploaded to our S3 bucket and will have this URL
# once encoded and uploaded:
# http://mybucket.s3.amazonaws.com/media/1234/videoabc1234.mp4
-> mp4 = $url/videoabc1234.mp4

# Here, we are using a conditional execution via the `if` parameter.
# The mp4_720p video will be created only if the original
# video width is >= 1280
#
# `$source_width` is one of the many built-in variables available.
-> mp4:720p = $url/videoabc1234_hd.mp4, if=$source_width >= 1280

# Here is the list of built-in variables that you can use
# anywhere in the file (not only in if conditions):
# $source_mime_type
# $source_size
# $source_format
# $source_width
# $source_height
# $source_fps
# $source_video_bitrate
# $source_is_hd
# $source_is_audio_only
# $source_duration
# $source_video_codec
# $source_audio_codec
# $source_channels
# $source_audio_bitrate
# $source_sample_rate

-> webm = $url/videoabc1234.webm
-> hls  = $url/videoabc1234.m3u8
-> dash  = $url/videoabc1234.mpd

# For the thumbnails, we want to generate 3 for each size
# (300px wide and 600px wide).
# We do it by using the parameter `number`
-> jpg:300x = $url/videoabc1234_small_#num#.jpg, number=3
-> jpg:600x = $url/videoabc1234_large_#num#.jpg, number=6

# If you want squared thumbnails:
# -> jpg:400x400 = $url/videoabc1234_square_#num#.jpg, number=6, square=1

-> gif:200x = $url/videoabc1234.gif