MV Quotes, Results and Recovery

Product overview · Task model

Fast Availability

Check Fast delivery health before submitting production batches:

curl 'https://api.omnapi.com/api/v1/mv/fast/availability?managedVersion=oneclick-v1' \
  -H "x-api-key: sk_live_..."

Response:

{
  "managedVersion": "oneclick-v1",
  "status": "available",
  "gateEnabled": true,
  "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 retained for response compatibility and is currently fixed to true. An unknown or unavailable status fails paid create 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. Availability, delivery history, and circuit state are isolated by managed version. Query ?managedVersion=premium-v2 before Premium V2 paid creates.

---

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;
    managedVersion?: "oneclick-v1" | "premium-v2" | null;
    performanceMode?: "sing" | "sing_perform" | "perform" | "dance" | 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;
    canRerenderSceneWithPrompt: boolean;
    canRerenderSceneWithImages: 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;
  };
};

billing.creditsReserved is a compatibility field name on MVView: it is the initial MV amount authorized and deducted at create time. It does not represent a separate, still-pending reservation. For cross-product accounting, prefer the Task’s creditsRequired and the finalized creditsCharged/refunded fields; use costSummary for MV operation-ledger totals.

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;
    prompt?: string | null;
    referenceImages?: string[];
    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 their returned renderingId, 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.

---

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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -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_..." \
  -H "Content-Type: application/json" \
  -d '{ "mode": "studio", "step": "total", "estimatedSceneCount": 7, "perSceneDurationSec": 4, "videoProvider": "p-video", "videoModel": "p-video", "resolution": "540p" }'

Quote request variants

mode and, except for Fast create pricing, step discriminate the request. Unknown fields and unsupported combinations are rejected.

Quote variant	Required fields	Optional fields
Fast OneClick V1 create	mode:"fast", durationSec	step:"create", managedVersion:"oneclick-v1", resolution, lipSync, quality, subtitleMode, and Visual Board quote fields
Fast Premium V2 create	mode:"fast", managedVersion:"premium-v2", performanceMode, durationSec	step:"create", resolution:"720p", subtitleMode, and Visual Board quote fields; omit lipSync and quality
Fast scene edit	mode:"fast", step:"scene-edit", mvId, sceneIndex	none
Fast compose	mode:"fast", step:"compose", mvId	none
Studio storyboard	mode:"studio", step:"storyboard"	visualBoardStrategy, visualBoardImageProvider, visualBoardImageCount, visualBoardReferenceImageCount
Studio render scene	mode:"studio", step:"render-scene", videoProvider, resolution, durationSec	videoModel, fps, draft
Studio render batch	mode:"studio", step:"render-batch", mvId, sceneIndexes, videoProvider, resolution	videoModel, fps, draft
Studio regenerate image	mode:"studio", step:"regenerate-image", mvId, sceneIndex	none
Studio lock character	mode:"studio", step:"lock-character", mvId	none
Studio finalize	mode:"studio", step:"finalize", mvId	none
Studio total	mode:"studio", step:"total", videoProvider, resolution, perSceneDurationSec, estimatedSceneCount	videoModel, draft, visualBoardStrategy, visualBoardImageProvider, visualBoardImageCount

OneClick V1 Fast create durationSec is 10-600; Premium V2 is 10-300. Studio render and total durations are 1-16 seconds; estimatedSceneCount and quote sceneIndexes allow 1-30 scenes. Quote sceneIndex values are non-negative. Visual Board counts allow 1-50 generated images and 0-16 reference images. The resolution, fps, and Provider enums match the Studio mutation table above.

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
Premium V2	perform at 720p	21 Vidu credits/second; call /api/v1/mv/quote for OmnAPI credits
Premium V2	sing, sing_perform, or dance at 720p	24 Vidu credits/second; call /api/v1/mv/quote for OmnAPI credits
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. Before Provider submission, a successful cancellation atomically stops the inactive OmnAPI job and refunds the eligible credits deducted for that task. After Provider submission, cancellation succeeds only if the generation service explicitly confirms remote cancellation. Current managed MV providers do not expose a dependable confirmation contract, so submitted or outcome-unknown operations return 409, stay active, keep their original charge, and continue status synchronization. Keep polling the original task; OmnAPI no longer reports a local CANCELLED state while remote work may continue.

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.

---

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 the 10-600s Fast or 10-300s Studio range, 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.

---