2026-11-16 · 5 min read
How to caption videos in TypeScript with an API
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.