Video captions

Standalone video captions take a public HTTPS video URL and return a job-backed captioned video. Prefer this when you already have a finished clip. For Avatar Video, you can also enable inline captions on talking-video or store caption intent on previews.

Create a caption job

Required: video_url. Optional: style, font, language, script_text, words, cues / segments (authored overlay; skips speech-to-text), plus the usual mode / webhook_url / wait_timeout_seconds communication fields.

Speech-to-captions (script_text, or STT when omitted) needs audible speech. A silent clip fails as caption_no_speech (next_action: use_overlay_captions) — not a generic policy reject. Pass cues (or segments) with text + start + end to burn authored overlay copy without ASR.

Create a video caption job

POST /v1/video-captions

Required

Video URL

Style, font and language

Field	Values / default
`style`	Omit it and the wording decides: `slam` for Latin, `black-outline` for Korean. Or name `slam`, `punch`, `tiktok-green`, `korean-ad` (CapCut-style Hangul karaoke for Korean speech: one short phrase at a time, lower-third, the spoken word shifts to a heavy weight — pair with `language: "ko"`; Korean `script_text` is supported), plus the Hangul identities below
`font`	Optional Hangul face for the chosen style. Omit to keep that style's own face. Hangul styles only — see Fonts.
`design`	Optional per-request overrides of the style's colours, typography, placement, phrasing and motion — see Design overrides.
`language`	Speech-to-text hint (`ko`, `en`, …). Omit for automatic detection.

style picks the look and the motion, design edits it, font picks the face it is drawn in, and language only tells speech-to-text what to expect. language never selects the style or the font. An omitted style does follow the wording — Korean copy resolves to black-outline rather than burning tofu through the Latin default — but a style you name is rendered as named.

Design overrides

A style is a set of design tokens, and design overrides them for one request. Every field is optional and merges over the style's own value, so one key changes one thing:

That burns black-outline with a cyan emphasis and everything else untouched.

Group	Fields
`colors`	`base`, `active`, `stroke`, `accent`, `accent_deep`, `card` (`null` draws no card)
`typography`	`base_weight`, `active_weight`, `active_scale`, `font_size_ratio`, `safe_width_ratio`, `stroke_width_px`
`placement`	`anchor_ratio`, `landscape_anchor_ratio` — line centre as a fraction of frame height
`phrasing`	`max_words`, `max_chars`, `pause_seconds`
`motion`	`enter_seconds`, `exit_seconds`, `emphasis_in_seconds`, `emphasis_out_seconds`

Colours are hex, rgb()/rgba(), or transparent; other CSS syntax is rejected rather than drawn into the render document. Numbers outside their documented range are a 400, so a look fails at request time instead of rendering wrong and billing. design is not supported on punch or tiktok-green, which still render on a path that reads none of these tokens.

Korean text on a Latin style is rejected

slam, punch and tiktok-green draw in Latin display faces with no Hangul glyphs. Sending Korean copy to one of them returns 400 (caption_hangul_text_latin_style) rather than re-styling the job: a caption you did not choose is worse than an error, and the alternative — a video full of tofu boxes — costs the same as a good one. Latin copy on slam is unchanged.

The same applies to font: the faces below are Hangul, so naming one alongside a Latin style returns 400 (caption_font_requires_hangul_style).

Hangul caption identities

For Korean speech — talking head, UGC, creator voiceover — use one of these rather than slam, whose Latin display face has no Hangul glyphs and renders Korean as tofu. They group words into phrase cards instead of one word at a time, and burn the transcript exactly as written with no case folding.

Style	Look
`black-outline`	CapCut white fill on a thick black outline, mid-frame. The safe default.
`weight-shift`	Phrase cards where the spoken word takes the weight and the rest drops back.
`highlight`	An accent block sweeps in behind the word being spoken.
`pill-karaoke`	The card sits in a dark pill; colour tracks the voice.
`clip-wipe`	Each word wiped in left-to-right. Clearest at small phone sizes.
`editorial-emphasis`	Left-aligned two-line card: the lead words stay small and the phrase-final word drops to a second line at roughly twice the size, in a display face, sliding in from the margin.

korean-ad is the ad karaoke look (weight-shift, with an accent colour on the spoken word). It is not what an omitted style resolves to — that is black-outline — so ask for korean-ad when you want the ad treatment.

An omitted style also drops the accent colour: both default styles were authored with a gold spoken-word tint, and a look nobody asked for should not introduce one, so a defaulted render keeps the fill colour on the spoken word. Naming black-outline (or slam) keeps that style's own gold tint, and design.colors.active sets it either way.

Fonts

Optional. Omitting font keeps the style's own face — Pretendard for korean-ad, weight-shift, highlight, pill-karaoke and editorial-emphasis, Do Hyeon for black-outline and clip-wipe. Setting it keeps the style and swaps the face.

editorial-emphasis draws its emphasis line in Black Han Sans whatever font says, because that identity's look is the contrast between its two faces rather than either one of them. font moves its lead line, like it moves the single line everywhere else.

`font`	Family	Feel
`pretendard`	Pretendard Variable	Clean baseline
`do-hyeon`	Do Hyeon	Thick rounded, the CapCut classic
`black-han-sans`	Black Han Sans	Impact
`jua`	Jua	Soft cute rounded
`dunggeunmo`	DungGeunMo	Pixel / retro
`bagel-fat-one`	Bagel Fat One	Fat rounded
`dongle`	Dongle Bold	Playful rounded display
`gasoek-one`	Gasoek One	Ultra-thick impact
`yeon-sung`	Yeon Sung	Brushy
`single-day`	Single Day	Soft cute handwritten
`hi-melody`	Hi Melody	Soft rounded cute
`nanum-pen`	Nanum Pen Script	Handwritten
`gowun-dodum`	Gowun Dodum	Soft editorial

All of them are SIL Open Font License 1.1 and ship with the renderer. Any other name is rejected rather than substituted, so a caption never falls back to a face you did not ask for.

weight-shift and korean-ad animate the wght axis, which only Pretendard carries; on a static face those styles keep their colour and scale emphasis and lose the weight travel.

Restyling without transcribing twice

To re-burn the same video under a different style, pass source_caption_id instead of video_url:

Sume reuses that caption's source video and the word timings it already has, so no second speech-to-text runs. Pass words alongside it only to correct the wording. Billing is unchanged — a restyle is still a render.

You can also supply words (word-level) or cues / segments (phrase-level overlay cards) with text, start, end in seconds. Either form skips speech-to-text and burns exactly that copy at those times — this is the path for silent clips. script_text, words, cues, and segments are mutually exclusive.

`script_text`

When provided, Sume keeps speech-to-text word timings as the timing source of truth and aligns burned-in wording to your script. Alignment can fail with typed public job errors:

script_alignment_mismatch
script_alignment_failed

Suggested next action: simplify_script_text_or_omit. Omit script_text to burn STT wording instead.

video_url must be a fetchable public HTTPS video URL.
Localhost, private-network, non-HTTPS, signed/private, and provider task URLs are rejected.
Raw cue lists, SRT uploads, and provider task ids are unsupported.