How to add subtitles to a video from a transcript

To add subtitles to a video from a transcript, each line of text needs a time: it has to appear when it is spoken. With Sume you don't set those times yourself: send the transcript as script_text with the video's URL to POST /v1/video-captions. Sume runs speech-to-text only to find when each word is said, burns your wording at those times, and returns a new captioned video.

Sume facts come from the Video captions docs and the caption schema in the Sume API reference, read on 2026-09-27. To get a transcript first and correct it before burning, see auto-generate subtitles, then edit.

How do I send the transcript?

Put the whole transcript in script_text, up to 8,000 characters, next to the video's public HTTPS URL in video_url. language is an optional speech-to-text hint such as en or ko; omit it for automatic detection. It never picks the style or the font.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transcript-captions-001" \
  -d '{
    "video_url": "https://example.com/interview.mp4",
    "language": "en",
    "script_text": "Thanks for joining us. Today we look at three ways to cut costs."
  }'

How should I prepare the transcript?

The timing comes from the speech and the wording from your text, so the text should be what is said:

• Keep only the spoken words, in order. Speaker labels, timestamps, and notes such as [music] have no speech to line up with.
• Fix names and spelling in the text. Speech-to-text word timings stay the timing source, and the burned wording is aligned to your script.
• Omit style and the wording picks it: slam for Latin text, black-outline for Korean. Korean text sent with slam, punch, or tiktok-green is refused with 400 caption_hangul_text_latin_style.
• script_text cannot be combined with words, cues, or segments.

What happens if the transcript doesn't match the audio?

The job fails; the standalone captions API does not fall back to other wording. Alignment errors are typed: script_alignment_mismatch or script_alignment_failed, with the suggested next action simplify_script_text_or_omit. Shorten or correct the text, or omit script_text to burn the speech-to-text wording instead. A clip with no audible speech fails as caption_no_speech, with next_action: use_overlay_captions.

If your text is a translation, or has no spoken match at all, skip alignment and send timed cues instead, as translate video subtitles by API does.

What are the limits, and what does it cost?

• video_url must be a fetchable public HTTPS video. Localhost, private-network, non-HTTPS, and signed or private URLs are rejected.
• Today the caption worker refuses a source longer than 60 seconds (duration_out_of_range) or one with no audio stream. For a longer video, see add captions to a long video.
• The result is a burned video, not a subtitle file: the caption resource returns the captioned video_url, and raw transcripts are not part of its public contract. For a separate subtitle file, write one from speech-to-text timings instead.
• Each accepted caption job reserves and captures the fixed amount listed on the Video captions page, for videos up to 60 seconds; confirm live pricing in GET /v1/catalog.