Caption API script_alignment_mismatch: what it means and how to fix it

script_alignment_mismatch and script_alignment_failed are the two typed job errors Sume's caption API returns when the script_text you supplied cannot be aligned to the speech in the video. The suggested next action is simplify_script_text_or_omit: shorten or simplify the script to match what is said, or omit script_text and burn the transcript wording instead.

This page follows the Video captions docs, read 2026-09-29. The docs do not publish the matching threshold, so treat the guidance below as practical advice, not a rule.

What does script_text actually do?

When provided, Sume keeps speech-to-text word timings as the source of truth and aligns the burned-in wording to your script. So the script sets the wording while the speech sets the timing, and a script that differs a lot from what is said gives the aligner nothing to match.

Which options fit which situation?

How do I fix a failing script?

• Compare the script with what is actually said and edit the script to match the speech.
• If the script is Korean, use a Hangul style; Korean copy on a Latin style is a separate 400.
• If the script still fails, omit it, or send words with exact times.

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-002" \
  -d '{
    "video_url": "https://example.com/clean.mp4",
    "style": "punch",
    "script_text": "Say hello to the Sume developer platform."
  }'

Do failed jobs still charge?

The docs give a $0.20 fixed estimate per accepted job and do not describe refunds for alignment failures specifically. Sume's generation docs say failed jobs release or refund the reservation where applicable; check GET /v1/usage for what a specific job settled at.

Which other caption errors should I know?