2026-11-11 · 5 min read
A captions API for mobile apps
If your mobile app produces video, a clips feature, a video journal, a coaching app with form checks, users will ask for captions. Rendering captions on the device means shipping fonts, managing subtitle timing, and burning CPU on the phone. caption.sh moves that work server-side: your backend hands the API a source URL, and the API returns a rendered MP4.
Where the API sits in a mobile architecture
The phone should not hold your API key. The clean shape is: the app uploads video to your storage as it already does, your backend submits the caption job with your key, and the app polls your backend (or receives a push) until the captioned MP4 is ready to display or share.
const API = "https://api.caption.sh/v1";
const headers = {
Authorization: `Bearer ${process.env.CAPTION_API_KEY}`,
"Content-Type": "application/json",
};
async function captionClip(sourceUrl) {
const res = await fetch(`${API}/videos`, {
method: "POST",
headers,
body: JSON.stringify({
source_url: sourceUrl,
options: {
font: "inter",
position: "bottom",
max_words: 3,
highlight: true,
highlight_color: "#22D3EE",
},
}),
});
if (res.status === 402) throw new Error("out of credits");
if (!res.ok) throw new Error(`submit failed: ${res.status}`);
const { job_id } = await res.json();
for (let i = 0; i < 120; i++) {
await new Promise((r) => setTimeout(r, 5000));
const job = await (
await fetch(`${API}/jobs/${job_id}`, { headers })
).json();
if (job.status === "error") throw new Error("render failed");
if (job.status === "done") return job_id;
}
throw new Error("render timed out");
}Statuses run queued, awaiting_upload, running, then done or error. When your backend sees done, it fetches the result endpoint, which answers with a 302 to a signed URL, saves the MP4 to your own storage, and marks the clip ready. Results are stored for 24 hours, then deleted, so your backend should pull the file promptly rather than handing users the signed URL.
Mobile-specific choices
- Vertical video from phones needs the captions inside the safe area: position bottom with a modest max_lines value keeps text above platform interface overlays.
- Short clips dominate mobile. max_words at 3 with a word highlight matches how users expect social captions to look.
- If users can pick a style, expose a small preset list (font, size, one accent color) instead of the full options surface; every documented key is optional, so presets stay valid as you add more.
- The API documents no webhook surface, so completion comes from polling. A backend poller every few seconds per open job is usually simpler than push-driven retries from the app.
Limits and cost
- One job covers up to 10 minutes of video. For longer uploads, split before submitting and total the per-minute cost across segments.
- A 429 means the transcription throughput ceiling is reached; back off and retry rather than submitting duplicates from every client retry loop.
- Pricing is prepaid at $0.10 per minute. A minute of user video costs $0.10 to caption, which makes unit economics easy to model against your plan prices.
- Burned-in text cannot be toggled or resized by viewers. If accessibility is a requirement for your app, keep the original video available with platform captions as well.