Skip to content
OmnAPI Docs
Music Video

Plan a music video with drafts

Open App ↗

Guided creative drafts

Section titled “Guided creative drafts”

The draft workflow saves a reusable creative plan before generation. Check GET /api/v1/mv/capabilities for available generation options and GET /api/v1/mv/styles for style cards. These development additions may be unavailable on a deployment that has not adopted this contract preview.

  1. Create a draft with POST /api/v1/mv/drafts. Supply a Suno clip or public audio URL in source. Save the returned draft id and version.
  2. Omit styleId and performanceMode, or set them to auto, to let the song guide art direction and visual treatment. Select singing or dance explicitly when required. The draft defaults to vidu-v2; select omn-v1 only when capabilities report it and preflight accepts the draft (see the Omn V1 engine guide).
  3. Read it with GET /api/v1/mv/drafts/{id}. Update with PUT /api/v1/mv/drafts/{id}, sending expectedVersion and the complete brief. A stale revision returns 409; reread before applying changes.
  4. For a separately priced ten-second preview, call POST /api/v1/mv/drafts/{id}/preview/preflight with expectedVersion. To purchase it, call POST /api/v1/mv/drafts/{id}/preview with the matching preflightId, expectedVersion, maxCredits and an Idempotency-Key header.
  5. For a full video, call POST /api/v1/mv/drafts/{id}/preflight, then explicitly purchase with POST /api/v1/mv/drafts/{id}/generate using that revision, preflight receipt, credit limit and a separate idempotency key.

Drafts expire after 30 days. Saving or checking a draft does not buy generation; preview and full-video generation are separate paid Tasks. Keep each purchase’s idempotency key and exact request body for recovery after an uncertain response. The lower-level POST /api/v1/mv retains its existing mode and generation contract.

Song context and reference checks

Section titled “Song context and reference checks”

In this development preview, audio sources accept optional title (up to 200 characters), musicStyle (up to 500 characters), and lyrics (up to 5,000 characters). These fields also survive saved creative drafts. Style and performance remain optional; omitted choices still use Auto.

New Omn V1 preparation attempts automatic lyric recognition when timing is missing. Recognized lyrics are estimates. If neither song information nor an explicit visual concept can support the plan, the Task stops and asks for more context instead of silently choosing an unrelated concept. Add lyrics or song information; for instrumental music, describe its mood or intended visuals.

Preparation also checks character references and keyframe composition before video generation. An unclear identity image or incompatible composition stops the Task; replace the reference or revise the brief before a new purchase. These checks occur during the paid Task, after preflight, and do not guarantee commercial quality. They never automatically purchase replacement images or videos. Technical failure follows the normal Task settlement policy.

Music Video overview · Edit scenes