AI Music Video API

The public MV API turns a Suno clip or caller-hosted public audio URL into a music video. It exposes two modes:

mode	Best for
"fast"	Finished MV from a public audio source or Suno clip.
"studio"	Beta storyboard workflow with scene stills, per-scene renders, selected-scene finalization, and character anchors.

Authentication uses the same x-api-key header as every other OmnAPI surface.

Note

MV can be expensive. Always preview with POST /api/v1/mv/quote or run POST /api/v1/mv/preflight before committing credits.

---

Commercial Boundaries

Fast MV is the production path. OmnAPI owns input validation, task creation, provider orchestration, polling/callback recovery, final MP4 storage, final URL refresh, webhooks, and automatic credit settlement. Generation quality and wall-clock time still depend on the managed video provider and the validity of the caller’s media inputs.

Studio is public Beta. Use it when you want a storyboard/editor workflow with human review between steps; do not treat it as the same one-click delivery commitment as Fast.

Fast technical failures are automatically refunded when the paid task reaches FAILED or CANCELLED. Input validation failures from quote, preflight, or maxCredits happen before credits are charged. Subjective quality issues are not automatically refunded.

Note

Upgrading an integration that used the MV API before July 10, 2026? Review the MV migration notes for compatibility, enum, signed URL, and historical billing guidance.

---

Endpoints

Supported rendering options are selected through the documented request fields below. Use the option codes listed in this guide and the Interactive Reference.

Method	Path	Description
GET	/api/v1/mv/fast/availability	Read current Fast MV delivery health: available, degraded, unknown, or unavailable
POST	/api/v1/mv/quote	Fast or Studio pricing preview
POST	/api/v1/mv/preflight	Validate create inputs and return a reusable create-time estimate without charging
POST	/api/v1/mv	Create Fast or Studio MV task
GET	/api/v1/mv	List the caller’s Fast and Studio MV history with cursor pagination
GET	/api/v1/mv/{mvId}	Read unified MVView; optional historyLimit=1..50 returns a recent per-scene window plus selected and latest playable Fast fallback entries
GET	/api/v1/mv/{mvId}/operations	Read the commercial operation and credit ledger
POST	/api/v1/mv/{mvId}/operations/{taskId}/cancel	Cancel an active paid operation and refund eligible charged credits
PATCH	/api/v1/mv/{mvId}/scenes/{sceneIndex}	Studio Beta: persist scene prompt, timing, lyric-window, framing, lighting, or mood edits
POST	/api/v1/mv/{mvId}/scenes/{sceneIndex}/regenerate-image	Studio Beta: regenerate one scene still
POST	/api/v1/mv/{mvId}/scenes/{sceneIndex}/render	Cross-mode scene render: Studio renders a candidate video; Fast edits/re-renders a generated scene
POST	/api/v1/mv/{mvId}/scenes/render-batch	Studio Beta: render 1-30 current scene versions in one charged task
PATCH	/api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering	Choose the scene rendering used for finalize. Fast selects a managed scene job from renderingHistory; Studio selects a storyboard rendering.
POST	/api/v1/mv/{mvId}/lock-character	Studio Beta: attach or replace the character anchor
POST	/api/v1/mv/{mvId}/finalize	Write/recover/recompose the final MP4; Fast normally auto-finalizes during create
GET	/api/v1/mv/{mvId}/final	Refresh the current final MP4 URL and return stale/failure diagnostics
DELETE	/api/v1/mv/{mvId}	Delete the MV and known media assets while retaining records required for financial reconciliation

---

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.

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: mv-create-fast-01" \
  -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"
  }'

Studio Beta

curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: mv-create-studio-01" \
  -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:

{
  "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",
    "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": "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 operation duration, destination queue depth, and worker concurrency. 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

Field	Type	Notes
mode	"fast" | "studio"	Required. Studio is public Beta.
source	object	Required. See Source variants.
referenceImages	string[]	Public http(s) image URLs. Each remote object must expose bounded size metadata and be at most 12MB. Fast accepts up to 7 caller scene/style references and uses them as the managed generation references by default, even when characterImage is supplied. Set generation.referenceStrategy="synthesize" when you want OmnAPI to generate unified Visual Board scene references first. Studio uses references for storyboard visual continuity. If omitted or empty, OmnAPI automatically creates Visual Board references.
characterImage	string	Public http(s) image URL, at most 12MB. Fast uses it as the managed lip-sync reference when lipSync=true. When Visual Board synthesis runs, OmnAPI can also offer it as the singer/protagonist identity reference for image options that support reference inputs. Studio stores it as the character anchor and passes it to reference-capable scene image models.
prompt	string	At most 3000 chars. Style hint plus scene direction.
aspectRatio	enum	16:9, 9:16 (default), 1:1, 4:3, 3:4.
resolution	enum	540p (default), 720p, 1080p. Fast requests that omit resolution use 720p when lipSync=true or generation.quality="high". Explicit 540p is rejected for those two cases.
lipSync	bool	Fast requests managed lip-sync rendering. Fast lip-sync requires 720p or 1080p and is limited to effective sources of 180 seconds or less. Studio treats it as storyboard guidance for visible-mouth singing shots.
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 atomically with task creation and direct debit.
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. The create body must match the preflight body exactly, excluding this field.
generation	object	Optional mode-specific options. See Mode configs.
config	object	Standard task request config: priority, tags, metadata, webhookUrl.

---

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-300 seconds.

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 10-300s effective duration.
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": "vidu",
    "motionPreset": "stable_performance",
    "visualBoard": {
      "imageProvider": "gpt-image-2"
    }
  }
}

Field	Notes
style	Fixed visual style hint sent as the Fast visual style lever alongside the top-level prompt.
quality	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 (default) or custom. vidu lets the managed generation service render subtitles. custom asks OmnAPI to render subtitles after generation. When srtUrl is absent, audio sources default to subtitle.mode="auto" and use Subtitle Sync to create the timing first.
motionPreset	Optional OmnAPI-level prompt policy (generation.motionPreset). Values are stable_performance (default), cinematic_light, dynamic_dance, and lip_sync_closeup; it shapes the prompt and generated Visual Board frames so the managed engine gets safer motion instructions.
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.

For Fast 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. Public Fast requests use characterImage rather than a separate lip reference URL.

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

---

Fast Availability

Check Fast delivery health before submitting production batches:

curl https://api.omnapi.com/api/v1/mv/fast/availability \
  -H "x-api-key: sk_live_..."

Response:

{
  "status": "available",
  "gateEnabled": false,
  "checkedAt": "2026-07-09T12:00:00.000Z",
  "windowMinutes": 120,
  "retryAfterSec": null,
  "message": "Fast MV is accepting production requests.",
  "guidance": "Use quote for estimates, preflight before paid creates, and webhooks for long-running jobs.",
  "metrics": {
    "projectCount": 12,
    "terminalCount": 10,
    "readyCount": 9,
    "failedCount": 1,
    "processingCount": 2,
    "staleProcessingCount": 0,
    "readyRate": 90,
    "failureRate": 10,
    "avgTerminalDurationSec": 214.5
  }
}

gateEnabled is the operator-controlled paid-create gate and defaults to false. Health diagnostics remain active when the gate is disabled, but unknown and unavailable do not block paid creates; responses carry delivery warnings instead. When gateEnabled=true, unknown or unavailable fails before charging with 503 MV_PROVIDER_UNAVAILABLE; use retryAfterSec as a backoff hint. degraded requests remain accepted and include MV_FAST_PROVIDER_DEGRADED in warningCodes.

---

Read

List the caller’s current Fast and Studio projects before loading a full MVView:

curl -H "x-api-key: sk_live_..." \
  "https://api.omnapi.com/api/v1/mv?limit=20&cursor=2026-07-10T12:00:00.000Z"

limit is clamped to 1–50 and defaults to 20. Results are newest first and exclude deleted or archived MVs. Pass nextCursor to the next request while hasMore=true. List items contain summary state only; use the item mvId to read scenes, current media links, capabilities, billing, and failure details.

Read one MV:

curl -H "x-api-key: sk_live_..." \
  https://api.omnapi.com/api/v1/mv/{mvId}

Returns MVView. Important fields:

type MVView = {
  mvId: string;
  mode: "fast" | "studio";
  status:
    | "PENDING"
    | "GENERATING"
    | "READY"
    | "RENDERING"
    | "FINALIZING"
    | "COMPLETED"
    | "EDITING"
    | "ACTION_REQUIRED"
    | "FAILED"
    | "ARCHIVED"
    | "DELETED";
  version: number;
  source: {
    type: "suno" | "audio";
    clipId?: string | null;
    audioUrl?: string | null;
    sourceDurationSec?: number | null;
    durationSec: number;
    range?: { startSec?: number; endSec?: number } | null;
    lyrics?: string | null;
  };
  prompt: string | null;
  title: string | null;
  generation: {
    aspectRatio: string;
    resolution: string;
    lipSync: boolean;
    subtitles: boolean;
    subtitleColor: string;
    language: string;
    videoProvider?: string | null;
    videoModel?: string | null;
  };
  characterAnchor: { url: string } | null;
  referenceImages: Array<{ url: string; source: "user" | "auto_visual_board" }>;
  scenes: MVSceneView[];
  finalMv: MVFinalView | null;
  finalUrl: string | null;
  sourceVersion: number;
  finalizedVersion: number | null;
  finalizationRequired: boolean;
  staleReason:
    | "missing_final"
    | "final_processing"
    | "final_expired"
    | "source_rendering"
    | "source_failed"
    | "source_changed"
    | "composition_unknown"
    | "url_unavailable"
    | null;
  warningCodes: string[];
  failureReason: { code: string | null; message: string | null } | null;
  failureCategory:
    | "customer_input"
    | "provider_unavailable"
    | "provider_failed"
    | "provider_timeout"
    | "platform_storage_failed"
    | "subtitle_failed"
    | "finalization_failed"
    | "unknown"
    | null;
  retryable: boolean;
  refundable: boolean;
  customerAction: "retry" | "fix_input" | "contact_support" | "wait" | null;
  billing: {
    creditsReserved: number;
    creditsCharged: number | null;
    refundedCredits: number;
    settlementStatus: "PENDING" | "CHARGED" | "REFUNDED";
    refundReason: string | null;
  } | null;
  costSummary: {
    authorizedCredits: number;
    chargedCredits: number;
    refundedCredits: number;
    netSpentCredits: number;
    operationCount: number;
  };
  capabilities: {
    canEditScenePrompt: boolean;
    canEditSceneImage: boolean;
    canEditSceneFraming: boolean;
    canTriggerRender: boolean;
    canRenderScene: boolean;
    canSelectRendering: boolean;
    canRegenerateSceneImage: boolean;
    canFinalize: boolean;
    canLockCharacter: boolean;
    canRefreshFinalUrl: boolean;
    canRetryFinalize: boolean;
    canRecompose: boolean;
    canEditManagedScene: boolean;
    requiresFinalize: boolean;
    canUseCurrentFinal: boolean;
    finalizeAction?: "finalize" | "recompose" | "retry_finalize" | null;
  };
};

Fast scene state separates the playable preview from the latest edit attempt:

type MVSceneView = {
  index: number;
  videoUrl: string | null; // selected playable scene output
  status:
    "READY" | "IMAGE_READY" | "RENDERING" | "FAILED" | "PLANNED" | "STALE";
  renderingHistory: Array<{
    id: string;
    videoUrl: string | null;
    durationSec: number;
    isSelected: boolean;
    isSelectable: boolean;
    createdAt: string;
  }>;
  sourceJob?: {
    status:
      "READY" | "IMAGE_READY" | "RENDERING" | "FAILED" | "PLANNED" | "STALE";
    isComposable: boolean;
    errorCode: string | null;
    errorMessage: string | null;
  } | null;
};

For Fast MVs, scene.videoUrl and renderingHistory[].isSelected point to the scene version that will be used by the next final recomposition. Choose only history entries where isSelectable=true; processing or failed entries remain visible with a durability warning; historical successful jobs remain selectable by provider job id for compatibility, but their preview URL may expire. When no manual selection exists, OmnAPI falls back to the newest successful scene job for backward compatibility. scene.sourceJob describes the newest edit/render attempt for that scene, even if a previous successful version remains selected and playable.

Interactive editors should request GET /api/v1/mv/{mvId}?historyLimit=5 (or another value from 1 to 50) to request a smaller recent window and reduce signed-URL work. The window applies per scene; selected versions and the latest playable Fast fallback are retained even when older. Omitting the parameter preserves the original complete-history response for existing clients.

Scene images, scene videos, character anchors, and current finalMv.videoUrl use short-lived signed URLs returned in MVView (60 minutes by default); storage keys and permanent public bucket URLs are not customer delivery links. Tracked outputs also expose additive assetId, urlExpiresAt, retainedUntil, and assetStatus fields. Use GET /api/v1/mv/{mvId}/final to refresh the final MP4 URL; if the response has ready=false, inspect staleReason, retryable, and actionHint.

source accepts media-source fields only. Put subtitles, subtitle, srtUrl, and generation at the request top level. Known top-level fields nested under source are rejected before task creation and charging instead of being silently ignored.

---

Scene Controls

Fast and Studio write operations are versioned. New clients should send expectedVersion from the latest MVView.version; stale versions return 409 MV_VERSION_CONFLICT. On conflict, read GET /api/v1/mv/{mvId} again and retry with the current version. Studio requires this version for storyboard writes. Fast uses the same field for managed scene edits and later recomposition. If expectedVersion is omitted on a Fast request, OmnAPI uses the latest MV version available when the request is accepted. This is kept for backward compatibility; sending expectedVersion is recommended so concurrent edits can be detected.

Edit one Fast scene

Fast scene edit reuses the public render endpoint. OmnAPI maps this to the managed scene edit operation and increments MVView.version when the edit is accepted. It does not refresh the final MP4 by itself.

Recommended flow:

1. Read the current MVView and keep MVView.version.
2. Quote the scene edit.
3. Create the scene edit task with prompt and expectedVersion.
4. Poll the returned task until it reaches a terminal state.
5. Read MVView again and inspect the edited scene’s sourceJob.
6. Optionally select any isSelectable=true version from renderingHistory.
7. When the selected composition is ready, quote and finalize to recompose the final MP4.

Read the current version:

curl https://api.omnapi.com/api/v1/mv/{mvId} \
  -H "x-api-key: sk_live_..."

Preview the scene edit charge before creating the paid edit task:

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

Edit one generated Fast scene:

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/scenes/2/render \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 4,
    "quoteId": "{quoteId}",
    "maxCredits": 240,
    "prompt": "close-up singer shot, warm backlight, smoother camera motion"
  }'

Fast scene edit requests accept prompt, optional expectedVersion, and optional task config. videoPromptOverride and videoPrompt are accepted only as compatibility aliases for the Fast prompt; new Fast integrations should send prompt. Studio render fields such as resolution, videoProvider, and videoModel are Studio-only; passing them on a Fast MV is rejected.

The response includes taskId, sceneIndex, version, charged, and creditsRequired. Poll the task:

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

After the edit task completes, read MVView again. If scene.sourceJob.status is RENDERING, keep polling or read again later. If it is FAILED, the previous playable scene.videoUrl may still remain available; retry the scene edit or select a different successful history item before recomposing.

Select any Fast scene version with isSelectable=true by passing the corresponding MVView.scenes[].renderingHistory[].id:

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

The response includes the refreshed version. Selecting the already effective rendering is a no-op. Selecting a different rendering makes the final MP4 stale until you recompose it.

Quote the final recomposition:

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

Then create the finalize task with the refreshed MVView.version:

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/finalize \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expectedVersion": 5, "quoteId": "{quoteId}", "maxCredits": 50 }'

Poll the finalize task using the returned taskId, then read the final URL:

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

curl https://api.omnapi.com/api/v1/mv/{mvId}/final \
  -H "x-api-key: sk_live_..."

Studio: regenerate one scene image

Persist prompt or editorial changes before regenerating or rendering:

curl -X PATCH https://api.omnapi.com/api/v1/mv/{mvId}/scenes/2 \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 4,
    "imagePrompt": "same singer, warmer sunset palette",
    "videoPrompt": "slow push-in with restrained motion",
    "framing": "close-up",
    "lighting": "golden hour"
  }'

Image-affecting edits invalidate the previous still and selected rendering; video-only edits retain the still but make the scene stale. The response returns the incremented scene and MV versions.

Timing edits must keep each scene within 1–16 seconds, avoid overlap with adjacent scenes, and stay within the known source duration. Submitting only unchanged values is rejected instead of invalidating an otherwise current scene.

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/scenes/2/regenerate-image \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expectedVersion": 5, "quoteId": "{quoteId}", "maxCredits": 15, "imagePromptOverride": "warmer sunset palette, keep the same character" }'

Studio: render one scene video

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/scenes/2/render \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 6,
    "quoteId": "{quoteId}",
    "maxCredits": 240,
    "videoProvider": "p-video",
    "videoModel": "p-video",
    "resolution": "540p"
  }'

For Studio, prompt is treated as a one-shot videoPromptOverride.

To render several current scene versions with one quote, idempotency key, task, and charge, use step:"render-batch" on quote and then:

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/scenes/render-batch \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: studio-render-batch-01" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 6,
    "quoteId": "{quoteId}",
    "maxCredits": 720,
    "sceneIndexes": [0, 1],
    "videoProvider": "p-video",
    "videoModel": "p-video",
    "resolution": "540p"
  }'

The batch accepts 1-30 scenes. Each scene result remains visible; a partial failure does not hide successful renders. OmnAPI charges the successful scene components and atomically refunds the failed scene components; if every scene fails, the task follows the normal full-refund path.

Select a Studio rendering

curl -X PATCH https://api.omnapi.com/api/v1/mv/{mvId}/scenes/2/select-rendering \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expectedVersion": 6, "renderingId": "rend_01H..." }'

Studio: lock a character anchor

Quote the operation with mode:"studio", step:"lock-character", and the current mvId, then confirm the returned ceiling on the write:

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/lock-character \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 7,
    "quoteId": "{quoteId}",
    "maxCredits": 5,
    "characterImage": "https://example.com/portrait.jpg",
    "description": "same singer throughout the video"
  }'

characterImage must be a public http(s) URL.

---

Finalize

Fast create normally generates and stores the final MP4 automatically. After the create task completes, call GET /api/v1/mv/{mvId}/final to get a fresh temporary URL. This endpoint is read/refresh only: it returns ready=true only when the stored final matches the current source composition. If Fast scene edits later make the final stale, the response returns ready=false, staleReason="source_changed", and actionHint="recompose_after_edit".

Fast explicit finalize is used for recovery or to recompose after successful Fast scene edits or selection changes. The finalize task creates a new final MP4 from the selected successful scene outputs. For legacy Fast projects with no explicit selections, OmnAPI uses the newest successful output per scene.

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

Studio finalize stitches selected scene renderings with the resolved audio:

curl -X POST https://api.omnapi.com/api/v1/mv/{mvId}/finalize \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 8,
    "scenes": [
      { "sceneIndex": 0, "renderingId": "rend_01H..." },
      { "sceneIndex": 1, "renderingId": "rend_01J..." }
    ]
  }'

Body field	Type	Notes
title	string	Optional title override.
retry	bool	Retry a failed finalize when supported.
expectedVersion	number	Studio required. Fast optional for backward compatibility, recommended for new clients; use the latest MVView.version.
selectLatest	bool	Studio: finalize latest ready rendering per scene.
scenes	array	Studio: explicit scene/rendering selection.
config	object	Optional task config for the finalize task.

Response fields: taskId, creditsRequired, status, idempotent, optional finalMvId, optional compositionHash, optional retryable.

Fast finalize uses the selected successful output per scene and records composition metadata so repeated finalization remains idempotent. Studio finalize remains selected-scene stitching; when the selected composition changes, OmnAPI prepares a final asset for the new composition.

When the task completes:

curl https://api.omnapi.com/api/v1/mv/{mvId}/final

Returns a short-lived final MP4 URL when ready (60 minutes by default):

{
  "id": "<final-mv-asset-id>",
  "ready": true,
  "status": "READY",
  "videoUrl": "https://cdn.omnapi.com/...",
  "expiresInSec": 3600,
  "urlExpiresAt": "2026-07-11T15:00:00.000Z",
  "retainedUntil": "2026-08-10T14:00:00.000Z"
}

If GET /final returns ready=false, use staleReason to choose the next action:

staleReason	Action
source_rendering	Wait for the scene edit task to finish, then read MVView again.
source_failed	Retry the failed scene edit before finalizing.
source_changed	Call POST /api/v1/mv/{mvId}/finalize to recompose.
final_processing	Poll the finalize task or call GET /final again later.

---

Quote

POST /api/v1/mv/quote is a pricing preview. It does not check whether remote audio or image URLs are reachable. Use preflight when you need resource validation and a reusable create-time estimate. Use maxCredits on create when the caller needs a hard charge cap. Each quote returns a short-lived quoteId, operation, expiresAt, and pricingVersion. Supply quoteId and maxCredits on the corresponding paid write. The server reprices immediately before atomic task creation and direct debit; an expired, used, mismatched, or over-budget quote is rejected without creating another charge.

Treat quote as estimate-only and preflight as validated estimate: quote is right for calculators and budget previews, while preflight is the last safe check before a paid create because it validates source media, reference images, optional characterImage, and optional srtUrl.

Fast quote:

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

Fast high-quality quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "fast", "durationSec": 10, "quality": "high", "resolution": "720p", "lipSync": false, "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "gpt-image-2", "visualBoardImageCount": 1 }'

Fast scene-edit quote:

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

Fast recompose quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "fast", "step": "compose", "mvId": "{mvId}" }'

Fast scene-edit quote reads duration and resolution from saved Fast scene metadata; callers do not pass durationSec or resolution for scene edits. Fast compose quote returns credits: 0 when the current final already matches the latest scene composition.

Studio storyboard quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "gpt-image-2", "visualBoardImageCount": 8 }'

Visual Board add-on fields:

Field	Type	Notes
quality	"standard" | "high"	Optional Fast quality tier. standard uses regular Fast pricing. high requires 720p or 1080p.
visualBoardStrategy	"direct_scene_images"	Optional; direct scene-image generation is the only public strategy.
visualBoardImageProvider	"gpt-image-2", "p-image", or "viduq2"	Optional but recommended when quoting Visual Board add-ons. Pricing follows the selected image option.
visualBoardImageCount	number	Direct-scene pricing unit, max 50.
visualBoardReferenceImageCount	number	Reference-image input count for reference-capable Visual Board providers, max 16. Include it when your create/preflight body will use characterImage or caller references with a provider such as gpt-image-2.

When visualBoardStrategy is direct_scene_images, include visualBoardImageProvider for an exact quote. If omitted, the API keeps the request compatible and returns a conservative direct-scene estimate with warningCodes: ["MV_VISUAL_BOARD_PROVIDER_REQUIRED_FOR_DIRECT_QUOTE"]. For Fast create/preflight, this same provider choice lives at generation.visualBoard.imageProvider; quote keeps it flat because it is a lightweight pricing shape rather than a full create request.

For gpt-image-2 Visual Board quotes, visualBoardReferenceImageCount adds the reference-image input cost. Image options without reference-input billing ignore the count for pricing.

P-Image direct scene-image storyboard quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "p-image", "visualBoardImageCount": 3 }'

Direct scene-image storyboard quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "studio", "step": "storyboard", "visualBoardStrategy": "direct_scene_images", "visualBoardImageProvider": "viduq2", "visualBoardImageCount": 3 }'

Studio render-scene quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "studio", "step": "render-scene", "durationSec": 4, "videoProvider": "p-video", "videoModel": "p-video", "resolution": "540p" }'

Studio total quote:

curl -X POST https://api.omnapi.com/api/v1/mv/quote \
  -H "x-api-key: sk_live_..." \
  -d '{ "mode": "studio", "step": "total", "estimatedSceneCount": 7, "perSceneDurationSec": 4, "videoProvider": "p-video", "videoModel": "p-video", "resolution": "540p" }'

Pricing summary:

Mode	Item	Credits
Fast	quote	0
Fast	540p	Dynamic; call /api/v1/mv/quote
Fast	720p	Dynamic; call /api/v1/mv/quote
Fast	1080p	Dynamic; call /api/v1/mv/quote
Fast	high quality	Dynamic; call /api/v1/mv/quote. Requires 720p or 1080p.
Fast	lip-sync	Dynamic; call /api/v1/mv/quote
Fast	scene edit	Dynamic; call /api/v1/mv/quote with step:"scene-edit"
Fast	recompose final after scene edit	Dynamic; call /api/v1/mv/quote with step:"compose"
Studio	storyboard + scene stills	250 plus optional Visual Board add-on
Studio	regenerate scene image	15
Studio	render scene	Dynamic by selected render option, model, resolution, fps, and duration
Studio	finalize	50

---

Operation ledger, cancellation, and deletion

GET /api/v1/mv/{mvId}/operations returns each quote/task linkage plus authorized, charged, refunded, and net credits. Its costSummary covers all recorded MV operation rows even when the returned item list is limited. MVView.costSummary provides the same recorded totals for normal product reads. For projects that predate operation-ledger coverage, earlier work may be absent; use task billing or the authenticated usage export for pre-cutover spend. See the MV migration notes.

Cancel an active operation with POST /api/v1/mv/{mvId}/operations/{taskId}/cancel. Cancellation is idempotent, stops OmnAPI processing, and refunds the reserved task credits. Some generation services do not support dependable remote cancellation; when work had already been submitted, upstreamMayContinue=true makes that limitation explicit.

DELETE /api/v1/mv/{mvId} removes the resource from customer lists/reads and best-effort deletes known source, scene, rendering, character, and final media. Task, operation, pricing, and billing records required for financial reconciliation remain subject to the platform audit-retention policy. After the configured Task retention window, retained MV operation Tasks are compacted to financial audit fields; request, provider, result, step, and webhook payloads are removed. Normal MV output assets are retained for 30 days by default. A successful finalize or recompose resets the final video’s retention window; refreshing a signed URL, opening the app, polling a Task, or playing a video does not extend that window. Scene videos used by a successful finalize or recompose are retained through the corresponding final delivery window. Download assets that must be kept longer.

Final delivery is gated by deterministic media checks for a usable video stream, audio stream, expected duration, purchased resolution tier, and viable frame rate. Creative quality remains subjective and is not an automatic-refund signal.

---

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.

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.

---

Lifecycle states

MVView.status	Meaning
PENDING	Generation task accepted
GENERATING	MV generation is running
READY	Fast finalization is resolving or Studio storyboard is ready for scene renders
RENDERING	Studio scene rendering or Fast scene edit is in flight
FINALIZING	Final stitch is in progress
COMPLETED	finalMv.videoUrl is populated
EDITING	Studio has edits since last finalize
ACTION_REQUIRED	Studio produced usable partial output but one or more scene stills need user retry or review
FAILED	Generation failed
ARCHIVED	Archived; public reads normally return not found
DELETED	User-deleted; public reads return not found

MVSceneView.status	Meaning
PLANNED	Scene plan exists, image not yet generated
IMAGE_READY	Scene image generated, no video yet
RENDERING	Scene rendering is in flight
READY	Scene has a video
FAILED	Generation failed
STALE	A newer edit invalidated this scene

---

Error codes

Code	HTTP	Meaning
MV_MODE_REQUIRED	400	mode field absent
MV_MODE_INVALID	400	Unknown mode value
MV_SOURCE_REQUIRED	400	source field absent
MV_SOURCE_INVALID	400	Unknown source variant
MV_SUNO_CLIP_NOT_READY	409	Suno clip exists but is not completed
MV_REFERENCE_IMAGE_REQUIRED	400	The requested MV path requires at least one usable reference image
MV_AUDIO_DURATION_INVALID	400	Effective duration is outside 10-300s, or range.endSec is not greater than range.startSec
MV_AUDIO_DURATION_UNAVAILABLE	400	OmnAPI could not determine reliable remote audio duration
MV_AUDIO_CODEC_UNSUPPORTED	400	Not MP3/WAV/AAC/M4A
MV_AUDIO_DOWNLOAD_FAILED	400 / 408 / 502	Remote audio could not be fetched, timed out, returned an unsupported response, or lacked bounded size metadata
MV_AUDIO_SOURCE_TOO_LARGE	413	Remote audio exceeds the validation or download size limit
MV_TOO_MANY_REFERENCES	400	More than 7 reference images
MV_REFERENCE_IMAGE_INVALID	400	Asset URL is malformed, non-public, not http(s), unreadable, or lacks size metadata
MV_IMAGE_PAYLOAD_TOO_LARGE	413	referenceImages[*] or characterImage exceeds 12MB, or srtUrl exceeds 4MB
MV_PROVIDER_RESOURCE_INVALID	400	A final image or subtitle sent to the managed MV service is invalid, unsupported, or too large
MV_ASPECT_RATIO_INVALID	400	Unknown aspect ratio
MV_RESOLUTION_INVALID	400	Unknown resolution
MV_PROMPT_TOO_LONG	400	prompt.length > 3000
MV_SUBTITLE_TIMING_REQUIRED	400	Fast custom subtitle rendering needs caller srtUrl, usable Suno lyric timing, or successful auto-generated timing
MV_SUBTITLE_FILE_INVALID	400	The provided SRT could not be parsed into usable subtitle cues
MV_SUBTITLE_RENDER_UNAVAILABLE	503	OmnAPI custom subtitle rendering is temporarily unavailable
MV_SUBTITLE_RENDER_FAILED	502	OmnAPI could not render custom subtitles into the final video
MV_AUTO_SUBTITLE_FAILED	400 / 502	Auto subtitle extraction was required, but transcription or artifact generation failed and fallback did not allow continuing
SUBTITLE_BUDGET_EXCEEDED	400	Active subtitle price exceeds subtitle.maxCostUsdPerMin
MV_NOT_SUPPORTED_IN_FAST	400	Studio-only operation called on a Fast MV
MV_NOT_SUPPORTED_IN_STUDIO	400	Fast-only operation called on a Studio MV
MV_VERSION_CONFLICT	409	Fast or Studio write used a stale expectedVersion
MV_PRECONDITION_FAILED	409	A required MV stage, selected scene, or source asset is not ready
MV_FINAL_VIDEO_INGEST_FAILED	502	The final generated video could not be fetched or stored
MV_TECHNICAL_QA_FAILED	502	The final output failed deterministic audio/video, duration, resolution, or frame-rate delivery checks
MV_PROVIDER_OUTPUT_TOO_LARGE	413	The generated output exceeded the allowed ingest size
MV_STORAGE_WRITE_FAILED	502	OmnAPI could not persist a generated MV asset
MV_PROVIDER_UNAVAILABLE	503	Fast health is unknown/unavailable while the operator-controlled paid-create gate is enabled; check /api/v1/mv/fast/availability and retry later
MV_NOT_FOUND	404	Unknown mvId
INSUFFICIENT_CREDITS	402	Quote exceeds available balance or the submitted maxCredits cap
RATE_LIMITED	429	Per-account concurrency cap hit

Warning codes

Code	Meaning	Suggested action
MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED	Fast audio source used provided-only managed subtitles without srtUrl; OmnAPI could not verify timing.	Use subtitle.mode="auto" or provide srtUrl for deterministic timing.
MV_SUBTITLE_DISABLED_NO_TIMELINE	Studio audio source used provided-only subtitles without srtUrl, so subtitles were disabled.	Use subtitle.mode="auto", provide srtUrl, or use a Suno source with usable timing.
MV_AUTO_SUBTITLE_GENERATED	Missing timed lyrics/SRT was filled by internal Subtitle Sync.	No action required; inspect generated captions before publishing user-visible content.
MV_AUTO_SUBTITLE_LOW_CONFIDENCE	Auto subtitle result was accepted but confidence is low.	Offer a caption review step or ask the user for an SRT file.
MV_AUTO_SUBTITLE_FALLBACK_SKIPPED	Auto subtitle failed and request policy allowed continuing without subtitles.	Show the MV as complete without captions and allow retry with SRT or stricter fallback.
MV_SCENE_IMAGES_FROM_AUTO_BOARD	Studio empty referenceImages: scene stills will come from Visual Board panels.	Add reference images when you need stronger user-supplied visual direction.
MV_REFERENCE_IMAGES_AUTOGENERATED	No caller references were supplied; OmnAPI generated Visual Board references automatically.	No action required unless you need exact identity or style control.
MV_CHARACTER_IMAGE_REFERENCE_IGNORED	Fast Visual Board synthesis received characterImage, but the effective image provider did not use reference-image inputs.	Use gpt-image-2 for synthesized Visual Board references or keep caller referenceImages in the default direct strategy.
MV_REFERENCE_IMAGES_TRUNCATED_FOR_CHARACTER	Fast generation.referenceStrategy="synthesize" received characterImage plus more than six non-character referenceImages; only the first six secondary references were used for Visual Board planning.	Reduce secondary references to the six most important images or use the default direct strategy.
MV_LIP_REF_AUTO_DERIVE_SKIPPED	Fast lipSync=true could not prepare a managed lip-sync reference from characterImage.	Provide a clearer frontal characterImage and retry.
MV_FACE_DETAIL_LOW_RESOLUTION_RISK	Fast resolution=540p includes face/detail cues or characterImage; facial or eye stability may degrade.	Prefer 720p or 1080p for face-led or lip-sync MVs.
MV_VISUAL_BOARD_PROVIDER_REQUIRED_FOR_DIRECT_QUOTE	A direct-scene Visual Board quote omitted visualBoardImageProvider, so the quote used a compatible fallback estimate.	Include visualBoardImageProvider in quote, matching generation.visualBoard.imageProvider in create/preflight.
MV_FAST_PROVIDER_DEGRADED	Fast MV provider health is degraded but requests are still accepted.	Use webhooks, set idempotency keys, and expect elevated latency or retry risk.
MV_SCENE_ASSET_NOT_DURABLE	A successful Fast scene result has not yet been copied into OmnAPI-owned storage. The final video may still be usable, and historical scene selection remains compatible, but the scene preview URL may expire.	Refresh the MV later; contact support if the durable preview remains unavailable.

---

Webhooks

MV uses the same webhook delivery as every other task surface: pass config.webhookUrl on create, render, regenerate, or finalize operations, and OmnAPI delivers task.* events. Studio storyboard tasks may also emit task.stage.* events for documented progress stages.

Fast and Studio finalization tasks may also emit product-level mv.ready or mv.failed events. These events include MV-specific fields such as mvId, finalMvId, viewUrl, and finalUrl when available.

See Webhook Events for payload shape, event vocabulary, delivery, and retry semantics.

---

Common pitfalls

Caution

Create returns both taskId and a stable mvId. Persist mvId immediately, poll taskId for execution, and use mvId for product reads and later writes. Do not treat a non-null mvId as proof that the MV is ready.

Caution

Use expectedVersion on new MV writes. Studio requires it. Fast accepts omitted expectedVersion on backward-compatible scene edit/recompose calls, but new clients should still read the latest MVView.version and send it.

Caution

Public inputs are URL-only. Public callers host audio, images, and SRT files in their own public environment and pass public https URLs.

Caution

Use preflight before paid creates. It validates reachable media resources and returns a reusable estimate without charging credits. Use maxCredits to cap the final create-time charge.

---

See also

• The Task Model — lifecycle, polling, config, sync/async
• Webhook Events — delivery semantics
• Credits & Billing — refund semantics on failure
• Errors — full MV_* error catalog