API Reference v2

Coconut API Documentation

Coconut's API is a REST based API built with simplicity and flexibility in mind. With a single request, you can fit any kind of workflow from transcoding to multiple formats to generating thumbnails of any size. It is then submitted to Coconut for processing. Very simple.

API version (current: 2021-001)

The default API version is the latest one that was available at the time you signed up. Go to your control panel to review API changes and update to the latest API version.


You must authenticate all your API requests with an API key using Basic Auth. The username is your API key and the password should be left blank.

Regions & API Endpoints

Our infrastructure is global, it means we provide different locations around the world so you can be close to your server geographical location.

Note that you must create an account for each region you may need. When going to the signup page, just select the region in the menu and sign up like usual.

Here are the regions we support:

RegionRegion CodeAPI endpoint
North Virginia (USA) us-east-1 https://api.coconut.co/v2
Oregon (USA) us-west-2 https://api-us-west-2.coconut.co/v2
Ireland (Europe) eu-west-1 https://api-eu-west-1.coconut.co/v2

If your region is missing, please contact us.

cURL example

To create a job, you just need to make a single HTTP request to the URL https://api.coconut.co/v2/jobs.

curl https://api.coconut.co/v2/jobs \
-u your-api-key: \
-d '{
  "input": {
    "url": "https://s3.amazonaws.com/bucket/file.mp4"
  "storage": {
    "service": "s3",
    "region": "us-east-1",
    "bucket": "mybucket",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
  "notification": {
    "type": "http",
    "url": "http://site.com/webhook"
  "outputs": {
    "mp4:480p": {
      "path": "/480p/video.mp4"
    "mp4:720p": {
      "path": "/720p/video.mp4"
    "httpstream": {
      "hls": {
        "path": "/hls"

Client libraries

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!



  • Config syntax changed to JSON. If you upgrade, you will no longer be able to create a new job with the old config syntax.
  • The API endpoint is starting by https://api.coconut.co/v2/.
  • Storyboard style images removed.
  • Builtin variables renamed from source_* to input.*.
  • We drop the dollar variable syntax to call a variable. Use {{ varname }} instead.
  • Webhook (Notification) structure completely changed.
  • notification Receive notification via HTTP or AWS SNS
  • storage Setup your storage service.
  • httpstream All encoding options are available for httpstream output: fit transpose vflip hflip duration offset watermark
  • httpstream default variants updated.
  • httpstream won't upscale by default. It means a 1080p video won't be upscaled to 4K.
  • httpstream Add support for HEVC. Works only with hlsfmp4 and dash.
  • images/gif Control how many scenes you want in a single gif and the duration of each scene in second. Create a more dynamic and pleasant animation preview for your users.
  • images/* New blur option available for jpg png and gif outputs.
  • formats Add support for fragmented mp4 via the option format frag. For example: mp4:1080p::frag