API Reference 2.0

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: 2023-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!



September, 2023

  • Add support for webp and webp_anim (animation in webp format). You will notice huge decrease of file size with a very good quality compared to JPG and GIF animations.
  • AWS S3 is now secure by default. You will get an https URL, so no need to use the secure option anymore.
  • Add new watermark position: center.

Breaking changes

  • Customize sprite generation with a number of image max per sprite file and the number of image per column. Depending on the number of images, it will be more optimized (file size and network bandwidth) to have many sprite images instead of one. sprite is no more a boolean, but an object.
  • Set the VTT filename vtt option takes an object as value instead of a boolean. The new object will let you customize the VTT filename.

See all releases