Omn V1 creative options

Omn V1 quickstart · Compare music video options

Singing, performance and dance

All fields below belong to generation except the top-level lipSync option. Set managedVersion: "premium-v2" whenever you send performanceMode. Do not combine that profile with lipSync, quality, sing_dance or sing_play.

Mode	Request	Singers and references
Automatic MV	Omit performanceMode	referenceImages or a generated Visual Board; optional characterImage. Omitting generation.creativeMode (or using auto/performance) leads with performance. Enable lipSync when singing is wanted. Use lyrics_story, prompt_story or mood_visual for another direction
Singing	performanceMode: "sing"	Optional one or two ordered portraits in generation.lipReferenceImages, or characterImage; omit both to generate a performer
Singing with performance	performanceMode: "sing_perform"	The same optional singer portraits
Instrumental performance	performanceMode: "perform"	referenceImages or a generated Visual Board
Dance	performanceMode: "dance"	referenceImages or a generated Visual Board; optional motion reference video
Singing and dancing / singing and playing	creativeMode: "sing_dance" / "sing_play"; omit performanceMode	Omn plans recurring singing and dance/instrument shots; optional characterImage
Compatible lip-sync option	lipSync: true; omit performanceMode	One singer; characterImage is optional; Omn V1 can generate the identity

Omn V1 accepts valid audio without images, lyrics, a title or a visual prompt. Without song semantics, it builds coherent visuals from the music’s timing and energy. Missing lyrics do not mean the song is instrumental. Ordinary reference images may show scenery or style; use characterImage or singer portraits to choose a specific identity. Explicit wardrobe requests take priority over the clothing in a supplied image. A portrait in referenceImages can also be reused as the identity reference when the preparation check confirms clear faces, the planned identities and the full cast. An approved customer portrait is reused directly; it is not redrawn merely because it lacked an identity label. Scenery and images with uncertain identities are not automatically treated as portraits.

For OneClick V1, lipSync: false prevents lip-sync shots. sing_dance and sing_play enable singing when lipSync is omitted; an explicit false still wins. Lip-sync on/off uses the same Omn V1 price. Omn V1 repairs inconsistent system-created references or planning text before buying videos, with no additional customer charge. A preparation service failure does not mean you must supply a portrait. Preflight still checks whether the requested settings are available.

Singing shots show the singer performing the vocal with visible mouth movement; other shots avoid singing and lip movement. When lipReferenceImages and characterImage are both sent, each singing shot is led by its singer’s portrait. The compatible lipSync: true option is also available at 540p. characterImage is kept as the identity reference on every shot that shows the cast. On Omn V1, all performance modes use the selected tier’s price: for example Standard 720p is 12 credits per second and HD 1080p is 20 credits per second before add-ons. Effective output must be at least 5 seconds; there is no minimum credit charge. perform means stage or instrumental performance; sing_perform combines singing and performance. For a narrative video instead, set generation.creativeMode to lyrics_story or prompt_story; mood_visual keeps a mood-led video without a protagonist arc.

sing_dance and sing_play are rendered only by Omn V1. A request that sets one of them and names no engine runs on Omn V1; with engineVersion vidu-v1 or vidu-v2, or with managedVersion: "premium-v2", it is rejected with 400 VALIDATION_ERROR. Both use the selected tier’s price, with no lipSync charge. Singing shots follow the vocal only, with natural mouth shapes that close in pauses; windows with little sung vocal are filmed as performance or concept shots instead.

Capabilities report what the deployment offers: lipSync (singing shots), maxSingers (up to 2 for explicit singing modes), dance, motionVideo and characterImage. They are checked with reference images. A text-only request, with no reference images, Visual Board, character image or singer portraits, also needs text-only rendering for every requested singing, performance or dance shot type. Omn V1 never renders a requested specialist shot as a story shot: when the tier, aspect ratio or available capacity cannot serve it, the request returns 422 MV_ENGINE_UNSUPPORTED with lip_sync_unsupported, specialist_mode_unsupported or aspect_ratio_unsupported before any charge.

Dance motion reference

For Omn V1 dance, generation.motionReferenceVideo supplies a public HTTPS video whose moves drive the dance shots. Each dance shot follows the part of the reference that matches its time in the song, looping a shorter reference. The reference’s own sound is not used. Send it together with generation.motionRightsConfirmed: true:

{
  "mode": "fast",
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "aspectRatio": "9:16",
  "referenceImages": ["https://media.example.com/dancer.jpg"],
  "generation": {
    "engineVersion": "omn-v1",
    "managedVersion": "premium-v2",
    "performanceMode": "dance",
    "motionReferenceVideo": "https://media.example.com/choreography.mp4",
    "motionRightsConfirmed": true
  }
}

Replace the example URLs with your own files. Motion references are available at the draft and standard tiers. Choose one explicitly; omitting the tier uses Standard 720p. Motion reference video is unavailable at HD and Ultra.

Requirement	Checked
Public HTTPS URL that declares a size of at most 128MB and, if it declares a content type, video/* or application/octet-stream	Before any charge
generation.motionRightsConfirmed: true and performanceMode: "dance"	Before any charge
2–660 seconds long, short side at least 240px, long side at most 4096px	While the Task runs

A failed pre-charge check returns 400 VALIDATION_ERROR, with the field in details.field (generation.motionReferenceVideo, or generation.motionRightsConfirmed when the confirmation is missing). Quote the same request with hasMotionReferenceVideo: true.

Motion transfer applies only to 16:9 and 9:16 videos:

• At 16:9 or 9:16, a request for which motion transfer is not available returns 422 MV_ENGINE_UNSUPPORTED with specialist_mode_unsupported before any charge; check motionVideo in capabilities.
• At 1:1, 4:3 or 3:4 the request is accepted and planned exactly like OneClick V2 dance without a reference; the video is not used.
• A reference that is unusable while the Task runs (unreachable, not decodable or outside the limits above) also dances without motion transfer, at the same price.

An MV planned for motion transfer cannot be upgraded.

Caution

You are responsible for the media you submit. Send only motion footage, reference images, character images and singer portraits that you own or are licensed to use, with the consent of the people who appear in them. motionRightsConfirmed: true records your confirmation for the motion video; it is not a rights check.

Creative direction and visual style

In guided MV Maker, creative direction and visual style are separate choices. Omn Auto direction and Story use narrative planning; creative drafts with performanceMode: "auto" preserve that behavior. A direct API request that explicitly selects Omn and omits creativeMode, or sets it to auto, uses singer-led performance around concept shots. Stage performance, Dance, Singing, and Singing + performance request their respective performances explicitly. Singing needs a clear front-facing character image in the guided form; the advanced form can supply two ordered singer portraits.

Visual presets are experimental instructions for art direction, not separately validated models or guaranteed output styles. Auto style lets the planner use the song, description and references. The six named presets can be combined with a direction; these are creative brief examples, not generated samples:

Visual style	Direction	Example description
Cinematic	Story	A traveler returns to a rainy hometown; warm window light and restrained camera moves connect the verses
Anime	Story	A student follows a paper bird through a summer town; keep the character design and cel shading consistent
Ink wash	Story	Mountains emerge from ink and mist; leave open space and move slowly with the flute melody
3D animation	Dance	A rounded toy robot dances in a pastel room; keep its proportions and materials consistent
Vaporwave	Stage performance	A keyboard player performs under pink and cyan lights in a retro arcade
Product visuals	Story	Follow the supplied sneaker’s shape, materials and colors through a city at dawn; leave room for a title added later

Use reference images for identity and product details. Product visuals do not guarantee accurate generated logos or lettering; add exact marks in post-production. Stylized singing also needs a usable face reference and a successful media preflight; a preset does not guarantee lip-sync quality.

Creative draft fields renderTier, resolution and schedule require engineVersion: "omn-v1". They are saved and reused by validation, preview and full generation. A guided draft defaults to Standard 720p; setting a tier alone uses its default resolution. Here is a free draft request body; replace the audio URL with your own file:

{
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "engineVersion": "omn-v1",
  "performanceMode": "story",
  "styleId": "anime",
  "renderTier": "hd",
  "resolution": "1080p",
  "schedule": "economy",
  "description": "A student follows a paper bird through a summer town",
  "subtitles": false
}

Save the returned draft ID and version, then validate that version through POST /api/v1/mv/drafts/{id}/preflight. Review its price before the separate paid preview or generate operation; save the exact purchase body and idempotency key for retries. When using POST /api/v1/mv directly, omit performanceMode and choose generation.creativeMode: "lyrics_story" or "prompt_story" for a story; story is a draft direction, not a generation.performanceMode enum. Drafts also accept sing_dance and sing_play on Omn V1; directly, send them as generation.creativeMode with engineVersion: "omn-v1" and managedVersion: "oneclick-v1" (or omit it to use that default).

Duration and long songs

Omn V1 accepts 5 seconds up to each purchase’s maxDurationSec in capabilities: at most 600 seconds for OneClick V1 where the deployment permits it, and 300 seconds for OneClick V2. A longer song is rendered as more shots at the same per-second rate. Outside the range Omn V1 returns duration_unsupported; one whose rendering cost would exceed the published price returns cost_limit_exceeded.

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. Settlement refunds only the paid subtitle extraction/alignment components recorded in the original quote, capped at the task charge. Video generation remains payable; uncharged subtitles do not create a refund. Check the Task’s final billed amount and workflow warningCodes. The Task, MV view and workflow use the same public warning vocabulary. MV_CREATIVE_PLANNING_WITHOUT_LYRICS means the creative plan did not use usable lyrics; review how well the story matches your song. It does not itself promise a refund. 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. 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" },
  "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. Review the automatic subtitle price in preflight.

{
  "mode": "fast",
  "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" },
  "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, since Omn’s successful-video settlement also handles missing subtitle burn-in with a refund of paid subtitle 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. When the quoted subtitle component is delivered, it remains payable. When it is omitted from a successful video, only that paid component is 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" },
  "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.

Character and style prompts

For a simple character-led MV, describe who appears, their clothing and a small number of actions in prompt. With no image, Omn V1 generates reference images and includes that work in the preflight quote. For a particular look, add generation.style, for example a hand-drawn animation treatment, and set aspectRatio explicitly for the intended viewing format.

When supplying characterImage, distinguish identity from the requested wardrobe or setting in the prompt. A face reference does not imply that every item of clothing should be retained. Avoid contradictory requirements across the image, prompt and style. Shot count is planned from the selected duration; an exact shot-count instruction in free text is not a dedicated count control and may conflict with the plan. Preflight validates inputs and estimates cost; subsequent creative preparation can still fail and settle with a refund.