Skip to content
OmnAPI Docs

Create Your First Fast Music Video

Quickstart

Create a short video from an audio URL you control. For your first run, use a 10-second clip and the default OneClick V1 mode. Keep one idempotency key and save every receipt. See complete input options after the first successful result.

Managed versionDurationResolution
OneClick V1, default10–600 seconds, including lip-sync540p / 720p / 1080p; lip-sync and high quality require at least 720p
OneClick V210–300 seconds720p; select a performance mode explicitly

1. Check availability and price

Section titled “1. Check availability and price”
Terminal window
curl https://api.omnapi.com/api/v1/mv/fast/availability \
  -H "x-api-key: $OMNAPI_KEY"

Only submit paid work when availability allows it. Honor retryAfterSec on a temporary rejection. For OneClick V2, query with ?managedVersion=premium-v2.

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}'

Read credits as the estimated price. breakdown.duration is seconds, not credits. Quotes are free and do not validate the remote media. Choose a maxCredits ceiling you are willing to authorize before creation. If GET /api/v1/mv/capabilities reports native.defaultEngine.enabled: true, a request without generation.engineVersion may run on the Omn V1 pilot at its price; preflight shows the price that applies. See the default engine rules.

2. Validate your media

Section titled “2. Validate your media”

Replace the example audio URL with your own publicly reachable URL. Keep it available throughout processing. Preflight validates media and returns a reusable preflightId valid for 10 minutes.

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://media.example.com/ten-seconds.mp3","durationSec":10},
    "prompt":"warm coastal indie pop video, gentle camera motion",
    "resolution":"540p",
    "subtitles":false
  }'

Read the validated quote and any warning codes before proceeding. If you want preflight to enforce a budget ceiling too, include maxCredits in that request.

3. Create once

Section titled “3. Create once”

Use the same media and generation inputs. Add the returned preflightId and a reviewed maxCredits; the value 100 below is illustrative, not a quoted price. Adding or changing quoteId/maxCredits does not invalidate media matching.

Terminal window
# Run once for a new logical MV and save this value for any retry.
export MV_REQUEST_KEY="$(uuidgen)"
curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $MV_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode":"fast",
    "source":{"type":"audio","audioUrl":"https://media.example.com/ten-seconds.mp3","durationSec":10},
    "prompt":"warm coastal indie pop video, gentle camera motion",
    "resolution":"540p",
    "subtitles":false,
    "preflightId":"replace-with-your-preflight-id",
    "maxCredits":100
  }'

Save taskId, mvId, viewUrl and creditsRequired. A create-time quote above your budget is rejected before the task is created. After an uncertain network outcome, retain the exact request and key; do not create another MV to recover it.

4. Poll and download

Section titled “4. Poll and download”

Set TASK_ID and MV_ID to the actual values from your receipt.

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

Poll with bounded backoff. Stop on COMPLETED, FAILED or CANCELLED. On failure, inspect the task error and settled credits.

Fast creation normally finalizes automatically. When complete, obtain a fresh URL:

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

Read ready and videoUrl. If ready is false, use staleReason, retryable and actionHint; do not repeatedly pay to finalize a video that is still processing. Download the returned media URL without your API key and before its expiry. URL expiry and asset retention are different deadlines.

Next workflows

Section titled “Next workflows”