script_alignment_mismatch: fixing a caption job with script_text

script_alignment_mismatch means the script_text you sent does not line up with what speech-to-text heard. Sume keeps the speech-to-text word timings as the source of truth for time and tries to align your script to them. If it cannot, the job fails with script_alignment_mismatch or script_alignment_failed, and the recommended next action is simplify_script_text_or_omit.

Why alignment fails

Sume does not retime your script by guessing. It places your words onto the heard words, so large differences break the match. The docs do not publish a numeric tolerance, so do not plan around one; treat any substantial rewrite as a risk.

• The speaker ad-libbed or skipped lines that are in your script.
• The script has stage directions, speaker labels or numerals written differently from how they were spoken.
• The recording is a different take than the script.
• The clip has more than one language, or a language other than the one you expected.

Your three options

Choosing between them

Use the simplified script when the goal is correct brand spelling, such as a product name that speech-to-text writes wrong. Keep the script to the lines that were actually said, in the order they were said.

Omit the script when accuracy matters less than speed. Use words when you have timings from another tool, for example from video inspect with transcribe: true and sentence segmentation, and you only need Sume to burn them in.

Request that includes a script

The docs' own example sends script_text with the punch style.

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."
  }'

Diagnosing a failed alignment

Read the job's error code, not only the message. Both alignment codes come back as typed public job errors with the same recommended action, so one handler can cover them. A good handler tries once with a trimmed script, then once with no script, and finally logs the clip for a human if brand spelling is critical.

If you only need a handful of names spelled right, a short script of those exact phrases is more likely to align than a full paragraph, but the docs only promise that simplifying is the recommended next step, not that it always succeeds.

• Do not send script_text together with words, cues or segments; only one of the four is allowed per request.
• Burning the speech-to-text words needs no script at all.