Caption inputs on Sume: script_text, words, cues or segments?
Four caption inputs and only one may be sent. When to use script_text with transcription, word timings, or phrase cues for a silent clip. Plus the errors.
A Sume caption job accepts four ways to supply wording, and you may send only one: script_text, words, cues or segments. Use script_text when the clip has speech and you want your spelling; use words when you already have word timings; use cues or segments for phrase cards, including clips with no speech. Omit all four and Sume transcribes the audio and burns what it hears.
Which one for which job
The rules come from the Video captions guide and Sume's request validation, read 2026-10-03. script_text keeps speech-to-text as the timing source, so the clip needs audible speech. The other three skip transcription.
| Input | Needs speech in the clip | Timing comes from | Typical use |
|---|---|---|---|
| none | Yes | Speech-to-text | Quick captions of a spoken clip |
| script_text | Yes | Speech-to-text, wording aligned to your script | Fix brand names |
| words | No | Your word start and end times | TTS timings, or a restyle with corrections |
| cues | No | Your phrase start and end times | Silent clips, labels |
| segments | No | Same as cues | Same as cues |
What fails and why
Sending two inputs together returns a 400, because words, cues and segments all name the same timed wording and script_text has nothing to align onto if timings are given. A silent clip with no authored input fails as caption_no_speech. A script_text that cannot be matched to the speech fails as script_alignment_mismatch or script_alignment_failed.
Each phrase cue can hold up to 400 characters, and each word up to 200, so keep cards short enough to read.
Sources
Related posts
More in Developers
- video_filter_crop_out_of_bounds: FFmpeg crop pixels to fractions
Sume video-filter crop takes fractions of the frame, not pixels. Convert FFmpeg crop=w:h:x:y with a runnable Python check of the bounds.
- video_inspect 400s: frames at[] vs fps, and transcribe fields
Three video_inspect refusals: frames with both at[] and fps, frames with neither, and language_code without transcribe. Causes, fixes, a Python lint.
- A video provider interface after the Sora shutdown, Sume behind it
OpenAI lists the Sora API shutdown as 2026-09-24 with no replacement. Put video generation behind one interface so the next vendor exit is a config change.
- Video API 400 unsupported_parameter: size, seed and provider.options
Sume's /v1/videos returns 400 unsupported_parameter for size, seed and a non-empty provider.options. Use resolution and aspect_ratio, and strip the rest.
Written by Sume