Omn quickstart — API v2

Creative modes and inputs · Pricing

Before you start

Use /api/v2/mv at https://api.omnapi.com with an x-api-key. Check /api/v2/mv/capabilities and the requested combination, then preflight the actual media before purchasing. Use the returned preflightId, a saved Idempotency-Key, and your maxCredits limit. See API availability.

Omn creates a music video from a song, a creative direction and optional reference media. This guide uses API v2 with the Omn V1 generation engine. The API version identifies the request format; the engine version identifies generation.

Use an API key with task:create and task:read, and purchased credits. The example selects singing at 1080p with required automatic captions. Check the returned capability and preflight price before paying. Choose creative.mode and output.resolution. There is no engine, purchase-profile, quality-tier or lip-sync selector.

1. Check the requested capability

Read GET /api/v2/mv/capabilities, then POST /api/v2/mv/capabilities/check with your creative/output options and durationSec. Static support and current readiness are separate; preflight validates the actual media.

2. Save and preflight the request

Replace the example media URL with your publicly reachable audio. Authentication uses x-api-key: $OMNAPI_KEY. Save this body before calling POST /api/v2/mv/preflight:

{
  "source": {
    "type": "audio_url",
    "url": "https://example.com/song.wav",
    "range": { "startSec": 0, "endSec": 40 }
  },
  "creative": {
    "mode": "sing",
    "brief": "A singer walks through a rain-lit city.",
    "style": "Cinematic realism, blue and violet light"
  },
  "output": { "resolution": "1080p", "aspectRatio": "16:9" },
  "captions": { "mode": "auto", "required": true }
}

Preflight does not debit credits. Save preflightId, expiresAt and creditsRequired. Changing any creative or output option requires a new preflight.

3. Approve the amount and create once

Call POST /api/v2/mv with an Idempotency-Key generated and persisted before submission. Use the exact quoted amount as maxCredits. An optional quoteId replaces the quote saved at preflight; an explicit maxCredits without quoteId replaces that saved quote as the authorization ceiling. If both are supplied, the lower valid ceiling applies.

{ "preflightId": "REPLACE_WITH_PREFLIGHT_ID", "maxCredits": 800 }

The amount above is illustrative. The preflight is bound to the account and API key; an expired preflight must be refreshed. A successful receipt contains taskId and the MV resource information. Persist the receipt. After a lost response, replay the same body and idempotency key; do not create another purchase.

4. Wait for execution and settlement

The shared Task API remains at /api/v1/tasks, including for videos created through API v2. This is not a change to the MV’s API version.

Poll GET /api/v1/tasks/{taskId} until COMPLETED, FAILED or CANCELLED. Read the MV and its operations to reconcile charges/refunds. human_review_required and needs_revision are quality observations, not task failure states.

5. Read and save the final video

Read GET /api/v2/mv/{mvId} and GET /api/v2/mv/{mvId}/final. An accepted task is not a finished video. Do not send your API key when downloading media URLs.

Short clips and recovery

New full videos require at least 10 effective seconds. Use source.range to select a shorter portion of a song. Cancellation is POST /api/v2/mv/{mvId}/operations/{taskId}/cancel; refund eligibility depends on work already purchased. Read refunded and net credits instead of assuming cancellation is always free.

Next steps

Modes and materials · Prices and settlement · Availability · Editing

Already integrated with API v1? Keep existing resources and retries on that API; use the API v1 compatibility guide.