Developer docs

Encodo API reference.

Queue source videos, render one or many outputs, and receive a webhook when results are ready. Examples on this page use placeholders only—never expose storage keys, secrets, or private media URLs in client-side code.

Start with POST /api/queue View formats

POST /api/queue

Lifecycle

Send a source URL and output formats.
Encodo validates and queues the job.
Workers transcode with FFmpeg and upload outputs.
Your callback URL receives the final results.

Base URL

https://api.encodo.dev

Content type

application/json

Job limit

1–20 output format configurations per request.

Secrets

Pass credentials from your server only. Encodo strips storage credentials before persisting job config.

Queue jobs

POST /api/queue

Create a transcoding job from a source video URL and one or more output format definitions.

TSqueue-job.ts

const response = await fetch('https://api.encodo.dev/api/queue', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: {
      source: 'https://cdn.example.com/uploads/source.mp4',
      callback_url: 'https://your-app.com/webhooks/encodo',
      format: [
        {
          output: 'mp4',
          video_codec: 'libx264',
          quality: 23,
          audio_bitrate: 128,
          audio_codec: 'aac',
          destination: {
            url: 's3://your-bucket/outputs/video.mp4',
            key: process.env.STORAGE_ACCESS_KEY,
            secret: process.env.STORAGE_SECRET_KEY,
            permissions: 'public-read'
          }
        }
      ]
    },
    payload: { assetId: 'asset_123' }
  })
});

const job = await response.json();
// { jobId: 'job_...', status: 'queued', formatCount: 1 }

Field	Type	Description
`query.source`	URL	Publicly reachable source video URL.
`query.callback_url`	URL	Your HTTPS endpoint for completion callbacks.
`query.format`	array	One to twenty output configurations.
`payload`	JSON	Optional opaque metadata echoed back in the callback. Max 8 KB when serialized.

Formats

Supported outputs

GIF

output: 'gif', with width, framerate, start_time, and duration.

MP4

output: 'mp4', with optional codec, CRF quality, audio bitrate, clipping start, and duration.

Repack

output: 'repack' remuxes into another container via file_extension without re-encoding.

Thumbnail

output: 'thumbnail', with image_format (jpg or png), timestamp, and width.

JSONadvanced_hls format

{
  "output": "advanced_hls",
  "separate_audio": 0,
  "segment_duration": 6,
  "playlist_name": "playlist.m3u8",
  "quality": 23,
  "destination": {
    "url": "s3://your-bucket/hls/video/",
    "key": "<storage-access-key>",
    "secret": "<storage-secret-key>",
    "permissions": "public-read"
  },
  "stream": [
    {
      "height": "720",
      "bitrate": "3500",
      "chunklist_name": "720.m3u8",
      "video_codec": "libx264",
      "audio_bitrate": "96",
      "optimize_bitrate": 0,
      "framerate": "25",
      "keyframe": "3",
      "video_codec_parameters": { "vprofile": "main" }
    }
  ]
}

Status

GET /api/status

Poll a job by ID. Status values are queued, processing, done, failed, or cancelled.

TSstatus.ts

const response = await fetch(
  'https://api.encodo.dev/api/status?jobId=job_123'
);

const status = await response.json();
// {
//   jobId: 'job_123',
//   status: 'processing',
//   progress: 50,
//   formats: [
//     { formatIndex: 0, type: 'mp4', status: 'active' }
//   ]
// }

Callbacks

Completion webhook

Encodo sends a POST request to callback_url with result URLs and your optional payload. Verify callbacks on your server before trusting result data.

JSONcallback body

{
  "jobId": "job_123",
  "status": "completed",
  "results": [
    {
      "formatIndex": 0,
      "type": "mp4",
      "status": "completed",
      "url": "https://cdn.example.com/outputs/video.mp4"
    }
  ],
  "payload": { "assetId": "asset_123" }
}