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

Convert the source file to any video / audio formats

Jump to

Every outputs must be set inside the outputs key with each value being a Hash describing the output format and settings.

The format specs are named following a very simple naming convention described in the Formats page.

Examples

Transcoding to webm, 2 mp4 formats and 1 mp3 audio only format:

{
  "outputs": {
    "webm": {
      "path": "/webm/video.webm"
    },
    "mp4:360p": {
      "path": "/mp4/360p/video.mp4"
    },
    "mp4:720p": {
      "path": "/mp4/720p/video.mp4"
    },
    "mp3:64k": {
      "path": "/mp3/audio.mp3"
    }
  }
}

Prevent upscaling

By using if conditional statement, you can define what output you want to skip depending on certain conditions:

{
  "outputs": {
    "mp4:360p::quality=4": {
      "key": "mp4:360p",
      "path": "/mp4/360p/video.mp4",
      "if": "{{ input.width }} >= 480"
    },
    "mp4:480p::quality=4": {
      "key": "mp4:480p",
      "path": "/mp4/480p/video.mp4",
      "if": "{{ input.width }} >= 720"
    },
    "mp4:720p::quality=4": {
      "key": "mp4:720p",
      "path": "/mp4/720p/video.mp4",
      "if": "{{ input.width }} >= 1280"
    },
    "mp4:1080p::quality=4": {
      "key": "mp4:1080p",
      "path": "/mp4/1080p/video.mp4",
      "if": "{{ input.width }} >= 1920"
    },
    "mp4:2160p::quality=4": {
      "key": "mp4:2160p",
      "path": "/mp4/2160p/video.mp4",
      "if": "{{ input.width }} >= 3840"
    }
  }
}

Parameters

NameTypeDefaultRequired
path
The path including the filename where the file will be uploaded. See Destination.
string Yes
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT. See Conditional outputs.
string No
key
Will rename the output key which is sent in the notification payload. Very useful because you can change the output settings but the key name you get at the end will be unchanged. No code to update on your side.
string No
format
Set the format specs. This is totally optional since you can set all the format specs inside the output key by following the syntax described here.
hash No
resolution
Set the resolution.
Example: 1280x720, 1280x or any resolutions 240p 360p 480p 540p 576p 720p 1080p 2140p.
string Original No
video_codec
Set the video codec.
mpeg4 xvid flv h263 mjpeg mpeg1video mpeg2video qtrle svq3 wmv1 wmv2 huffyuv rv20 h264 hevc vp8 vp9 theora dnxhd prores.
string No
video_bitrate
Set the video bitrate.30k and 220000k
Example: 2000k.
string No
fps
Set the FPS.
15fps 23.98fps 25fps 29.97fps 30fps 60fps 120fps 240fps.
string Original No
audio_codec
Set the audio codec.
mp3 mp2 aac amr_nb ac3 vorbis flac pcm_u8 pcm_s16le pcm_alaw wmav2.
string No
audio_bitrate
Set the audio bitrate.
Between 8k and 512k.
Example: 96k.
string No
sample_rate
Set the audio sample rate.
8000hz 11025hz 22050hz 44100hz 48000hz.
string No
channel
Set the audio channel.
mono stereo.
string No
quality
Set the visual quality.
Between 1 (worst) to 5 (visually lossless).
int No
pix_fmt
Set the pixel format.
yuv420p yuv422p yuva444p10le.
string No
vprofile
Set the video profile.
baseline main high high10 high422 high444 444.
string No
level
Set the level for H264 and HEVC codec.
10 11 12 13 20 21 22 30 31 32 40 41 42 50 51.
int No


Encoding Options

NameTypeDefaultRequired
deinterlace
Will deinterlace the video if enabled
bool false No
fit
Available since 2019-06-13

Option to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop
width and height are required.
string pad No


Rotation

NameTypeDefaultRequired
transpose
Rotate the video
0 90CounterCLockwise and Vertical Flip (default)
1 90Clockwise
2 90CounterClockwise
3 90Clockwise and Vertical Flip
We automatically use transpose for videos taken in portrait mode.
int 0 No
vflip
Vertically Flip the video
We automatically use vflip for videos taken upsidedown.
bool false No
hflip
Horizontally Flip the video
We automatically use hflip for videos taken upsidedown.
bool false No

Cut

NameTypeDefaultRequired
duration
Max duration in second of the video. if 10, the encoded video length will be 10 seconds.
int No
offset
Will start the encoding at the given offset in second.
int No

Watermark

NameTypeDefaultRequired
watermark
Overlay an image (PNG) over the video.
hash No
url
URL of the png image that will be incrusted in the video. Transparent and semi-transparent images are compatible.
URL No
position
Position of the watermark.
topleft topright bottomleft bottomright
string topleft No


Example:

{
  "outputs": {
    "mp4:480p::quality=3": {
      "key": "mp4:480p:wm",
      "path": "/mp4/480p/video_wm.mp4",
      "watermark": {
        "url": "https://yourserver/watermark.png",
        "position": "bottomright"
      }
    }
  }
}