2026-11-14 · 5 min read

How to add captions to music videos with an API

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

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.

Back to all articles