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 API v2 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.

The API endpoint is https://api.coconut.co/v2

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.

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!



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