A Caption API for Legal and Deposition Video

Deposition recordings and legal video get reviewed by people who need the words on screen, whether for accessibility, for noisy offices, or for reviewing testimony without headphones. A caption track that lives in the player does not help once the file is copied or shared, so teams burn the text into the video itself.

The caption.sh API fits that workflow: submit the recording from a hosted URL, poll the job, and download the same video with captions rendered into the frames.

The captioning workflow

This example captions one recording with Python and writes the result to disk.

import requests, time

KEY = "YOUR_CAPTION_API_KEY"
H = {"Authorization": f"Bearer {KEY}"}
API = "https://api.caption.sh/v1"

def caption_video(source_url, out_path):
    r = requests.post(f"{API}/videos", headers=H,
                      json={"source_url": source_url, "options": {}},
                      timeout=30)
    if r.status_code == 402:
        raise RuntimeError("out of credits, top up first")
    r.raise_for_status()
    job_id = r.json()["job_id"]

    deadline = time.time() + 60 * 60
    while time.time() < deadline:
        time.sleep(15)
        job = requests.get(f"{API}/jobs/{job_id}", headers=H, timeout=30).json()
        if job["status"] == "done":
            break
        if job["status"] == "error":
            raise RuntimeError(f"render failed: {job}")
    else:
        raise RuntimeError("render did not finish in time")

    mp4 = requests.get(f"{API}/jobs/{job_id}/result", headers=H, timeout=60)
    open(out_path, "wb").write(mp4.content)

Practical notes

• Submissions are rate limited per API key. A 429 response means wait a moment and retry, it does not mean the job failed.
• Rendering is prepaid at $0.10 per minute of video. A 402 response means the balance is empty, so top up before retrying.
• Every render needs a bounded poll loop with three exits: done, error, and your own timeout. Do not poll forever.
• The API documents no webhook surface, so polling is the intended way to learn a job finished.
• Automated captions can mishear names, case terms and citations. For anything filed or presented, have a person review the rendered video before it is relied on.

Depositions run long, so caption the segments you expect to present instead of every hour of footage. Billing is per rendered minute, which keeps a targeted workflow inexpensive.