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

Webhook

Keyword: webhook is a setting and must be prefixed by the keyword set.

Required – When the job is complete, receive an HTTP notification to the given webhook URL in JSON format. The request contains all the output URLs and errors if any by default.

For instance:

set webhook = https://mysite.com/coconut/webhook

Structure of a basic webhook:

{
  "id": 49342345,
  "event": "job.completed",
  "output_urls": {
    "mp4": "http://videobucket.s3.amazonaws.com/1234/test.mp4",
    "mp4:720p": "http://videobucket.s3.amazonaws.com/1234/test_hd.mp4",
    "hls": "http://videobucket.s3.amazonaws.com/1234/hls/test.m3u8"
    "jpg": [
      "http://videobucket.s3.amazonaws.com/1234/thumbs/test_01.jpg",
      "http://videobucket.s3.amazonaws.com/1234/thumbs/test_02.jpg",
      "http://videobucket.s3.amazonaws.com/1234/thumbs/test_03.jpg"
    ],
    "gif": "http://videobucket.s3.amazonaws.com/1234/test.gif"
  },
  "errors": {
    "output": {
      "webm": "unknown_error"
    }
  }
}


Tips: Add custom query string parameters to the URL to match with objects of your application.

Let's say you have videos attached to a Post in your application. When creating the coconut job, simply add the post_id to the webhook URL so you will know the webhook is related to the given post id when your application will receive it.

set webhook = https://mysite.com/coconut/webhook?post_id=1234


Metadata

Available since version 2015-04-07

You can receive the metadata of the source and output videos as well by using the parameter metadata.

set webhook = https://mysite.com/coconut/webhook, metadata=true

Example of a webhook with metadata enabled:

{
  "id": 49342345,
  "event": "job.completed",
  "output_urls": {
    "mp4_360p": "http://videobucket.s3.amazonaws.com/1234/test_360p.mp4",
    "mp4_240p": "http://videobucket.s3.amazonaws.com/1234/test_240p.mp4",
  },
  "errors": {},
  "metadata": {
    "mp4:360p": {
      "streams": {
        "video": {
          "codec": "h264",
          "width": 480,
          "height": 360,
          "aspect": 1.33,
          "pix_fmt": "yuv420p",
          "fps": 15.0,
          "bitrate": 795
        },
        "audio": {
          "codec": "aac",
          "sample_rate": 44100,
          "channels": 2,
          "bitrate": 128
        }
      },
      "format": {
        "name": "mov",
        "duration": 5,
        "size": 517120,
        "mime_type": "video/mp4"
      }
    },
    "source": {
      "streams": {
        "video": {
          "codec": "mpeg4",
          "width": 320,
          "height": 240,
          "aspect": 1.33,
          "pix_fmt": "yuv420p",
          "fps": 15.0,
          "bitrate": 501
        },
        "audio": {
          "codec": "aac",
          "sample_rate": 24000,
          "channels": 2,
          "bitrate": 53
        }
      },
      "format": {
        "name": "mov",
        "duration": 5,
        "size": 325632,
        "mime_type": "video/mp4"
      }
    },
    "mp4:240p": {
      "streams": {
        "video": {
          "codec": "h264",
          "width": 320,
          "height": 240,
          "aspect": 1.33,
          "pix_fmt": "yuv420p",
          "fps": 15.0,
          "bitrate": 460
        },
        "audio": {
          "codec": "aac",
          "sample_rate": 44100,
          "channels": 2,
          "bitrate": 53
        }
      },
      "format": {
        "name": "mov",
        "duration": 5,
        "size": 299008,
        "mime_type": "video/mp4"
      }
    }
  }
}

Event changes & overall progress

Available since version 2015-05-07

You can receive a webhook request where specific events occur via the boolean parameter events.

Here is the list of events:

Event typeDescription
job.completed When the job is completed.
source.transferred When the source file is transferred to Coconut. All the output jobs are then created. You also get the current progress of the job.
source.failed When the source file couldn't be transferred to Coconut. The job is aborted and the webhook `job.completed` is immediately sent.
output.processed When an output job just finished processing. You also get the current progress of the job.
output.failed When an error occurred while processing.


Usage example:

set webhook = https://mysite.com/coconut/webhook, events=true

Here are some examples:

Source file is transferred to Coconut:

{
  "id": 5194,
  "event": "source.transferred",
  "progress": "16%"
}

An output just processed:

{
  "id": 5194,
  "event": "output.processed",
  "progress": "75%",
  "format": "mp4:240p",
  "url": "http://files.coconut.co.s3.amazonaws.com/newapi/test_240p.mp4"
}

Source file error:

{
  "id": 5192,
  "event": "source.failed",
  "progress": "100%",
  "error": "source_http_404_error"
}

Output failed:

{
  "id": 5192,
  "event": "output.failed",
  "progress": "75%",
  "format": "webm",
  "error": "transcoding_audio_cant_be_resampled"
}

You can also combine events with metadata so you can receive the metadata of the source file and the output videos as well.

{
  "id": 5195,
  "event": "source.transferred",
  "progress": "25%",
  "metadata": {
    "streams": {
      "video": {
        "codec": "mpeg4",
        "width": 320,
        "height": 240,
        "aspect": 1.33,
        "pix_fmt": "yuv420p",
        "fps": 15.0,
        "bitrate": 501
      },
      "audio": {
        "codec": "aac",
        "sample_rate": 24000,
        "channels": 2,
        "bitrate": 53
      }
    },
    "format": {
      "name": "mov",
      "duration": 5,
      "size": 325632,
      "mime_type": "video/mp4"
    }
  }
}

Read our tutorial on how to receive webhooks server-side.