Omn V1 availability and recovery

Omn V1 quickstart · Compare music video options

Read capabilities

GET /api/v1/mv/capabilities returns the boolean native.selectableContracts fields. native.selectableContractDetails.oneclickV1 describes OneClick V1; premiumV2Perform describes OneClick V2, and its singing, dance and motion fields cover the other performance modes of that purchase. These are request profile names: oneclickV1 corresponds to managedVersion: "oneclick-v1", and premiumV2Perform to managedVersion: "premium-v2"; both use engineVersion: "omn-v1" here. They do not select Vidu.

Before enabling an option, check the profile’s selectable, supported output settings and duration range. When capabilityReadiness is present, use narrative.ready or singing.ready for the requested capability; the parent ready only means at least one capability is ready. With older responses, use the parent as an initial hint. Always preflight the exact body and handle admission rejection at creation. Capability readiness details.

This is an illustrative response excerpt; use the values returned for your account.

{
  "native": {
    "newAdmissionEnabled": true,
    "defaultEngine": { "enabled": false, "contracts": [] },
    "selectableContracts": { "oneclickV1": true, "premiumV2Perform": true },
    "selectableContractDetails": {
      "oneclickV1": {
        "selectable": true,
        "ready": true,
        "minDurationSec": 5,
        "maxDurationSec": 600,
        "resolutions": ["540p", "720p", "1080p", "1440p"],
        "aspectRatios": ["16:9", "9:16", "1:1"],
        "renderTiers": ["draft", "standard", "hd", "ultra"],
        "schedules": ["standard", "economy"],
        "shotTypes": ["narrative", "bridge", "lipsync", "performance"],
        "lipSync": true,
        "maxSingers": 1,
        "dance": false,
        "motionVideo": false,
        "characterImage": true
      },
      "premiumV2Perform": {
        "selectable": true,
        "ready": false,
        "unavailableReason": "capacity_unavailable",
        "resolutions": ["720p"],
        "renderTiers": ["standard"],
        "shotTypes": ["narrative", "bridge", "performance", "lipsync", "dance"],
        "lipSync": true,
        "maxSingers": 2,
        "dance": true,
        "motionVideo": true
      }
    }
  }
}

Field	Meaning
selectable, ready, unavailableReason	Whether Omn V1 is open for the purchase and can accept new generations now; the reason matches MV_PROVIDER_UNAVAILABLE
minDurationSec, maxDurationSec	Accepted effective duration range in seconds; maxDurationSec is 0 when not selectable
resolutions, aspectRatios	Delivery options a plain request can use, including 1440p and 4:3/3:4 when offered
renderTiers, schedules	Accepted generation.renderTier and generation.schedule values
shotTypes	Shot types planning can use: narrative, lipsync, performance, dance, bridge. For the types a finished MV’s shot edits accept, read its MVView.capabilities.editShotTypes
lipSync, maxSingers	Whether singing shots are available and the largest number of ordered singer portraits
dance, motionVideo	Whether OneClick V2 dance and a motion reference video are available; motion transfer applies to 16:9 and 9:16
characterImage	Whether characterImage is accepted

These values are hints for a plain request with reference images, not approval of a specific one; a text-only request may still be rejected. A deployment that offers Omn V1 without shot-based rendering reports only standard in renderTiers, only narrative in shotTypes, and false for the singing, dance, motion and character fields; those options then return 422 MV_ENGINE_UNSUPPORTED. There, standard is the single render tier: an explicit renderTier: "standard" is accepted at every resolution the capabilities list, including 1080p.

Legacy request compatibility

The deployed API uses oneclick-v1 and premium-v2 request profiles on Omn V1. The latter requires performanceMode and keeps its 300-second limit. The independent request format with native.modes is an unreleased preview; do not rely on it in production.

Explicit engine selections and saved preflights keep their chosen engine. Requests without an explicit engine follow the default-engine rules.

During generation

After the Task is created:

• Shot types appear on each scene’s renderingHistory[].shotType, with the tier in renderingHistory[].renderTier. Scene indexes are zero-based.
• A shot that fails during rendering is regenerated once at OmnAPI’s cost. Shots rejected by content review are not regenerated; the Task fails.
• If a shot’s outcome cannot be confirmed within 1 hour, or a started shot has not finished within 3 hours, the Task fails and is refunded instead of waiting for a longer delivery deadline. The Task’s own deliveryDeadlineAt can end it earlier; do not use the shot limits as the client timeout. Time an economy shot spends waiting for the off-peak window does not count toward these shot limits.
• Shot prompts carry imagery from the lyrics rather than the lyrics themselves and ask for no on-screen text. Only singing shots show singing or lip movement.

Temporary media-access failures are retried while the accepted Task remains active. Keep polling that Task; do not create a second purchase while it is recovering. Read deliveryDeadlineAt for its actual deadline (30 minutes for the current Omn pool path). A short output duration does not promise that the job finishes in the same number of seconds. If delivery fails at the deadline, verify the final refund settlement before a new attempt.

Omn V1 Tasks can also end with these codes. Each stops before any video is rendered, and the Task is refunded:

errorCode	Meaning	Retry
MV_NATIVE_SHOT_PROMPT_TOO_LONG	The planned shot prompts would exceed the video prompt limit.	Shorten the prompt or character descriptions, then create a new Task.
MV_NATIVE_REFERENCE_REJECTED	The pre-video check found the reference images do not fit the song or story, for example the wrong number of characters. The message says what to change.	Change the reference images or prompt, then create a new Task.
MV_NATIVE_PREPARATION_REPAIR_EXHAUSTED	Automatic preparation could not produce consistent visuals within its repair or time limit. This is a preparation failure, not a requirement to add a portrait.	After the failed Task settles, retry later with a new Idempotency-Key.
MV_NATIVE_REFERENCE_INPUT_REQUIRED	A supplied character image is unclear or has the wrong cast.	Correct the image as described in the error, then create a new Task.
MV_NATIVE_PREPARATION_REPAIR_UNCERTAIN	Preparation could not confirm an earlier repair result; it stopped to avoid duplicate purchases.	Verify the terminal settlement, then retry later with a new Idempotency-Key.
MV_NATIVE_REFERENCE_REVIEW_UNAVAILABLE	The pre-video check could not finish.	Retry later with a new Idempotency-Key.

Failure messages describe the problem in OmnAPI terms. When a failure’s internal details cannot be shown, errorMessage on the Task, the Task list and webhooks, MVView.lastErrorMessage and failureReason.message, and failureMessage on GET /api/v1/mv/{mvId}/final read This MV could not be processed. Please retry later with a new idempotency key. A failed scene’s scenes[].sourceJob.errorMessage reads This scene could not be rendered. Edit the scene to render it again. The errorCode is unchanged. Branch on errorCode, retryable and refunded, not on the message text.

Rejections

The request-admission rejections in this section happen before a Task is created or credits are charged. Execution failures after acceptance are separate: read the original Task and verify its settlement. The message and details.reason never name an internal service.

HTTP / code	Meaning	details
422 MV_ENGINE_UNSUPPORTED	This request can never run on Omn V1 with the current configuration. Quote and preflight apply the same rules. Change the request or choose another engineVersion; do not retry unchanged.	{ "engineVersion": "omn-v1", "reason": "...", "retryable": false }
503 MV_PROVIDER_UNAVAILABLE	Omn V1 is temporarily unavailable. Retry later when retryable is true.	{ "engineVersion": "omn-v1", "reason": "...", "retryable": true }

MV_ENGINE_UNSUPPORTED reasons:

reason	Change
specialist_mode_unsupported	The requested performance or dance shots, singer count or motion reference cannot be served, for example for a text-only request; add reference images, or check dance, maxSingers and motionVideo
lip_sync_unsupported	Singing shots are not available for this tier, aspect ratio or deployment, or for a text-only request; add reference images, remove lipSync or the singing mode, or choose another tier
character_image_unsupported	Remove characterImage; see characterImage in capabilities
output_profile_unsupported	Choose a render tier, resolution and quality from the price table and capabilities
aspect_ratio_unsupported	Choose an aspect ratio listed in capabilities that can render every requested shot type
duration_unsupported	Stay within the capabilities duration range
cost_limit_exceeded	Shorten the song, lower the tier or reduce reference images
subtitle_timeline_required	Provide srtUrl, use a Suno source with timing, allow automatic subtitles, or turn subtitles off
contract_unsupported	Use oneclick-v1 or premium-v2 with the corresponding native.selectableContractDetails; remove providerOverride
source_unsupported	Use a supported Suno clip or public audio source
reference_images_unsupported	Reduce the reference images or Visual Board images; for an upgrade, edit the scene with fewer references
mode_unsupported	Omn V1 is available for Fast only
not_eligible	Economy is not available for this request (use schedule: "standard"), the MV cannot be upgraded, or Omn V1 is not offered for it; choose another option or engineVersion

MV_PROVIDER_UNAVAILABLE reasons: engine_closed (Omn V1 is not accepting new requests; retryable: false), capacity_unavailable, workers_unavailable, engine_configuration_unavailable and scheduling_unavailable (all retryable: true).

{
  "success": false,
  "error": {
    "code": "MV_ENGINE_UNSUPPORTED",
    "message": "Omn V1 does not support this request: output_profile_unsupported",
    "details": {
      "engineVersion": "omn-v1",
      "reason": "output_profile_unsupported",
      "retryable": false
    }
  }
}

Unsupported values for the Omn-only fields return 400 before admission: VALIDATION_ERROR for a field sent without omn-v1, an invalid renderTier or schedule value, a tier or quality conflict, or any motion reference problem, and MV_RESOLUTION_INVALID for a tier and resolution mismatch or 1440p on another engine. Field-level errors for generation.renderTier, generation.schedule and the motion reference fields name the field in details.field.

Choose the next action

Save the operation’s route, exact body, Idempotency-Key, taskId, mvId and X-Request-Id. HTTP request errors and an accepted Task’s later failures are different events. Do not turn a transport error into a new paid attempt.

Situation	Credit / Task outcome	Client action
Connection timeout, broken response, or ambiguous server error during a paid write	Acceptance is unknown	Retry the original route with the saved key and identical body. Do not refresh the preflight or change keys to recover an uncertain purchase
409 CONFLICT on a same-body replay	An operation may already exist	Poll error.details.taskId when supplied; otherwise back off and retry the same request. A used quote may identify details.usedTaskId
409 CONFLICT because the body differs	Not permission to buy again	Restore the saved body to recover the original operation. Resolve its outcome before intentionally starting another purchase
400 VALIDATION_ERROR for an expired/missing preflightId, or 409 CONFLICT for a mismatched preflight or changed price card	That rejected attempt creates no Task	Once earlier acceptance is ruled out, run preflight again, review the amount, and save the new create body with a new operation key
401 INVALID_API_KEY / 403 FORBIDDEN	Request rejected	Check key, scopes, IP restrictions and purchased-credit eligibility. A preflight is tied to its originating key; regenerate it after changing keys only after resolving any uncertain create
402 INSUFFICIENT_CREDITS	No Task created for the rejected purchase	Check both available balance and maxCredits (and any quote ceiling). Obtain a new reviewed budget or change the input; do not automatically raise the cap
429 RATE_LIMITED	Request/admission limited	Honor Retry-After when present. Without it, use bounded backoff and wait for active Tasks to finish. Keep the same key/body for an unchanged retry
422 MV_ENGINE_UNSUPPORTED	Admission rejected before charge	Fix the option named by details.reason; repeating unchanged will not help
503 MV_PROVIDER_UNAVAILABLE with a known admission rejection	No Task created	Retry later with the same key/body only when details.retryable is true; engine_closed is not an automatic-retry instruction
Task remains non-terminal, or final ready: false with actionHint: "wait"	Existing purchase continues	Poll the original Task/final endpoint. Do not pay for another generation or finalize
Task FAILED / CANCELLED	Execution ended; settlement may still be pending	Verify credit settlement below. A deliberate new attempt needs a new key and new preflight; use retryable and the error code to decide whether to retry or fix inputs
Edit/upgrade fails	That operation settles separately	Poll its Task and ledger item; a failed upgrade keeps the previous final. Read the MV again before another edit or upgrade
409 MV_PRECONDITION_FAILED with source_assets_unavailable	New operation rejected before charge	Missing/expired inputs cannot be restored by repeating the same request. Keep any downloaded final or create a new MV with available sources

details.reason is available for Omn admission errors, but not every generic validation/conflict response has a structured reason. Keep the local saved request and quote/preflight expiry; never depend on exact English error text. When a conflict remains ambiguous, recover the original Task or contact support rather than creating another purchase.

The following preparation failures happen after acceptance, not as evidence that a new Task was never charged:

Task errorCode	Next action
MV_NATIVE_SHOT_PROMPT_TOO_LONG	Shorten the prompt or character descriptions before a new attempt
MV_NATIVE_REFERENCE_REJECTED	Correct the supplied references or their relationship to the story
MV_NATIVE_REFERENCE_REVIEW_UNAVAILABLE	Wait; after terminal failure, consider a new attempt and verify settlement
MV_NATIVE_PREPARATION_REPAIR_EXHAUSTED	System-created materials could not be repaired within the limit; inspect settlement and the terminal retry recommendation
MV_NATIVE_PREPARATION_REPAIR_UNCERTAIN	Preparation purchase outcome could not be confirmed; while the Task is active, keep observing it. After failure, verify settlement before deciding on a new attempt
MV_NATIVE_REFERENCE_INPUT_REQUIRED	Replace the explicitly supplied identity image with a clearer image; an absent optional portrait is not the cause

For MV_NATIVE_PREPARATION_REPAIR_EXHAUSTED and MV_NATIVE_PREPARATION_REPAIR_UNCERTAIN, the workflow issue identifies a platform preparation failure before video generation. Its retry advice does not confirm a refund: verify billing.settlement, billing.refunded and the ledger. A failed Task with 195 credits debited and 195 refunded has a net charge of 0.

Preparation repairs do not add customer charges. A service preparation failure does not mean the customer must supply a portrait. For other errors, use the MV error reference and the Task’s retryable field. See idempotency rules for account/key scope and unknown outcomes.

Verify credit settlement

Read the ledger with task:read, and match the operation’s taskId:

curl --fail-with-body "https://api.omnapi.com/api/v1/mv/$MV_ID/operations" \
  -H "x-api-key: $OMNAPI_KEY" > omn-operations.json
jq --arg taskId "$TASK_ID" '.items[] | select(.taskId == $taskId)' omn-operations.json

Use the edit or upgrade Task ID for those purchases, not the original creation Task ID. A limited ledger response or a not-yet-readable MV is not proof of no charge; retain the Task receipt and query that Task as well.

Ledger field	How to use it
taskStatus	Execution state, independent of settlement
settlementStatus: "PENDING"	Amounts are not final; keep checking settlement even if execution failed
settlementStatus: "REFUNDED"	Full-refund settlement; check the returned amount
settlementStatus: "CHARGED"	Settled charge; can include a partial refund, so inspect both refund and net amounts
chargedCredits	Original amount deducted for this operation
refundedCredits	Credits returned for this operation
netCredits	Amount remaining charged; do not subtract refundedCredits from it again
authorizedCredits	Purchase authorization ceiling, not necessarily the amount deducted

For a hypothetical 570-credit purchase, these are three alternative HTTP 200 ledger response excerpts, not three charges for the same request.

Failed execution, settlement still pending: do not tell the customer that 570 credits have already been returned.

{
  "items": [{
    "taskId": "0199a000-0000-7000-8000-000000000001",
    "operation": "create",
    "taskStatus": "FAILED",
    "settlementStatus": "PENDING",
    "chargedCredits": 570,
    "refundedCredits": 0,
    "netCredits": 570
  }]
}

Full refund complete: execution stays failed; the credit outcome changes.

{
  "items": [{
    "taskId": "0199a000-0000-7000-8000-000000000001",
    "operation": "create",
    "taskStatus": "FAILED",
    "settlementStatus": "REFUNDED",
    "chargedCredits": 570,
    "refundedCredits": 570,
    "netCredits": 0
  }]
}

Video delivered, 10-credit paid subtitle component not delivered: the Task stays successful and only that component is refunded.

{
  "items": [{
    "taskId": "0199a000-0000-7000-8000-000000000001",
    "operation": "create",
    "taskStatus": "COMPLETED",
    "settlementStatus": "CHARGED",
    "chargedCredits": 570,
    "refundedCredits": 10,
    "netCredits": 560
  }]
}

In the third case, Task creditsRequired is 570 and final creditsCharged is 560. Task reports refunded: true, refundedCredits: 10, refundType: "partial", refundReason: "subtitle_not_delivered" and settlementStatus: "CHARGED". The MV’s billing reports the same refund amount, type and reason. CHARGED means a net charge remains; it does not rule out a partial refund. REFUNDED means full refund. While PENDING, the eventual refund is not confirmed.

refunded means some credits were returned, not that the entire order was free. Use refundType (none, partial, full) and amounts to distinguish them. Keep pricing.components as the purchased price snapshot; use settlement amounts for net spending rather than summing the original items after a refund. Never subtract refundedCredits again from Task creditsCharged.

If you also read GET /api/v1/tasks/{taskId}/workflow, billing.final says whether settlement is final; billing.settlement carries the settlement state. billing.debited, billing.refunded and billing.net are decimal strings in credits. They correspond to original debit, returned credits and net spend. Do not confuse workflow billing.refunded with the Task’s boolean refunded.

Continue settlement polling with bounded backoff when pending. No fixed refund arrival time is promised here. If it remains unresolved, contact support with taskId, mvId, X-Request-Id, timestamps and the settlement response; do not send your API key. A credit refund is not a cash refund of a top-up payment.

If a create Task fails without delivering a current final video, the MV view reports FAILED even when individual scene videos are ready. The final read reports ready: false, staleReason: "source_failed" and actionHint: "check_source"; it does not recommend buying finalize again. For EXPIRED or PROVIDER_PROCESSING_TIMEOUT, inspect the recorded failure and settlement, then wait for service recovery before considering a new request with a new idempotency key. Replaying the old key returns the same failed Task.

Cancellation requires task:cancel. Before submission, an eligible operation can be cancelled and refunded; after submission or when the outcome is unknown, a cancellation can return 409 and the Task continues. Keep polling it. Subjective creative dissatisfaction does not automatically cause a refund. Cancellation and retention.

Default engine

native.defaultEngine in capabilities reports whether requests that omit generation.engineVersion are evaluated for Omn V1 first. When enabled is true and contracts lists the purchase (oneclick-v1, premium-v2:perform, premium-v2:sing, premium-v2:sing_perform or premium-v2:dance), accounts included in rolloutPercent are evaluated for Omn V1 at its price. The rollout percentage defaults to zero and account selection is stable. The request stays on the existing engine when the account is outside the rollout or Omn V1 cannot admit it. Default-engine rules:

• An explicit engineVersion is never changed.
• A request without an explicit engine can move to Omn with a valid quoteId when Omn’s price fits under that quote. If maxCredits is also present, the lower limit applies.
• Reusing a saved preflight keeps its original engine, including older Vidu OneClick V1 or Premium V2 preflights issued before Omn rollout.
• With maxCredits, Omn V1 is used only when its price fits the limit.
• A quote without engineVersion still prices the existing engine; preflight returns the price that will apply.
• When the deployment has closed OneClick V2 on the existing engine, an implicit OneClick V2 request listed in contracts is still evaluated for Omn V1 first. It returns 503 MV_PROVIDER_UNAVAILABLE only when it stays on the existing engine.

To stay on the existing engines, set engineVersion to vidu-v1 or vidu-v2; MVView.generation.engineVersion reports the engine an MV used.

An implicit request moved to Omn keeps narrative planning when creativeMode is omitted or auto. Explicit creative modes retain their requested direction.

Capability-specific readiness

native.selectableContractDetails can include capabilityReadiness.narrative and capabilityReadiness.singing. Each reports configured supported, operational ready, and recent health (status, sampleCount, technicalFailureCount, circuit, lastFailureAt). A singing outage does not by itself disable narrative requests, and a narrative-only circuit does not close a healthy singing capability. When these fields are present, use the requested capability’s ready; the parent ready means at least one capability can accept work. unknown health means insufficient observations, not a healthy verdict. These fields are advisory; preflight and creation check the specific request again before charging. Reading capabilities does not create a generation.