Music video captions — API v2 and v1

Choose the API version

Contract	Required policy	Delivery and settlement
API v2	captions.required: true	Requested captions must not be silently dropped from delivery. Do not combine required with mode: "off". Read the final operation status and warnings.
API v1	subtitle.required: true, fallback: "fail"	Required preparation can fail the Task. A later burn-in failure can still deliver a successful video without captions and a warning. New Omn bundles have no separate subtitle refund.

API v2 caption fields · API v1 creative modes

The sections and complete requests below use API v1.

Subtitles

If a successful video cannot deliver its requested subtitles, it stays successful and reports a subtitle warning such as MV_SUBTITLE_DISABLED_NO_TIMELINE, MV_AUTO_SUBTITLE_FALLBACK_SKIPPED, or MV_SUBTITLE_BURN_IN_SKIPPED. A new bundle order has no separate subtitle charge, so a missing subtitle does not create a credit refund. Historical orders that bought subtitle extraction/alignment components separately keep their original rule: only those paid components are refunded, capped at the task charge. Video generation remains payable. Check the Task’s final billed amount and workflow warningCodes. The Task, MV view and workflow use the same public warning vocabulary. Three advisory warnings report which lyrics the creative plan actually used:

Warning	Meaning	What to check
MV_CREATIVE_PLANNING_FROM_UNVERIFIED_TRANSCRIPT	Automatically recognized words, not customer-verified lyrics, shaped the plan. This also applies when a supplied SRT was unusable and recognition was used instead	Review how well the story and any captions match the song; provide source.lyrics or a valid srtUrl when wording matters
MV_CREATIVE_PLANNING_WITHOUT_LYRICS	No usable lyric meaning was available, so the plan followed the music, prompt and references	Review whether the story fits the song; missing lyrics do not mean the song is instrumental
MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED	Your lyrics were used, but their timing was estimated by machine alignment	Check caption timing; provide an accurate srtUrl for exact timing

The first two are mutually exclusive in the final plan. These warnings do not fail a delivered video and do not change billing or refunds. A preflight response describes the inputs known before recognition; inspect the completed Task, MV view and workflow for the final warning list.

Recognition filters suspect text before using it, including on instrumental music with subtitles disabled. Promotional outro phrases (for example requests to like or subscribe) are removed when their confidence or word timing shows they are not aligned with the singing; ordinary lyrics with normal timing are kept. Filtering is not a guarantee of lyric accuracy. For automatic subtitles, a line the lyric corrector cannot resolve is re-recognized from its own audio (at most four lines per MV); its text changes only when that reading matches one of the corrector’s same-syllable candidates, and its timing is unchanged. Provide source.lyrics when exact wording matters and review automatic subtitles against the audio; MV_SUBTITLE_TEXT_REVIEW_REQUIRED continues to apply. MV_NATIVE_PROMPT_COMPILATION_FALLBACK means prompt preparation used its fallback; review the delivered scene direction.

Omn V1 burns in visible subtitles from srtUrl, Suno lyric timing, or automatic transcription of an audio source. When you also send source.lyrics, the director plans from your lyrics and the transcription only supplies timing.

Send lyrics for exact wording

Automatic recognition of sung lyrics is a machine estimate. Correction fixes spelling-sized mistakes only, so a line with a missing syllable or a misheard phrase can remain wrong and keeps MV_SUBTITLE_TEXT_REVIEW_REQUIRED. When the captions or the story must use exact words, send source.lyrics (or a verified srtUrl).

subtitle_timeline_required remains for requests that ask for your own timing with automatic timing disabled and no usable timeline. generation.subtitleMode: "custom" alone does not disable automatic timing. Creative drafts default subtitles on for every engine. An MV with visible subtitles cannot be upgraded.

Choose a subtitle policy

These are complete alternative preflight/create bodies. Replace the example URLs with your own reachable files. Preflight the chosen body, then follow the saved-body create flow.

No visible subtitles: suitable when you want to preserve upgrade eligibility or add captions yourself later. Other upgrade restrictions still apply.

{
  "mode": "fast",
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "prompt": "A traveler follows a paper bird through a rainy hometown",
  "subtitles": false,
  "subtitle": { "mode": "off" },
  "generation": { "engineVersion": "omn-v1", "renderTier": "draft", "creativeMode": "prompt_story" }
}

Automatic timing: the example permits delivery without subtitles if subtitle preparation fails. Automatic subtitles are included in the bundle price of a new order.

{
  "mode": "fast",
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "prompt": "A traveler follows a paper bird through a rainy hometown",
  "subtitles": true,
  "subtitle": { "mode": "auto", "required": false, "fallback": "continue_without_subtitles" },
  "generation": { "engineVersion": "omn-v1", "renderTier": "draft", "creativeMode": "prompt_story" }
}

To require successful automatic subtitle preparation, use required: true and fallback: "fail" instead; failed required preparation can fail the Task. That policy is not proof that the delivered video has captions: inspect final warnings. On historical orders with separately paid subtitle components, a successful video whose subtitle burn-in was skipped refunds those components.

Set subtitle.language to zh, en or auto for automatic recognition and lyric correction. It takes precedence over top-level language; when omitted, the subtitle step inherits that field. Explicit subtitle.language: "auto" keeps language detection even if top-level language is fixed. This selects a recognition language, not a translation target.

Automatic timing accepts M4A audio, including audio selected with source.range; you do not need to rename your audio URL or provide an SRT to use it. A SUBTITLE_GENERATION_FAILED message about an incomplete transcription request does not mean that your audio is silent. Check the Task’s final status and warnings before deciding whether to submit a new paid request.

Recognition segments reported as unreliable are excluded. If no usable speech timing remains, preparation reports SUBTITLE_NO_SPEECH_DETECTED and follows your required/fallback policy. This does not certify that the source is instrumental. Use a portion with clear vocals or provide a verified SRT when the wording must be exact; automatic recognition still needs content review.

Automatic subtitles use recognized word timing to separate clearly marked Chinese lyric phrases, so a later phrase need not appear with the previous one. Short pauses can remain continuous; this is phrase-level display, not karaoke word highlighting. Timing and wording both require review on sung audio. Homophones can remain wrong even after automatic text correction. Correction also applies to a single timed lyric line. Without supplied lyrics it uses surrounding text to repair likely phonetic mistakes, preserves line timing, and retains the original line when a proposed edit would rewrite too much. A correction confidence value is not a measured word-accuracy score. Recognition can produce spurious words over an instrumental intro even with high confidence. Text correction cannot verify those words acoustically. ASR word timestamps can also shift with the selected audio window, especially at phrase endings. Preserving those timestamps during correction does not prove precise alignment with each sung word. Review the rendered subtitles against the original audio before publication; for deterministic lyrics and timing, provide an accurate srtUrl.

MV_SUBTITLE_LYRICS_CORRECTED reports a text change. Low-confidence fallback, failed correction and uncertain or rejected edits have separate warning codes. A subtitle review warning does not fail a delivered task or automatically refund delivered subtitles. Check the final billing fields for actual settlement.

If you know the lyrics, provide source.lyrics for the selected audio portion, with one lyric line per line. It helps correct text while automatic timing still comes from the audio. Do not include section headings such as [Verse] as lyric lines. A supplied lyric reference is not independent evidence of recognition accuracy. Use a verified SRT when exact wording and timing are required.

To verify delivery, play the final video at the subtitle cue times, then compare Task and workflow warnings and the settled charge. In a new bundle order, subtitles are not a separate charge, so omitted subtitles leave the bundle charge unchanged. On historical orders, an omitted paid subtitle component is the only part refunded. human_review_required is a quality advisory and does not itself fail the Task or trigger a refund.

Your own SRT: use this when you need your supplied wording and timing. The SRT must be publicly reachable, parseable, at most 4MB, and usable for the selected output duration. source.lyrics alone is not an SRT timeline.

{
  "mode": "fast",
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "prompt": "A traveler follows a paper bird through a rainy hometown",
  "subtitles": true,
  "subtitle": { "mode": "provided" },
  "srtUrl": "https://media.example.com/song.srt",
  "generation": { "engineVersion": "omn-v1", "renderTier": "draft", "creativeMode": "prompt_story", "subtitleMode": "custom" }
}

subtitles controls visible captions; subtitle.mode controls automatic timing and can override it: off disables captions and auto enables them. Keep the values consistent as above. Sending subtitles: false together with srtUrl is rejected. generation.subtitleMode chooses subtitle rendering behavior, not the engine or automatic timing policy; custom still permits automatic timing unless you disable it with subtitle.mode.

If visible subtitles have no usable timing and automatic timing is disabled, preflight can reject the request (MV_SUBTITLE_TIMING_REQUIRED, MV_ENGINE_UNSUPPORTED with subtitle_timeline_required, or a Suno timing availability error, depending on the source and options). Supply timing or change the policy; do not retry unchanged. A successful video can still carry subtitle warnings described above. Refund examples.