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-002)

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!



October, 2021

Enable ultrafast mode to speed up transcoding process. When enabled, the input video is split into chunks that are transcoded in parallel. Expect 5x speed compared to classic mode. Works for videos longer than 1 minute.

See all releases