How to burn captions onto a video with the Sume API

To burn captions onto a video with Sume, send the clip's public HTTPS URL to POST /v1/video-captions. Sume returns a job-backed captioned video, timed by speech-to-text or by word and phrase timings you supply, in a style you name or one picked from the wording.

Every detail below comes from the Video captions docs, read on 2026-09-25.

How do I create a caption job?

Use the standalone captions API when you already have a finished clip. video_url is required. Optional fields are style, font, design, language, script_text, words, and cues / segments, plus the usual mode, webhook_url, and wait_timeout_seconds communication fields. GET /v1/video-captions/:id reads the job back.

This request burns the punch style and aligns the burned wording to a script:

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-caption-script-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "punch",
    "script_text": "Say hello to the Sume developer platform."
  }'

Which caption style should I pick?

style picks the look and the motion, design edits it, font picks the face, and language (ko, en, …) only tells speech-to-text what to expect. language never selects the style or the font. Omit style and the wording decides: slam for Latin copy, black-outline for Korean. A style you name is rendered as named.

design overrides a style's colors, typography, placement, phrasing, and motion tokens for one request. Colors are hex, rgb()/rgba(), or transparent, and a number outside its documented range is a 400, so a bad look fails at request time instead of rendering and billing. font swaps the face on Hangul styles only, from a fixed list of SIL Open Font License 1.1 faces such as pretendard, do-hyeon, and noto-sans-kr. Any other name is rejected rather than substituted.

How do I caption a silent clip or burn my own wording?

Speech-to-captions, from script_text or from speech-to-text when you omit it, needs audible speech. A silent clip fails as caption_no_speech with next_action: use_overlay_captions, not as a generic policy reject.

Four fields control the wording, and they are mutually exclusive:

• cues or segments: phrase-level overlay cards, each with text, start, and end in seconds. They skip speech-to-text, so this is the path for silent clips.
• words: word-level text, start, and end. Also skips speech-to-text.
• script_text: speech-to-text word timings stay the timing source of truth, and the burned wording is aligned to your script. Alignment can fail with script_alignment_mismatch or script_alignment_failed; the suggested next action is simplify_script_text_or_omit.

Can I restyle a captioned video without transcribing it again?

Yes. Send source_caption_id instead of video_url, with the new style: { "source_caption_id": "…", "style": "black-outline" }. 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.

How do I get the captioned video, and what does it cost?

Poll GET /v1/jobs/:id/status and GET /v1/jobs/:id/result, or read GET /v1/video-captions/:id. When ready, the resource returns public-safe status, the style, and the captioned video_url and artifacts. Raw transcripts, renderer internals, and signed source URLs are not part of the public contract.

Each accepted standalone caption job reserves and captures a fixed amount of Sume usage for videos up to 60 seconds under the current fixed estimate. The amount is on API pricing, and the docs say to confirm live pricing in GET /v1/catalog; How Sume pricing works explains the wallet.

Inline captions on a talking avatar video are a separate add-on on the avatar-video estimate and do not create a video_caption resource.

What does the captions API reject or not support?

• A video_url that is not a fetchable public HTTPS video URL. Localhost, private-network, non-HTTPS, signed or private, and provider task URLs are rejected.
• SRT uploads and provider task ids. Pass phrase-level text as cues or segments instead.
• Korean copy on slam, punch, or tiktok-green: 400 (caption_hangul_text_latin_style). Latin copy on slam is unchanged.
• A Hangul font named with a Latin style: 400 (caption_font_requires_hangul_style).
• design colors in CSS syntax other than hex, rgb()/rgba(), or transparent, and design numbers outside their documented range.