@encodeapi/sdk

Official Node.js SDK for EncodeAPI — cloud video transcoding (FFmpeg, HLS, BYOS storage, webhooks).

Copyright 2026 EncodeAPI Australia

Install

npm install @encodeapi/sdk

Requires Node.js 18+ (uses native fetch).

Quick start

import { EncodeAPIClient } from "@encodeapi/sdk";

const client = new EncodeAPIClient({
  apiKey: process.env.ENCODEAPI_KEY!, // sk_test_... or sk_live_...
});

// Sandbox: URL in → temp output (no bucket required)
const job = await client.createJob({
  input: { url: "https://cdn.example.com/sample.mp4" },
  pipeline: { profile: "mp4_1080p" },
});

const result = await client.getJob(job.id);
console.log(result.status, result.download_url);

Examples

Production job (your S3/R2 bucket)

Use a live API key (sk_live_). Mount storage in the EncodeAPI dashboard, or pass a presigned PUT URL.

const job = await client.createJob({
  input: { url: "https://mybucket.s3.amazonaws.com/uploads/lecture.mp4" },
  output: { mode: "byos", upload_url: presignedPutUrl },
  pipeline: { profile: "mp4_1080p" },
  webhook: {
    url: "https://yourapp.com/webhooks/encode",
    secret: "whsec_your_secret",
  },
});

Adaptive HLS (YouTube-style streaming)

const job = await client.createJob({
  input: { url: sourceUrl },
  pipeline: {
    profile: "vod_hls",
    renditions: ["360p", "720p", "1080p"],
  },
  webhook: { url: "https://yourapp.com/webhooks/encode" },
});

// When completed, download_url points to master.m3u8
const done = await client.getJob(job.id);
console.log(done.download_url);

Upload a file from your app (no bucket yet)

Three steps bundled into one helper: POST /uploads → PUT file → POST /jobs.

import { readFileSync } from "node:fs";

const buffer = readFileSync("./video.mp4");

const job = await client.uploadFileAndCreateJob({
  file: {
    name: "video.mp4",
    type: "video/mp4",
    size: buffer.byteLength,
    data: buffer,
  },
  pipeline: { profile: "vod_hls", renditions: ["360p", "720p"] },
  webhook: { url: "https://yourapp.com/webhooks/encode" },
});

Cost estimate before encoding

const estimate = await client.estimate({
  input: { url: "https://example.com/long-video.mp4" },
  pipeline: { profile: "vod_hls", renditions: ["360p", "720p", "1080p"] },
});

console.log(`~$${estimate.estimated_charge_aud} AUD`);

Batch jobs

const batch = await client.createJobsBatch([
  { input: { url: "https://a.mp4" }, pipeline: { profile: "mp4_1080p" } },
  { input: { url: "https://b.mp4" }, pipeline: { profile: "mp4_720p" } },
]);

Download all outputs as ZIP (HLS ladders, etc.)

Maximum 500 MB total.

if (result.download_zip_url) {
  const zip = await client.downloadJobZip(job.id);
  // zip is ArrayBuffer — write to disk or upload elsewhere
}

List available encoder engines

const { billing_mode, engines } = await client.listEngines();
// sandbox → ffmpeg, ffprobe
// prepaid → ffmpeg, handbrake, rav1e, svt-av1, ...

Pipeline templates

const { templates } = await client.listTemplates();

const job = await client.createJob({
  input: { url: sourceUrl },
  template: { id: "tiktok_9x16" },
});

Custom FFmpeg / HandBrake args (prepaid)

await client.createJob({
  input: { url: sourceUrl },
  output: { mode: "byos", upload_url: presignedPut },
  pipeline: {
    engine: "handbrake",
    args: ["-i", "{input}", "-o", "{output}", "-e", "x264", "-q", "22"],
  },
});

Ultrafast parallel encode (prepaid)

await client.createJob({
  input: { url: sourceUrl },
  pipeline: { profile: "mp4_1080p", ultrafast: true },
});

Error handling

import { EncodeAPIClient, EncodeAPIError } from "@encodeapi/sdk";

try {
  await client.createJob({ ... });
} catch (err) {
  if (err instanceof EncodeAPIError) {
    console.error(err.code);    // e.g. insufficient_credits
    console.error(err.status);  // 402, 403, 422
    console.error(err.message);
  }
}

API reference

| Method | HTTP | |--------|------| | createInputUpload() | POST /uploads | | createJob() | POST /jobs | | createJobsBatch() | POST /jobs/batch | | getJob() | GET /jobs/:id | | estimate() | POST /jobs/estimate | | listEngines() | GET /engines | | listTemplates() | GET /api/public/templates | | downloadJobZip() | GET /jobs/:id/download.zip | | uploadFileAndCreateJob() | uploads + jobs (convenience) |

Full REST docs: encodeapi.com/docs/api

CLI

For terminal usage, install @encodeapi/cli:

npm install -g @encodeapi/cli
encodeapi jobs-create --input-url https://example.com/v.mp4 --profile vod_hls

License

MIT — Copyright 2026 EncodeAPI Australia