2026-11-16 · 5 min read

How to caption videos in TypeScript with an API

A film strip of programming scenes, the middle frame showing the captioned word TS in neon
This image was generated with AI.

TypeScript is where a lot of video tooling actually lives: Next.js upload routes, serverless functions, queue consumers. Captioning has usually meant shelling out to ffmpeg and shipping fonts with the bundle. caption.sh turns it into a handful of typed fetch calls.

Submit and poll

const API = "https://api.caption.sh/v1";
const KEY = "YOUR_API_KEY";

const headers = {
  Authorization: `Bearer ${KEY}`,
  "Content-Type": "application/json",
};

interface Job {
  job_id: string;
  status: "queued" | "awaiting_upload" | "running" | "done" | "error";
}

const res = await fetch(`${API}/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    source_url: "https://your-cdn.example/clip.mp4",
    options: {
      font: "inter",
      position: "bottom",
      max_words: 3,
      highlight: true,
      highlight_color: "#22D3EE",
    },
  }),
});
const { job_id } = (await res.json()) as { job_id: string };

// poll until done or error
let status: Job["status"] = "queued";
for (let i = 0; i < 120; i++) {
  const r = await fetch(`${API}/jobs/${job_id}`, { headers });
  status = ((await r.json()) as Job).status;
  if (status === "done" || status === "error") break;
  await new Promise((s) => setTimeout(s, 5000));
}
if (status !== "done") throw new Error(`job did not finish: ${status}`);

// /result answers 302; fetch does not expose the Location after
// following, so read the redirect manually
const result = await fetch(`${API}/jobs/${job_id}/result`, {
  headers,
  redirect: "manual",
});
console.log("download:", result.headers.get("Location"));

The options object accepts the documented keys only: font, caps, size, max_words, max_lines, position, text_color, highlight, highlight_color, decoration, decoration_color, outline_width, backdrop_radius, backdrop_opacity, max_tilt, censor_captions, and censor_audio. Every key is optional; defaults produce the standard word-by-word style. Type the status field as the union the API actually returns: queued, awaiting_upload, running, done, error.

Details that matter in TypeScript

  • Pass redirect: "manual" on the /result call so the 302 Location header is readable; a followed redirect hides it. Results are stored for 24 hours, then deleted, so download promptly.
  • A bounded for loop with setTimeout suits a script; in a queue consumer, requeue with a delay instead of awaiting inside the handler.
  • A 429 means the transcription throughput ceiling is reached. Back off and retry the same job rather than submitting duplicates per retry.
  • One job accepts up to 10 minutes of video. Split longer footage first and total the per-minute cost across segments.

Cost and tradeoffs

Pricing is prepaid at $0.10 per minute, so cost is predictable before you run a batch. Burned-in captions cannot be toggled, resized, or translated by viewers, so keep platform-side captions available where accessibility matters.

Back to all articles