JetEncode accepts a job payload compatible with Coconut’s “API Reference 2.0” style inputs/outputs.

At a high level:

• You provide a source
• Optionally a destination (depending on your integration)
• A map of outputs, where each key is either:

- a Simple Format Spec string (like mp4:1080p::quality=4), or - a special output group key like httpstream

In JetEncode core, outputs are parsed by reading the outputs object and interpreting each key as a format string (see model.JobRequest.Outputs and ParsedOutputs()).

Request Schema (top-level)

{
  "source": { ... },
  "destination": { ... },
  "outputs": {
    "<output_key>": { ...output_settings... }
  },
  "worker_uid" : "<optional worker id to run the job on>"
}

source (object)

Defines where the input media comes from.

Typical Coconut-compatible shape:

{
  "service": "http",
  "url": "https://example.com/video.mp4"
}

destination (object, optional)

Where to upload results. On AWS, attach a least-privilege IAM instance role to EC2 and omit static AWS access keys from the request:

{
  "destination": {
    "path": "jetencode-test",
    "service": "s3",
    "credentials": {
      "bucket": "media-output",
      "region": "us-east-1"
    }
  }
}

The AWS edition must resolve S3 credentials through the AWS default credential provider chain. Never put AWS access keys in a job payload, AMI, or instance user data. For a non-AWS S3-compatible service, follow that provider's scoped credential and secret-management guidance.

outputs (object, required)

A map where:

• key = output format identifier
• value = output settings for that output

Example with multiple output types:

{
  "outputs": {
    "mp4:480p::quality=3": {
      "key": "480p",
      "path": "/mp4/480p.mp4"
    },
    "jpg:240x": {
      "path": "/jpg/thumbs_%05d.jpg",
      "number": 10
    },
    "httpstream": {
      "hls": { "path": "/hls" },
      "dash": { "path": "/dash" },
      "variants": [
        "mp4:x:64k",
        "mp4:240p::quality=2",
        "mp4:480p::quality=3,maxrate=1500k",
        "mp4:720p::quality=4,maxrate=3000k"
      ]
    }
  }
}

A Simple format describes the format specs you want to use in outputs.

Naming Convention

For video outputs:

$video_container:$video_specs:$audio_specs:$format_options

• Only $video_container is required
• Specs are separated by :
• Options are separated by _ in the conceptual spec, but commonly written as :: then comma-separated key/value options (see examples)

For audio-only outputs:

$audio_container:$audio_specs

For image outputs:

$image_container:$resolution

Supported Containers

Supported video, audio, and image containers:

• Video: mp4, webm, mpegts, mov
• Audio: ogg, aac, mp3, wav
• Image: jpg, png, webp, gif, webp_anim

Video Specifications

Pattern:

$resolution_$bitrate_$codec_$fps

Resolution

• Presets: 144p, 240p, 360p, 480p, 540p, 576p, 720p, 1080p, 1440p, 2160p, 4k
• Or custom: WxH (e.g., 1280x720)

Default: original resolution

Codec

• copy, dnxhd, h264, hevc, novideo, prores, prores-ks, vp8, vp9
• Container/codec compatibility is enforced; see docs/TRANSCODING_PROFILES.md.

Default: container standard

Bitrate

Any value < 200000k (example: 1500k, 4000k)

FPS

• 0fps (preserve source FPS), 15fps, 23.98fps, 25fps, 29.97fps, 30fps, 60fps

Default: original fps

Audio Specifications

Pattern:

$codec_$bitrate_$sample_rate_$channels

Codec

aac, ac3, copy, mp2, mp3, noaudio, pcm, pcm-alaw, pcm-s16le, pcm-u8, vorbis

Default: container standard

Bitrate

Any value < 512k (example: 64k, 128k, 256k)

Sample rate

8000hz, 11025hz, 22050hz, 44100hz, 48000hz

Default: original

Channels

mono, stereo, multi

Default: original

Format Options

Options section:

$options

Common options

MP4-specific options

H264 options

high10 requires yuv420p10le, high422 requires yuv422p, and high444 requires yuv444p10le.

HEVC options

HEVC supports quality, maxrate, 2pass, yuv420p, and certified 10-bit yuv420p10le.

VP8 / VP9 options

Same quality / maxrate semantics as above.

Full Examples

Any output whose key is a video container or video Simple Format spec (e.g., mp4:720p) produces a transcoded video file.

Output settings (video/audio)

Example:

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

Image outputs are keyed by an image Simple Format spec:

• Static thumbnails: jpg:240x, png:640x360, webp:960x
• Animations: gif:320x, webp_anim:480x

Required

Thumbnail generation modes

Use one of:

• number: generate N images equally spaced (max 100)
• offsets: extract at specific seconds (array of ints)
• interval: extract every N seconds

Image output settings

Example:

{
  "outputs": {
    "jpg:480x": {
      "key": "jpg:medium",
      "path": "/jpg/medium/thumbs_%05d.jpg",
      "number": 10
    },
    "webp_anim:320x320": {
      "key": "webp:preview",
      "path": "/webp/preview.webp",
      "scene": { "number": 5, "duration": 1 },
      "square": true
    }
  }
}

HTTP streaming output is specified under a special output key:

{
  "outputs": {
    "httpstream": {
      "hls": { "path": "/hls" },
      "dash": { "path": "/dash" },
      "variants": ["mp4:240p::quality=2", "mp4:720p::quality=4,maxrate=3000k"],
      "playlist_name": "master",
      "segment_duration": 4
    }
  }
}

JetEncode core implements this in two phases:

1. Encode variants (ffmpeg)
2. Package to HLS/DASH (shaka-packager), optionally encrypt
3. NOTE: only AES-128 encryption is supported currently

Fields

Variants constraints (streaming)

For httpstream.variants:

• container must be mp4
• video codec must be h264 (default), hevc, or novideo
• audio codec must be aac or noaudio

Example variants list:

[
  "mp4:x:64k",
  "mp4:240p::quality=2",
  "mp4:480p::quality=3,maxrate=1500k",
  "mp4:720p::quality=4,maxrate=3000k"
]

By passing worker_uid field to the request body, it is possible to use that particular worker to execute the job. This field is optional. Worker will be automatically selected otherwise.