Skip to content
OmnAPI Docs

AI Music Video Fast Quickstart

MV Fast creates a finished music video through OmnAPI’s managed one-click workflow. Use this flow for production calls:

  1. POST /api/v1/mv/quote for a quick cost estimate.
  2. POST /api/v1/mv/preflight to validate public media URLs and get a reusable create-time estimate.
  3. POST /api/v1/mv with mode: "fast" and an Idempotency-Key.
  4. Poll GET /api/v1/tasks/{taskId}.
  5. GET /api/v1/mv/{mvId}/final for a fresh MP4 URL.
  6. 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. Quote

Section titled “1. Quote”
Terminal window
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": 2
  }'

Response:

{
  "credits": 134,
  "breakdown": {
    "base": 120,
    "lipSync": 0,
    "duration": 10,
    "visualBoard": 14
  },
  "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.

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.

2. Preflight

Section titled “2. Preflight”
Terminal window
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 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. Use stable_performance for safer default motion, cinematic_light for gentle camera movement, dynamic_dance for wider rhythmic motion, and lip_sync_closeup for face-forward singing shots.

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 have OmnAPI render subtitles after the managed video is generated, choose "custom". OmnAPI uses srtUrl when supplied, otherwise it generates timing first through Subtitle Sync:

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

3. Create

Section titled “3. Create”

Send the same body used for preflight and add preflightId.

Terminal window
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-...",
    "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": null,
  "requestId": "bTFV3CIainrOq-cP0fvKK",
  "links": {
    "task": "/api/v1/tasks/cbc70993-69ba-46f8-9d57-b7195ed3377f",
    "resource": "/api/v1/mv/cbc70993-69ba-46f8-9d57-b7195ed3377f",
    "final": null
  },
  "pricing": {
    "baseCredits": 130,
    "chargedCredits": 130,
    "adjustmentCredits": 0,
    "source": "standard",
    "quoteVersion": 1
  },
  "product": {
    "type": "mv",
    "resourceId": null,
    "deliveryStatus": "rendering",
    "autoFinalize": true
  },
  "warningCodes": [],
  "mvId": null,
  "pollUrl": "/api/v1/tasks/cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "viewUrl": "/api/v1/mv/cbc70993-69ba-46f8-9d57-b7195ed3377f",
  "finalUrl": null,
  "autoFinalize": true,
  "deliveryStatus": "rendering"
}

4. Poll

Section titled “4. Poll”
Terminal window
curl https://api.omnapi.com/api/v1/tasks/task_01J... \
  -H "x-api-key: $OMNAPI_KEY"

When the task is COMPLETED, read the mvId from the task output and use it for MV reads, scene edits, and final URL refreshes.

5. Download

Section titled “5. Download”
Terminal window
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.

6. Edit a scene

Section titled “6. 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.

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

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:

Terminal window
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:

Terminal window
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"
  }'

Use prompt for Fast scene edits. Keep Studio render controls such as videoProvider, videoModel, and resolution for Studio MVs.

Poll the returned taskId:

Terminal window
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:

Terminal window
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:

Terminal window
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.

Terminal window
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:

Terminal window
curl https://api.omnapi.com/api/v1/tasks/{finalizeTaskId} \
  -H "x-api-key: $OMNAPI_KEY"
Terminal window
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

Section titled “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.

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