2026-11-12 · 5 min read

A captions API for healthcare videos

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

Healthcare teams produce more video every year: patient education clips, staff training, procedure explainers, recorded telehealth sessions. Much of it needs captions, both for accessibility and because viewers often watch without sound. caption.sh handles the rendering step through an API, and this guide is careful about the parts that still need people.

A sensible division of labor

The API transcribes the audio and burns timed captions into the video. What it does not do is guarantee medical accuracy or handle your compliance obligations: terminology review stays with your team, and whether a given workflow fits your privacy requirements is a decision for your compliance staff, not something a captioning tool can settle. Treat the API as the rendering step inside a process you already control.

The workflow

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/patient-education.mp4",
        "options": {
            "font": "inter",
            "position": "bottom",
            "max_words": 5,
            "max_lines": 2,
            "caps": False,
            "backdrop_opacity": 0.4,
        },
    },
).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 run queued, awaiting_upload, running, then done or error. Poll until a terminal status, then fetch the result endpoint: it returns a 302, so read the Location header with redirects disabled. Results are stored for 24 hours, then deleted, so download the MP4 promptly.

Accuracy for medical vocabulary

General speech-to-text handles everyday language well and stumbles on specialized vocabulary: drug names, anatomical terms, procedure names. For patient-facing content, plan a review pass where someone checks the captions against your script or transcript, especially dosages and medication names where a wrong word is a real problem. For internal training drafts, the generated captions are often good enough to review against rather than type from scratch.

Practical notes

  • Accessibility is usually the point in healthcare, so remember the tradeoff: burned-in captions cannot be toggled, resized, or translated. Pair them with platform captions wherever the player supports it.
  • max_words at 5 with caps off reads calmly, which suits instructional content better than the punchy social style.
  • Each job covers up to 10 minutes. Longer training recordings should be split into segments first.
  • At $0.10 per minute prepaid, captioning a 6-minute patient education video costs $0.60.
  • A 429 means the transcription throughput ceiling is reached. Wait and retry rather than submitting duplicates.

Back to all articles