Auto-generate subtitles API: transcribe, fix the text, then burn

To auto-generate subtitles you can check before they are burned in, transcribe the clip with POST /v1/video-inspect and transcribe: true, fix the returned text, then send it as script_text to POST /v1/video-captions. Sume keeps the speech-to-text word timings and aligns your corrected wording to them.

The steps come from Sume's Video inspect and Video captions docs and the API reference schema, read on 2026-09-26. Without a review step, a caption job with no wording transcribes and burns in one call, as in How to burn captions onto a video.

How do I get an editable transcript?

Inspect reads one clip that is already a media.sume.com artifact or asset in your workspace, such as the output of an earlier Sume job; there is no open-internet fetch. Idempotency-Key is required. frames: false skips the stills, language_code (for example en or ko) is an optional hint, and segmentation.mode: "sentence" adds gapless sentence segments shaped like caption lines.

The default mode is sync: the call waits up to 30 seconds and answers 200 with the finished inspect, or 202 with a queued job to poll. Read the resource later with GET /v1/video-inspect/:id.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-inspect-transcript-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "frames": false,
    "transcribe": true,
    "segmentation": { "mode": "sentence" }
  }'

What does the transcript contain?

When ready, the inspect resource carries probe, warnings[], and a transcript object. These are the transcript fields you edit or reuse:

How do I burn the corrected text?

Fix names, brand terms, and typos in text, then send the whole corrected text as script_text (up to 8,000 characters) with the same media.sume.com URL as video_url. Sume keeps the speech-to-text word timings as the timing source of truth and aligns the burned-in wording to your script.

Alignment can fail with the typed job errors script_alignment_mismatch or script_alignment_failed, and the suggested next action is simplify_script_text_or_omit. Omit script_text to burn the speech-to-text wording instead. script_text, words, cues, and segments are mutually exclusive.

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-reviewed-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "script_text": "Welcome to the Acme onboarding tour. Today we set up your first project."
  }'

Can I burn my own timings instead?

Yes. words and cues / segments skip speech-to-text and burn exactly your copy at your times, so there is no alignment step to fail:

• words: 1–1,200 entries of text, start, and end in seconds, each text up to 200 characters. Inspect's words[] use a word key, so rename it to text when you copy them across.
• cues, or its alias segments: 1–200 phrase-level cards with text, start, and end, each text up to 400 characters. A newline in text makes a two-line card.
• A cue takes only text, start, and end. To reuse inspect's sentence segments[] as cues, keep those three keys and drop index and duration_seconds.

What does it cost, and what are the limits?

The transcript and the burn are two jobs, billed separately, each with its own caps:

• Inspect's probe and stills are unbilled. Only the transcript reserves, at the Sume STT 1.0 rate: $0.01 per audio minute on API pricing, plus a 5.5% agent fee by default.
• Without duration_seconds, the transcript reserves 1 minute; the hint maxes out at 600 seconds. Inspect sources can run up to 1,800 seconds.
• A clip with no audio track fails inspect with inspect_source_has_no_audio. A speech-to-captions job on a silent clip fails as caption_no_speech.
• A standalone caption job bills the fixed amount listed on the Video captions page, for videos up to 60 seconds under the current fixed estimate.
• The caption resource returns the captioned video_url, not a transcript: raw transcripts are not part of its public contract. That is why the editable text comes from inspect.
• SRT uploads are not supported. Send phrase-level text as cues or segments instead.