2026-11-11 · 5 min read

How to add captions to documentary footage with an API

A film strip of documentary scenes, the middle frame showing the captioned word STORY
This image was generated with AI.

Documentary work produces two captioning jobs. The first is social: short captioned cuts of interviews and scenes that promote the film. The second is the long-form deliverable itself, where broadcasters and festivals have strict caption requirements. caption.sh automates the first job cleanly and can draft the second, with honest limits this guide spells out.

The social-cut workflow

Promotional clips are where an API earns its keep. Cut the excerpt, upload it somewhere addressable, and caption it programmatically:

import requests, time

API = "https://api.caption.sh/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

job = requests.post(
    f"{API}/videos",
    headers=HEADERS,
    json={
        "source_url": "https://your-cdn.example/interview-excerpt.mp4",
        "options": {
            "font": "inter",
            "position": "bottom",
            "max_words": 4,
            "max_lines": 2,
            "highlight": True,
            "highlight_color": "#FACC15",
        },
    },
).json()
job_id = job["job_id"]

for _ in range(120):
    job = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS).json()
    if job["status"] in ("done", "error"):
        break
    time.sleep(5)

if job["status"] == "done":
    r = requests.get(f"{API}/jobs/{job_id}/result", headers=HEADERS,
                     allow_redirects=False)
    video_url = r.headers["Location"]

Statuses are queued, awaiting_upload, running, then done or error. The result endpoint returns a 302; read the Location header with redirects disabled and save the MP4, since results are stored for 24 hours, then deleted.

Where a human pass still matters

  • Documentary dialogue includes names, places, and dates that must be exactly right. Transcription gets everyday speech right most of the time, but proper nouns deserve a proofread against your transcripts.
  • Field audio varies: wind, crowds, overlapping voices. Accuracy follows the audio, so a clean interview track captions better than a verite scene with background noise.
  • Emotional pauses and half-finished sentences are part of documentary speech. Review pacing so captions do not imply a cleaner sentence than the subject spoke.
  • For festival or broadcast delivery, burned-in captions are usually not the required format at all; distributors typically want a sidecar caption file, which is a different deliverable from a burned-in MP4.

Limits and cost

  • Each job accepts up to 10 minutes. Social cuts fit easily; long scenes should be split into segments first, with per-minute cost summed across them.
  • A 429 means the transcription throughput ceiling is reached. Wait and retry rather than submitting duplicates.
  • At $0.10 per minute prepaid, captioning ten 90-second promo cuts costs about $1.50 total.
  • Burned-in text cannot be toggled, resized, or translated. For accessibility on the final film, use switchable captions in the delivery player and keep burned-in versions for social promotion.

Back to all articles