MV Creation and Input Reference

Preflight

Use POST /api/v1/mv/preflight when you want create-time checks before credits are charged. It accepts the same body as POST /api/v1/mv, validates reachable resources, resolves the final duration, and returns a validated create-time estimate. It does not create a task and does not charge credits.

For each new logical operation, set and save a fresh REQUEST_KEY once. Reuse it with the exact same route and body only when recovering that operation. Use a different saved key when trying a different example or export format.

export REQUEST_KEY="$(uuidgen)"

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

Response:

{
  "preflightId": "7f5a4b6a-...",
  "expiresAt": "2026-06-24T13:00:38.939Z",
  "quoteType": "validated_estimate",
  "mode": "fast",
  "creditsRequired": 130,
  "warningCodes": [],
  "checks": {
    "source": {
      "status": "ok",
      "kind": "audio",
      "url": "https://example.com/song.mp3",
      "durationSec": 10,
      "processingMode": "audio_url"
    },
    "referenceImages": [],
    "visualBoard": {
      "status": "ok",
      "kind": "visual-board",
      "durationSec": 10,
      "processingMode": "fast"
    }
  },
  "quote": {
    "credits": 130,
    "breakdown": {
      "base": 120,
      "duration": 10,
      "visualBoard": 10
    },
    "warningCodes": []
  }
}

Response fields:

Field	Type	Notes
`preflightId`	string	Reusable validation snapshot id. Include it on `POST /api/v1/mv` with the same body.
`expiresAt`	string	ISO timestamp when the snapshot expires.
`quoteType`	string	Currently `validated_estimate`. Final charged credits are resolved at create time.
`mode`	`"fast" \| "studio"`	Normalized mode.
`creditsRequired`	number	Validated create-time estimate.
`warningCodes`	string[]	Non-fatal behavior warnings.
`checks.source`	object	Resolved source check; includes status, source type, duration, range, and processing mode.
`checks.referenceImages`	object[]	Validation results for caller-supplied references. Empty when OmnAPI generates Visual Board references automatically.
`checks.characterImage`	object	Optional validation result for `characterImage`.
`checks.srtUrl`	object	Optional validation result for `srtUrl`.
`checks.visualBoard`	object	Optional Visual Board check when OmnAPI creates references automatically.
`quote`	object	Same shape as `POST /api/v1/mv/quote`: `credits`, `breakdown`, and `warningCodes`.

quote.credits is the final estimate. breakdown.duration is the billable duration in seconds, not a credit amount.

To create with the validated snapshot, send the same request body to POST /api/v1/mv and add preflightId. Media, source, and generation fields must match the preflight body. The create-time quoteId and maxCredits authorization may be added or changed without invalidating the validated media snapshot. Preflight snapshots expire after 10 minutes.

If you need a hard billing boundary, include maxCredits on the create body, or on both preflight and create when you also want preflight to reject above that ceiling. The API resolves the final quote immediately before creating the task; when that final quote is higher than maxCredits, no task is created and no credits are deducted.

For paid create requests, send an Idempotency-Key header so a network retry cannot create and charge a duplicate task.

Create

Fast

curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "source": { "type": "suno", "clipId": "484a67d4-..." },
    "title": "Sunny Morning",
    "prompt": "cinematic morning city story",
    "aspectRatio": "9:16",
    "resolution": "540p",
    "lipSync": false,
    "subtitles": true,
    "language": "auto"
  }'

Premium MV V2 uses the same endpoint with explicit generation fields and no V1-only lipSync or generation.quality fields:

{
  "mode": "fast",
  "source": {
    "type": "audio",
    "audioUrl": "https://example.com/song.mp3",
    "durationSec": 60
  },
  "resolution": "720p",
  "generation": {
    "managedVersion": "premium-v2",
    "performanceMode": "sing_perform",
    "lipReferenceImages": [
      "https://example.com/singer-1.png"
    ]
  }
}

Studio Beta

curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "studio",
    "source": {
      "type": "audio",
      "audioUrl": "https://example.com/song.mp3",
      "durationSec": 30
    },
    "title": "Pocket Change",
    "prompt": "cinematic music video, warm close-ups, rhythm-aware editing",
    "aspectRatio": "9:16",
    "resolution": "540p",
    "maxCredits": 2000,
    "generation": {
      "imageProvider": "gpt-image-2",
      "videoProvider": "p-video",
      "videoModel": "p-video"
    }
  }'

Response envelope:

Expand the complete JSON example

{
  "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"
}

Studio create returns the same envelope with mode: "studio", autoFinalize: false, and deliveryStatus: "drafting".

The create response assigns the canonical mvId immediately. For newly created resources it equals taskId, so clients can persist one stable resource identity before generation finishes. A non-null mvId is not a readiness signal, and the MV product view may not be materialized immediately. Poll GET /api/v1/tasks/{taskId} for execution and read GET /api/v1/mv/{mvId} for product state.

estimatedCompletionTime is a best-effort backend estimate based on expected recent delivery times and current availability. It may be null when no reliable duration signal exists and is not a delivery guarantee. Keep polling the Task or consume webhooks until a terminal status.

Input fields

Set these shared fields for any mode. Select a mode below for reference images, resolution and lip-sync requirements.

Field	Type	Notes
`mode`	`"fast" \| "studio"`	Required. Studio is public Beta.
`source`	object	Required. See Source variants.
`prompt`	string	At most 3000 chars. Style hint plus scene direction.
`aspectRatio`	enum	`16:9`, `9:16` (default), `1:1`, `4:3`, `3:4`.
`subtitles`	bool	Burn subtitles into the final MP4 when timing exists. See Subtitle behavior.
`subtitle`	object	Subtitle automation policy. Use `mode:"auto"` to generate timing when `srtUrl` is absent, `mode:"provided"` to require caller timing, or `mode:"off"` to disable subtitles. Optional fields: `language`, `quality`, `required`, `fallback`, `maxCostUsdPerMin`.
`subtitleColor`	string	Hex, default `#FFFFFF`.
`language`	`"auto" \| "en" \| "zh"`	Default `"auto"`.
`srtUrl`	string	Explicit SRT override. Public http(s) URL only, at most 4MB.
`title`	string	At most 200 chars.
`quoteId`	string	Optional short-lived create quote id. It is consumed when the task is created and credits are deducted.
`maxCredits`	number	Optional create-time spend guard. If the final quote exceeds this value, create returns `402 INSUFFICIENT_CREDITS` before deducting credits.
`preflightId`	string	Optional id from `POST /api/v1/mv/preflight`. Keep media and generation inputs identical; create-time `quoteId` and `maxCredits` may be added or changed. See Preflight.
`generation`	object	Optional mode-specific options. See Mode configs.
`config`	object	Standard task request config: `priority`, `tags`, `metadata`, `webhookUrl`.

Field	When and how to use it
`mode` / `generation.managedVersion`	Use `fast`; version is `oneclick-v1` by default. Effective audio duration: 10–600 seconds.
`referenceImages`	Up to 7 public image URLs, each at most 12MB; omit for generated Visual Board references.
`resolution`	`540p` by default; `720p` or `1080p` required for lip-sync and high quality.
`lipSync` / `characterImage`	Set `lipSync: true` and supply a clear singer portrait for lip-sync; image at most 12MB.
`generation.quality`	`standard` or `high`; V1 only.

Field	When and how to use it
`mode` / `generation.managedVersion`	Use `fast` and explicitly choose `premium-v2`. Effective audio duration: 10–300 seconds.
`referenceImages`	Up to 6 public image URLs, each at most 12MB. Omit for generated Visual Board references.
`resolution`	Fixed at `720p`.
`generation.performanceMode`	Required: `sing`, `sing_perform`, `perform`, or `dance`.
`generation.lipReferenceImages`	Singing modes use 1–2 distinct, ordered singer portraits. Omit to use `characterImage` as the single Singer 1 fallback.
`lipSync` / `generation.quality`	Omit both: V2 rejects these V1 fields.

See the Premium V2 guide for mode-specific media rules.

Field	When and how to use it
`mode`	Use `studio`. Effective audio duration: 10–300 seconds.
`referenceImages`	Public image URLs for storyboard continuity, each at most 12MB.
`lipSync`	Storyboard guidance; it does not select a managed Fast singing mode.
`generation`	Choose Studio image/video options under Studio generation.

Studio creates a draft. Render scenes and finalize it with the editing workflow.

Source variants

{
  "type": "suno",
  "clipId": "<suno-clip-id>",
  "range": {
    "startSec": 12,
    "endSec": 72
  },
  "lyrics": "optional override"
}

{
  "type": "audio",
  "audioUrl": "https://example.com/song.mp3",
  "durationSec": 60,
  "range": {
    "startSec": 0,
    "endSec": 45
  },
  "lyrics": "optional plain text"
}

Host audio in your own publicly reachable HTTPS environment and pass audioUrl. Inline base64 audio and direct file uploads are not part of the public API.

OmnAPI validates external audio URLs before create/preflight can succeed. The URL must expose bounded size metadata, must not resolve to a private or local network address, must stay within the audio size/time limits, and must yield a readable duration. The default remote audio cap is 128MB. Effective duration must be 10-600 seconds for OneClick V1 Fast, 10-300 seconds for Premium MV V2, or 10-300 seconds for Studio.

Source field	Applies to	Notes
`clipId`	`suno`	Required Suno clip id.
`audioUrl`	`audio`	Required public http(s) audio URL for `audio` sources. Suno sources do not accept audio fallbacks in the public API.
`durationSec`	`audio`	Optional client duration hint. OmnAPI validates external audio and rejects material disagreement.
`range.startSec`	`suno`, `audio`	Optional segment start, seconds from original source.
`range.endSec`	`suno`, `audio`	Optional segment end; must be greater than `startSec` and produce a valid effective duration for the selected Fast version or Studio.
`lyrics`	`suno`, `audio`	Optional plain-text lyrics/context, at most 5000 chars. For `audio`, this guides visual planning. Exact subtitle timing comes from `srtUrl`, Suno timing, or `subtitle.mode="auto"`.

Producer music results can be sent to MV as ordinary public audio URLs. Pass the audio resource URL with source.type="audio" and keep any lyrics as visual context unless you also provide srtUrl or let OmnAPI generate timing with subtitle.mode="auto".

Mode configs

generation is MV-specific and separate from config, which is the standard task envelope.

Fast generation

{
  "generation": {
    "style": "cinematic neon night",
    "quality": "standard",
    "referenceStrategy": "direct",
    "subtitleMode": "custom",
    "creativeMode": "performance",
    "promptMode": "verbatim",
    "visualBoard": {
      "imageProvider": "gpt-image-2",
      "preset": "detail"
    }
  }
}

Field	Notes
`managedVersion`	`oneclick-v1` (default) or `premium-v2`. Existing clients stay on V1 unless they opt in explicitly.
`performanceMode`	Premium V2 only and required there: `sing`, `sing_perform`, `perform`, or `dance`.
`lipReferenceImages`	Premium V2 singing modes only: 1-2 ordered, distinct public singer portraits. `characterImage` is the single-portrait fallback when this field is omitted.
`style`	Fixed visual style hint sent as the Fast visual style lever alongside the top-level `prompt`.
`quality`	OneClick V1 only: `standard` (default) or `high`. High quality is available only at `720p` and `1080p`; if `resolution` is omitted, Fast uses `720p`.
`referenceStrategy`	`direct` or `synthesize`. Fast defaults to `direct` when `referenceImages` are supplied and `synthesize` when they are omitted. Use `synthesize` to generate unified Visual Board scene references before managed generation.
`subtitleMode`	`vidu` (API default) or `custom`. `vidu` lets the managed generation service compose subtitles. `custom` renders a foreground layer after generation, limits each cue to two lines, and splits oversized cues over time. When `srtUrl` is absent, audio sources default to `subtitle.mode="auto"` and use Subtitle Sync to create timing first.
`motionPreset`	Optional OmnAPI-level prompt policy. Omit it for automatic selection: lip-sync requests use close-up guidance, clear dance/high-energy direction uses wider rhythmic motion, synthesized references use cinematic motion, and direct references retain stable performance behavior. Explicit values remain `stable_performance`, `cinematic_light`, `dynamic_dance`, and `lip_sync_closeup`.
`creativeMode`	Creative intent: `auto`, `lyrics_story`, `prompt_story`, `mood_visual`, or `performance`. Omit for `auto`.
`promptMode`	Prompt handling: `auto`, `verbatim`, or `creative_brief`. Use `verbatim` to preserve the caller prompt or `creative_brief` to compile it into a managed generation brief.
`visualBoard.imageProvider`	Optional image provider for OmnAPI-generated Visual Board references when `referenceImages` is omitted. Use `gpt-image-2`, `p-image`, or `viduq2`. This maps to `/quote`’s flat `visualBoardImageProvider`.
`visualBoard.preset`	Visual Board policy: `auto`, `speed`, `detail`, or `off`. `off` disables generated Visual Board references.

generation.motionPreset is an OmnAPI prompt policy; omitting it enables the automatic selection described above without adding an auto enum value to the public API. generation.creativeMode, generation.promptMode, and generation.visualBoard.preset use the exact enums in the table above.

Premium V2 requires performanceMode, uses 720p, and accepts effective durations up to 300 seconds. sing and sing_perform require singer portraits; perform and dance use caller referenceImages or an automatically generated Visual Board. Premium V2 rejects top-level lipSync and generation.quality instead of silently translating them. It does not fall back to OneClick V1.

For OneClick V1 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. Premium V2 singing uses the separately documented generation.lipReferenceImages list.

The three Premium V2 selectors are generation.managedVersion, generation.performanceMode, and generation.lipReferenceImages.

When referenceImages is omitted, OmnAPI generates Visual Board references and uses an automatic count based on duration: 1 image for up to 10 seconds, 3 for 10-30 seconds, 4 for 30-90 seconds, 5 for 90-180 seconds, and up to 7 for longer supported requests. The generated pack uses distinct roles such as character identity, world/style, motif, and climax. World/style and motif references may intentionally omit the recurring character so the managed MV is not forced into performer shots. Use generation.visualBoard.imageProvider to choose the image option for generated Visual Board references. If a Fast request includes characterImage and no referenceImages, the character image is offered to reference-capable Visual Board image options. When the selected option or fallback path cannot use reference inputs, the request still proceeds and returns MV_CHARACTER_IMAGE_REFERENCE_IGNORED in warningCodes. The exact Visual Board strategy may evolve without changing the request shape.

When characterImage and referenceImages are both present, Fast keeps the caller references as the managed generation references by default. If you need OmnAPI to create a more unified set of scene references first, set generation.referenceStrategy="synthesize". In that synthesis path, characterImage is used as the identity reference for capable image providers, and at most six caller references are used as secondary scene/style references. If more than six secondary references are supplied, the request still proceeds and returns MV_REFERENCE_IMAGES_TRUNCATED_FOR_CHARACTER in warningCodes.

Studio generation

{
  "generation": {
    "imageProvider": "gpt-image-2",
    "videoProvider": "p-video",
    "videoModel": "p-video"
  }
}

Field	Notes
`imageProvider`	Scene-still generation option. Public values include `gpt-image-2`, `viduq2`, and `p-image` when enabled.
`videoProvider`	Scene-video generation option used when rendering or re-rendering scenes.
`videoModel`	Rendering model code, for example `p-video` or `viduq3-turbo` when enabled.

Use the top-level prompt for Studio visual style and scene direction. Available options may change as the public catalog evolves. The API accepts the documented option codes directly.

Subtitle behavior

Mode	Source	`generation.subtitleMode`	`subtitles=true`	`srtUrl`	Behavior
Fast	suno	`vidu`	yes	—	OmnAPI converts the Suno timeline to subtitles when available, then lets the managed generation service render them.
Fast	suno	`custom`	yes	—	OmnAPI converts the Suno timeline when available and renders subtitles after generation. If no usable timing exists, create/preflight fails with `MV_SUBTITLE_TIMING_REQUIRED`.
Fast	suno	any	yes	yes	Caller-supplied SRT wins.
Fast	audio	`vidu`	yes	yes	Caller-supplied SRT is passed to the managed generation service.
Fast	audio	`custom`	yes	yes	Caller-supplied SRT is used by OmnAPI for post-generation subtitle rendering.
Fast	audio	`vidu`	yes	—	Default: OmnAPI generates SRT with Subtitle Sync, then passes it to the managed generation service. With `subtitle.mode="provided"`, the provider may infer timing and the task includes `MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED`.
Fast	audio	`custom`	yes	—	Default: OmnAPI generates timing with Subtitle Sync, renders subtitles after generation, and returns `MV_AUTO_SUBTITLE_GENERATED`. With `subtitle.mode="provided"`, create/preflight fails with `MV_SUBTITLE_TIMING_REQUIRED`.
Studio	audio	Not applicable	yes	—	Default: OmnAPI generates line timing with Subtitle Sync for storyboard/final subtitle burn-in. With `subtitle.mode="provided"`, subtitles are disabled and the task includes `MV_SUBTITLE_DISABLED_NO_TIMELINE`.
any	any	any	false	any	No subtitles.

Custom Fast subtitles are placed in a post-generation foreground layer. Each event is limited to two lines; longer text is split into consecutive events within the original cue timing rather than stacked into three or more lines.

subtitle.fallback controls ASR failure behavior for auto subtitles. The default is fail. Use "continue_without_subtitles" when an MV should still finish even if lyrics cannot be extracted from the audio.