AI Music Video Fast Quickstart

MV Fast creates a finished music video from a public audio source or Suno clip. Use this flow for production calls:

Managed version	Select with	Duration / resolution	Best for
OneClick V1	Omit generation.managedVersion or set oneclick-v1	10-600s; 540p, 720p, or 1080p	Existing integrations, quality tiers, optional V1 lip-sync, and scene editing
Premium MV V2	Set generation.managedVersion: "premium-v2"	10-300s; fixed 720p	Explicit singing, performance, and dance modes

Premium V2 is opt-in and never falls back to V1. See the Premium MV V2 guide for its complete mode and image matrix.

Note

Upgrading an integration that used the MV API before July 10, 2026? Read the MV migration notes before changing strict response schemas or media URL storage.

1. GET /api/v1/mv/fast/availability before production batches.
2. POST /api/v1/mv/quote for a quick cost estimate.
3. POST /api/v1/mv/preflight to validate public media URLs and get a reusable create-time estimate.
4. POST /api/v1/mv with mode: "fast" and an Idempotency-Key.
5. Poll GET /api/v1/tasks/{taskId}.
6. GET /api/v1/mv/{mvId}/final for a fresh MP4 URL.
7. Optional: quote and edit a generated scene, poll the edit task, read MVView, quote and finalize the recomposition, poll the finalize task, then refresh GET /api/v1/mv/{mvId}/final.

1. Availability

curl 'https://api.omnapi.com/api/v1/mv/fast/availability?managedVersion=oneclick-v1' \
  -H "x-api-key: $OMNAPI_KEY"

Read both status and gateEnabled. The public contract currently reports gateEnabled: true, so an unknown or unavailable status returns 503 MV_PROVIDER_UNAVAILABLE before charging; back off using retryAfterSec. Quote and preflight remain available while delivery health is unverified. Use ?managedVersion=premium-v2 for Premium V2; do not reuse a V1 availability result for V2 admission.

2. Quote

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "durationSec": 10,
    "resolution": "540p",
    "lipSync": false,
    "visualBoardStrategy": "direct_scene_images",
    "visualBoardImageProvider": "gpt-image-2",
    "visualBoardImageCount": 1
  }'

Response:

{
  "credits": 130,
  "quoteId": "019c...",
  "operation": "create",
  "expiresAt": "2026-07-10T12:10:00.000Z",
  "pricingVersion": 1,
  "breakdown": {
    "base": 123,
    "lipSync": 0,
    "duration": 10,
    "visualBoard": 7
  },
  "warningCodes": []
}

quote is lightweight and does not inspect remote audio or image resources. Use it as an estimate-only calculator. preflight is the validated estimate that checks source media, reference images, optional characterImage, and optional SRT before a paid create. breakdown.duration is the billable duration in seconds. The quote field visualBoardImageProvider maps to create/preflight generation.visualBoard.imageProvider. For the default auto Visual Board policy, use 1 generated reference image for a 10-second Fast MV, 3 for 10-30 seconds, 4 for 30-90 seconds, 5 for 90-180 seconds, and up to 7 for longer supported requests.

Fast also accepts "quality": "high" in quote requests. High quality requires 720p or 1080p; if a create/preflight request omits resolution, OmnAPI uses 720p for high quality. lipSync=true follows the same minimum-resolution rule, is limited to effective sources of 180 seconds or less, and adds the lip-sync line item shown in breakdown.lipSync.

When the create/preflight request omits referenceImages, or explicitly sets generation.referenceStrategy="synthesize", add Visual Board quote fields so the estimate includes generated scene references. Add visualBoardReferenceImageCount when synthesis will use characterImage or caller references with reference-capable Visual Board providers such as gpt-image-2. Providers that do not use reference inputs ignore that count for pricing. When caller referenceImages are supplied and no synthesis is requested, Fast uses those references directly and the quote should omit Visual Board add-ons.

Premium V2 quotes replace the V1 quality and lipSync fields with managedVersion and performanceMode:

{
  "mode": "fast",
  "managedVersion": "premium-v2",
  "performanceMode": "sing_perform",
  "durationSec": 60,
  "resolution": "720p"
}

3. Preflight

curl -X POST https://api.omnapi.com/api/v1/mv/preflight \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "source": {
      "type": "audio",
      "audioUrl": "https://example.com/song.mp3",
      "durationSec": 10
    },
    "prompt": "cinematic night market performance video",
    "resolution": "540p",
    "aspectRatio": "9:16",
    "lipSync": false,
    "subtitles": false,
    "generation": {
      "style": "cinematic neon night",
      "visualBoard": {
        "imageProvider": "gpt-image-2"
      }
    },
    "maxCredits": 130
  }'

Preflight validates URL reachability, resolves duration, and returns preflightId. It does not create a task and does not charge credits.

For Premium V2, put the version and mode under generation. Singing modes require 1-2 ordered portraits; omit top-level lipSync and generation.quality:

{
  "resolution": "720p",
  "generation": {
    "managedVersion": "premium-v2",
    "performanceMode": "sing_perform",
    "lipReferenceImages": [
      "https://example.com/singer-1.png",
      "https://example.com/singer-2.png"
    ]
  }
}

For 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:

{
  "resolution": "720p",
  "lipSync": true,
  "characterImage": "https://example.com/front-face.png",
  "generation": {
    "quality": "high",
    "motionPreset": "lip_sync_closeup"
  }
}

generation.motionPreset is an OmnAPI-level prompt policy. Omit it to let OmnAPI match clear dance/high-energy direction and otherwise choose a safe preset for the effective references. Use stable_performance for safer motion, cinematic_light for gentle camera movement, dynamic_dance for wider rhythmic motion, and lip_sync_closeup for face-forward singing shots.

characterImage is an identity anchor. It does not require the person to appear in every shot, does not lock one outfit during synthesized Fast planning, and does not make a still image sing unless lipSync=true. Use referenceImages for locations, atmosphere, objects, palette, and composition anchors.

For subtitles, Fast defaults to generation.subtitleMode: "vidu". If the user does not upload an SRT, enable auto subtitle extraction with a budget guard:

{
  "subtitles": true,
  "subtitle": {
    "mode": "auto",
    "language": "auto",
    "maxCostUsdPerMin": 0.05,
    "fallback": "continue_without_subtitles"
  }
}

To keep subtitles in a foreground post-generation layer, choose "custom". OmnAPI limits each custom subtitle event to two lines and splits oversized cues across their original timing range. It uses srtUrl when supplied, otherwise it generates timing first through Subtitle Sync:

{
  "subtitles": true,
  "subtitle": {
    "mode": "auto",
    "maxCostUsdPerMin": 0.05
  },
  "generation": {
    "subtitleMode": "custom"
  }
}

4. Create

Send the same media and generation body used for preflight and add preflightId. When confirming the short-lived quote from step 2, also add its quoteId. quoteId and the create-time maxCredits authorization are excluded from preflight media matching; both are enforced atomically with task creation.

curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: mv-fast-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "preflightId": "4f78d90e-...",
    "quoteId": "019c...",
    "mode": "fast",
    "source": {
      "type": "audio",
      "audioUrl": "https://example.com/song.mp3",
      "durationSec": 10
    },
    "prompt": "cinematic night market performance video",
    "resolution": "540p",
    "aspectRatio": "9:16",
    "lipSync": false,
    "subtitles": false,
    "generation": {
      "style": "cinematic neon night",
      "visualBoard": {
        "imageProvider": "gpt-image-2"
      }
    },
    "maxCredits": 130
  }'

Response:

{
  "mode": "fast",
  "taskId": "cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "status": "PENDING",
  "creditsRequired": 130,
  "estimatedCompletionTime": "2026-07-12T13:40:00.000Z",
  "requestId": "bTFV3CIainrOq-cP0fvKK",
  "links": {
    "task": "/api/v1/tasks/cbc70993-69ba-46f8-9d57-b7195ed3377f",
    "stream": "/api/v1/tasks/cbc70993-69ba-46f8-9d57-b7195ed3377f/stream",
    "resource": "/api/v1/mv/cbc70993-69ba-46f8-9d57-b7195ed3377f",
    "final": null
  },
  "pricing": {
    "baseCredits": 130,
    "calculatedCredits": 130,
    "chargedCredits": 130,
    "adjustmentCredits": 0,
    "settlementRoundingCredits": 0,
    "settlementPolicyVersion": "whole-credit-v1",
    "billingIncrementCredits": 1,
    "source": "standard",
    "quoteVersion": 2
  },
  "product": {
    "type": "mv",
    "providerCode": "mv",
    "modelCode": "mv-managed-basic",
    "featureCode": "generate-managed-mv",
    "resourceId": "cbc70993-69ba-46f8-9d57-b7195ed3377f",
    "deliveryStatus": "rendering",
    "autoFinalize": true
  },
  "warningCodes": [],
  "mvId": "cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "pollUrl": "/api/v1/tasks/cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "viewUrl": "/api/v1/mv/cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "finalUrl": null,
  "autoFinalize": true,
  "deliveryStatus": "rendering"
}

5. Poll

curl https://api.omnapi.com/api/v1/tasks/task_01J... \
  -H "x-api-key: $OMNAPI_KEY"

Persist the stable mvId returned by create immediately. Poll taskId until terminal, and use mvId for MV reads, scene edits, and final URL refreshes. A non-null mvId is a resource identity, not a readiness signal; the product view may not be materialized immediately after create.

6. Download

curl https://api.omnapi.com/api/v1/mv/mv_01J.../final \
  -H "x-api-key: $OMNAPI_KEY"

The endpoint returns ready: false while processing or when the stored final no longer matches the current source composition. When ready, videoUrl is a fresh temporary URL; call the endpoint again when it expires. If ready=false, inspect staleReason, retryable, and actionHint; for example, actionHint="recompose_after_edit" means call POST /api/v1/mv/{mvId}/finalize to create a new final from the latest scene outputs.

7. Edit a scene

For new integrations, read the latest MV first and use its version as expectedVersion. Fast requests may omit expectedVersion for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Sending the version is recommended so concurrent edits can be detected with 409 MV_VERSION_CONFLICT.

curl https://api.omnapi.com/api/v1/mv/mv_01J... \
  -H "x-api-key: $OMNAPI_KEY"

For editor refreshes, append ?historyLimit=5. It returns each scene’s recent history plus the selected version and latest playable fallback when older. Omitting it preserves the original complete-history response.

MVView.scenes[].videoUrl and renderingHistory[].isSelected point to the selected playable scene output. Choose only renderingHistory[] entries where isSelectable=true; in-flight and failed attempts remain visible but cannot be selected. MVView.scenes[].sourceJob points to the latest edit/render attempt and is the field to inspect for in-flight or failed edits. When no manual selection exists, Fast falls back to the newest successful scene job for backward compatibility.

Before creating the paid edit task, quote the scene edit:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "step": "scene-edit",
    "mvId": "mv_01J...",
    "sceneIndex": 2
  }'

The scene-edit quote reads duration and resolution from saved Fast scene metadata. Do not send durationSec or resolution on Fast scene edits.

Edit one generated Fast scene by reusing the public render endpoint:

curl -X POST https://api.omnapi.com/api/v1/mv/mv_01J.../scenes/2/render \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 4,
    "prompt": "close-up singer shot, warm backlight, smoother camera motion",
    "referenceImages": [
      "https://cdn.example.com/references/singer-close-up.jpg"
    ]
  }'

Send prompt, referenceImages, or both. referenceImages accepts one to seven public image URLs and replaces the selected scene’s source images for this new rendering. Omit the field to preserve the current source images; do not send an empty array to clear them. Keep Studio render controls such as videoProvider, videoModel, and resolution for Studio MVs.

Poll the returned taskId:

curl https://api.omnapi.com/api/v1/tasks/{taskId} \
  -H "x-api-key: $OMNAPI_KEY"

When the edit task completes, read MVView again. If the edited scene’s sourceJob.status is RENDERING, wait and read again. If it is FAILED, retry the scene edit before recomposing; the previous playable scene.videoUrl may still remain available.

Optionally select any Fast scene version with isSelectable=true by passing its renderingHistory[].id:

curl -X PATCH https://api.omnapi.com/api/v1/mv/mv_01J.../scenes/2/select-rendering \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 5,
    "renderingId": "019f..."
  }'

Selecting a different rendering increments MVView.version and makes the final MP4 stale until recomposed. Selecting the already effective rendering is a no-op. Recompose the final with the refreshed version:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "step": "compose",
    "mvId": "mv_01J..."
  }'

The compose quote returns credits: 0 when the current final MP4 already matches the selected scene composition. Otherwise it returns the current compose charge.

curl -X POST https://api.omnapi.com/api/v1/mv/mv_01J.../finalize \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expectedVersion": 5 }'

Poll the finalize task, then refresh the final MP4 URL:

curl https://api.omnapi.com/api/v1/tasks/{finalizeTaskId} \
  -H "x-api-key: $OMNAPI_KEY"

curl https://api.omnapi.com/api/v1/mv/mv_01J.../final \
  -H "x-api-key: $OMNAPI_KEY"

If another write changed the MV first, OmnAPI returns 409 MV_VERSION_CONFLICT. Refresh MVView.version and retry the write.

Production notes

• Always use Idempotency-Key on create.
• Use preflight for reusable resource validation; use quote for calculators and budget previews.
• Inspect warningCodes on quote, preflight, create, task, and MVView responses. They are non-fatal diagnostics with suggested actions in the MV API guide.
• Set maxCredits to cap the final create-time charge. If the final quote is higher, the API returns 402 before creating a task.
• If you host your own audio and images, they must be public https URLs with bounded size metadata and range-readable content.
• Send expectedVersion from the latest MVView.version on new scene edit and explicit finalize/recompose integrations. Fast backward-compatible calls may omit it; Studio calls must include it.
• Prefer webhooks for long-running Fast MV jobs.
• Read MVView.generation.managedVersion and performanceMode to confirm the executed protocol. Premium V2 scene edit and compose are separate rollout capabilities; show those actions only when MVView.capabilities enables them.
• Technical FAILED or CANCELLED tasks are automatically refunded. Check MVView.billing, MVView.costSummary, and GET /api/v1/mv/{mvId}/operations for the settlement receipt. Cancel an active task through POST /api/v1/mv/{mvId}/operations/{taskId}/cancel. A pre-submit cancellation returns 200 and refunds the task. Submitted or outcome-unknown MV work returns 409 unless the Provider explicitly confirms remote cancellation; the task then remains active and is not refunded, so continue polling it. Subjective output-quality issues are handled by support policy, not automatic refunds.
• Final and scene media URLs are short-lived signed URLs (60 minutes by default). Refresh them by reading the MV again; do not persist them as permanent asset addresses.
• estimatedCompletionTime is a nullable, queue-aware estimate rather than a delivery guarantee. Keep polling the Task or use webhooks until terminal.

See Music Video (MV) API for Studio Beta and every field.