Music Video input reference

Reference

Use the Fast MV quickstart for a complete creation flow.

Source variants

{
  "type": "suno",
  "clipId": "<suno-clip-id>",
  "range": {
    "startSec": 12,
    "endSec": 72
  },
  "lyrics": "optional override"
}

{
  "type": "audio",
  "audioUrl": "https://example.com/song.mp3",
  "durationSec": 60,
  "range": {
    "startSec": 0,
    "endSec": 45
  },
  "lyrics": "optional plain text"
}

Host audio in your own publicly reachable HTTPS environment and pass audioUrl. Inline base64 audio and direct file uploads are not part of the public API.

OmnAPI validates external audio URLs before create/preflight can succeed. The URL must expose bounded size metadata, must not resolve to a private or local network address, must stay within the audio size/time limits, and must yield a readable duration. The default remote audio cap is 128MB. Effective duration must be 10-600 seconds for OneClick V1 Fast, 10-300 seconds for Premium MV V2, or 10-300 seconds for Studio.

Source field	Applies to	Notes
`clipId`	`suno`	Required Suno clip id.
`audioUrl`	`audio`	Required public http(s) audio URL for `audio` sources. Suno sources do not accept audio fallbacks in the public API.
`durationSec`	`audio`	Optional client duration hint. OmnAPI validates external audio and rejects material disagreement.
`range.startSec`	`suno`, `audio`	Optional segment start, seconds from original source.
`range.endSec`	`suno`, `audio`	Optional segment end; must be greater than `startSec` and produce a valid effective duration for the selected Fast version or Studio.
`lyrics`	`suno`, `audio`	Optional plain-text lyrics/context, at most 5000 chars. For `audio`, this guides visual planning. Exact subtitle timing comes from `srtUrl`, Suno timing, or `subtitle.mode="auto"`.

Producer music results can be sent to MV as ordinary public audio URLs. Pass the audio resource URL with source.type="audio" and keep any lyrics as visual context unless you also provide srtUrl or let OmnAPI generate timing with subtitle.mode="auto".

Mode configs

generation is MV-specific and separate from config, which is the standard task envelope.

Fast generation

{
  "generation": {
    "style": "cinematic neon night",
    "quality": "standard",
    "referenceStrategy": "direct",
    "subtitleMode": "custom",
    "creativeMode": "performance",
    "promptMode": "verbatim",
    "visualBoard": {
      "imageProvider": "gpt-image-2",
      "preset": "detail"
    }
  }
}

Field	Notes
`managedVersion`	`oneclick-v1` (default) or `premium-v2`. Existing clients stay on V1 unless they opt in explicitly.
`performanceMode`	Premium V2 only and required there: `sing`, `sing_perform`, `perform`, or `dance`.
`lipReferenceImages`	Premium V2 singing modes only: 1-2 ordered, distinct public singer portraits. `characterImage` is the single-portrait fallback when this field is omitted.
`style`	Fixed visual style hint sent as the Fast visual style lever alongside the top-level `prompt`.
`quality`	OneClick V1 only: `standard` (default) or `high`. High quality is available only at `720p` and `1080p`; if `resolution` is omitted, Fast uses `720p`.
`referenceStrategy`	`direct` or `synthesize`. Fast defaults to `direct` when `referenceImages` are supplied and `synthesize` when they are omitted. Use `synthesize` to generate unified Visual Board scene references before managed generation.
`subtitleMode`	`vidu` (API default) or `custom`. `vidu` lets the managed generation service compose subtitles. `custom` renders a foreground layer after generation, limits each cue to two lines, and splits oversized cues over time. When `srtUrl` is absent, audio sources default to `subtitle.mode="auto"` and use Subtitle Sync to create timing first.
`motionPreset`	Optional OmnAPI-level prompt policy. Omit it for automatic selection: lip-sync requests use close-up guidance, clear dance/high-energy direction uses wider rhythmic motion, synthesized references use cinematic motion, and direct references retain stable performance behavior. Explicit values remain `stable_performance`, `cinematic_light`, `dynamic_dance`, and `lip_sync_closeup`.
`creativeMode`	Creative intent: `auto`, `lyrics_story`, `prompt_story`, `mood_visual`, or `performance`. Omit for `auto`.
`promptMode`	Prompt handling: `auto`, `verbatim`, or `creative_brief`. Use `verbatim` to preserve the caller prompt or `creative_brief` to compile it into a managed generation brief.
`visualBoard.imageProvider`	Optional image provider for OmnAPI-generated Visual Board references when `referenceImages` is omitted. Use `gpt-image-2`, `p-image`, or `viduq2`. This maps to `/quote`’s flat `visualBoardImageProvider`.
`visualBoard.preset`	Visual Board policy: `auto`, `speed`, `detail`, or `off`. `off` disables generated Visual Board references.

generation.motionPreset is an OmnAPI prompt policy; omitting it enables the automatic selection described above without adding an auto enum value to the public API. generation.creativeMode, generation.promptMode, and generation.visualBoard.preset use the exact enums in the table above.

Premium V2 requires performanceMode, uses 720p, and accepts effective durations up to 300 seconds. sing and sing_perform require singer portraits; perform and dance use caller referenceImages or an automatically generated Visual Board. Premium V2 rejects top-level lipSync and generation.quality instead of silently translating them. It does not fall back to OneClick V1.

For OneClick V1 lip-sync, pass a clear frontal characterImage and set lipSync=true. OmnAPI validates that image and uses it as the lip-sync reference for the managed workflow. Premium V2 singing uses the separately documented generation.lipReferenceImages list.

The three Premium V2 selectors are generation.managedVersion, generation.performanceMode, and generation.lipReferenceImages.

When referenceImages is omitted, OmnAPI generates Visual Board references and uses an automatic count based on duration: 1 image for up to 10 seconds, 3 for 10-30 seconds, 4 for 30-90 seconds, 5 for 90-180 seconds, and up to 7 for longer supported requests. The generated pack uses distinct roles such as character identity, world/style, motif, and climax. World/style and motif references may intentionally omit the recurring character so the managed MV is not forced into performer shots. Use generation.visualBoard.imageProvider to choose the image option for generated Visual Board references. If a Fast request includes characterImage and no referenceImages, the character image is offered to reference-capable Visual Board image options. When the selected option or fallback path cannot use reference inputs, the request still proceeds and returns MV_CHARACTER_IMAGE_REFERENCE_IGNORED in warningCodes. The exact Visual Board strategy may evolve without changing the request shape.

When characterImage and referenceImages are both present, Fast keeps the caller references as the managed generation references by default. If you need OmnAPI to create a more unified set of scene references first, set generation.referenceStrategy="synthesize". In that synthesis path, characterImage is used as the identity reference for capable image providers, and at most six caller references are used as secondary scene/style references. If more than six secondary references are supplied, the request still proceeds and returns MV_REFERENCE_IMAGES_TRUNCATED_FOR_CHARACTER in warningCodes.

Studio generation

{
  "generation": {
    "imageProvider": "gpt-image-2",
    "videoProvider": "p-video",
    "videoModel": "p-video"
  }
}

Field	Notes
`imageProvider`	Scene-still generation option. Public values include `gpt-image-2`, `viduq2`, and `p-image` when enabled.
`videoProvider`	Scene-video generation option used when rendering or re-rendering scenes.
`videoModel`	Rendering model code, for example `p-video` or `viduq3-turbo` when enabled.

Use the top-level prompt for Studio visual style and scene direction. Available options may change as the public catalog evolves. The API accepts the documented option codes directly.

Subtitle behavior

Mode	Source	`generation.subtitleMode`	`subtitles=true`	`srtUrl`	Behavior
Fast	suno	`vidu`	Required	—	OmnAPI converts the Suno timeline to subtitles when available, then lets the managed generation service render them.
Fast	suno	`custom`	Required	—	OmnAPI converts the Suno timeline when available and renders subtitles after generation. If no usable timing exists, create/preflight fails with `MV_SUBTITLE_TIMING_REQUIRED`.
Fast	suno	any	Required	yes	Caller-supplied SRT wins.
Fast	audio	`vidu`	Required	yes	Caller-supplied SRT is passed to the managed generation service.
Fast	audio	`custom`	Required	yes	Caller-supplied SRT is used by OmnAPI for post-generation subtitle rendering.
Fast	audio	`vidu`	Required	—	Default: OmnAPI generates SRT with Subtitle Sync, then passes it to the managed generation service. With `subtitle.mode="provided"`, the provider may infer timing and the task includes `MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED`.
Fast	audio	`custom`	Required	—	Default: OmnAPI generates timing with Subtitle Sync, renders subtitles after generation, and returns `MV_AUTO_SUBTITLE_GENERATED`. With `subtitle.mode="provided"`, create/preflight fails with `MV_SUBTITLE_TIMING_REQUIRED`.
Studio	audio	Not applicable	Required	—	Default: OmnAPI generates line timing with Subtitle Sync for storyboard/final subtitle burn-in. With `subtitle.mode="provided"`, subtitles are disabled and the task includes `MV_SUBTITLE_DISABLED_NO_TIMELINE`.
any	any	any	false	any	No subtitles.

Custom Fast subtitles are placed in a post-generation foreground layer. Each event is limited to two lines; longer text is split into consecutive events within the original cue timing rather than stacked into three or more lines.

subtitle.fallback controls ASR failure behavior for auto subtitles. The default is fail. Use "continue_without_subtitles" when an MV should still finish even if lyrics cannot be extracted from the audio.