2026-11-14 · 5 min read
How to add captions to music videos with an API
Music video captioning covers two very different jobs. The first is spoken-word content around the music: artist interviews, behind-the-scenes footage, song explainers, and announcement clips. The second is lyrics. caption.sh handles the first well and deserves an honest answer on the second.
The spoken-word workflow
Interviews, BTS footage, and commentary caption cleanly because the speech sits above the mix. The standard workflow applies:
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/artist-interview.mp4",
"options": {
"font": "inter",
"position": "bottom",
"max_words": 4,
"max_lines": 2,
"highlight": True,
"highlight_color": "#E879F9",
},
},
).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"]Jobs run queued, awaiting_upload, running, then done or error; poll until a terminal status. The result endpoint answers 302, so read the Location header with redirects disabled. Results are stored for 24 hours, then deleted.
About lyrics
Speech-to-text is built for speech, and sung vocals over a full instrumental are the hardest audio there is: elongated vowels, stacked harmonies, and a loud mix. Expect lyric captions to need a review pass, and for dense tracks they may not be usable at all. If lyrics are the deliverable, a dedicated lyric-video workflow with a timed lyric sheet is the reliable route. caption.sh is the fast answer for everything spoken around the music.
Tradeoffs and cost
- Burned-in captions cannot be toggled, resized, or translated. Keep platform captions enabled where the player supports them.
- Each job covers up to 10 minutes; most music videos fit, but long-form concert footage should be segmented.
- A 429 means the transcription throughput ceiling is reached. Wait and retry rather than submitting duplicates.
- At $0.10 per minute prepaid, captioning a 4-minute video costs $0.40.