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

Coconut's API is a config-based API built with simplicity and flexibility in mind.

The config file is used to describe your entire encoding workflow from transcoding to multiple formats to generating thumbnails of any size. It is then submitted to Coconut for processing. Very simple.

Getting started

We provide client libraries for the most popular languages so that you don't have to reinvent the wheel and you can start right away!


Current API version: 2019-06-13


  • New Add new format options quality (1 to 5). Target the quality you need instead of a bitrate. vprofile, level and pix_fmt can be set directly in the format like this: mp4:1080p::vprofile=high,level=50
  • Break storyboard output removed in favor of a simple option storyboard=yes to any jpg or png outputs. For instance:
    -> jpg:1280x = $cdn/sb.jpg, storyboard=yes
  • New Add new storyboard options storyboard_border_color which lets you customize the color of the border and storyboard_template to choose between 5 different layouts.
  • New First version of the Metadata API. Get very detailed specs about all the media files (input and outputs). Works also with webhook option metadata
  • New Add support of getting job info with a GET request /v1/jobs/:jobid. We return progress, output_url and errors fields.
  • New Add new option fit to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop.
  • New Add support of uploading to your AWS S3 bucket with a presigned URL (HTTPS), see the documentation on AWS.
  • New Add support of setting api version directly in the config file with set api_version = 2019-06-13


  • New Add support for every option to generate thumbnails every X seconds.
  • New Add support for sprite option to generate thumbnails into a single sprite image.
  • New Add support for vtt option to create a WebVTT file containing a list of cues and corresponding thumbnails.
  • See previews output


  • New Add support for Widevine, Playready and Fairplay DRM to httpstream.
  • New Add Multiline support to config file to increase readability and maintainability.
  • New Add support for DigitalOcean Spaces (S3 compatible).


  • New httpstream output available. Packaging into HLS, HLSfMP4 and MPEG-Dash.
  • Break hls and dash outputs have been removed in favor of the new httpstream output.
  • New variable $source_ifps: source FPS as integer.


  • New dash output available. Simply add -> dash in the config file to get MPEG-Dash instantly!
  • New fit option for jpg and png output. If fit=crop, the image will be cropped instead padded.
  • New CDN Backblaze B2 supported – Added on January, 19th 2017


  • New events option (boolean) for webhook setting. You will be able to receive a webhook notification each time a source file is transferred, an output is processed and more.
  • New Any custom headers are now supported in the Amazon S3 output URL.
  • New offsets option ([int,]) for jpg and png output. You can now specify the position in second for each thumbnail.


  • New metadata option (boolean) for webhook setting. It is now possible to receive all the metadata of source and output videos in the webhook request.
  • Break Variable source_length renamed to source_duration


Initial release of the API v2. Read our blog post.