Music Video · Omn on API v1
This page is for integrations that create MVs through /api/v1/mv and want Omn
without changing their request format: add generation.engineVersion: "omn-v1"
to a OneClick request. Omn plans and renders the whole song in one pass and
delivers native 480p/768p or AI-upscaled 1080p/1440p (2K). New integrations can use
the resource API on /api/v2/mv; see Music Video. Keep each MV
on the API version that created it — changing the URL does not migrate it.
Select Omn on API v1
Section titled “Select Omn on API v1”| Field | Value | Notes |
|---|---|---|
mode | "fast" | Studio has no Omn option |
generation.engineVersion | "omn-v1" | Omn; omit for OneClick |
resolution | omitted, 480p, 540p, 720p, 768p, 1080p, 1440p | Omitted or 540p is delivered at 480p; 720p at 768p (MV_OMN_RESOLUTION_MAPPED). 1080p and 1440p are AI-upscaled from 768p |
generation.quality | standard (default) | high returns 400 MV_RESOLUTION_INVALID |
aspectRatio | 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 | HD delivery keeps the selected aspect ratio. API v2 also offers 5:4, 4:5 and 9:21 |
lipSync | boolean | true sings with the performer in characterImage (or one generation.lipReferenceImages entry) |
generation.creativeMode | auto, lyrics_story, prompt_story, mood_visual, performance | Non-singing direction |
Not available on Omn (rejected before any charge): two singers,
generation.performanceMode dance or perform, sing_dance and sing_play,
generation.motionReferenceVideo, generation.schedule: "economy", and a
generation.renderTier that contradicts resolution (the resolution alone decides
the price).
Your account administrator can also switch an API key so that its requests
without generation.engineVersion are bought as Omn. Requests Omn cannot
serve then use OneClick before any charge, or fail, depending on the key’s
setting. Explicit engineVersion values are never changed.
OmnAPI can also buy a share of requests without generation.engineVersion as
Omn. The choice is fixed per API key and request body, so a retry or a create
after preflight gets the same answer, and it is kept in the preflight. Such a
request is priced, delivered and settled as Omn (540p as 480p, 720p as 768p, with
MV_OMN_RESOLUTION_MAPPED); if Omn cannot take it, it is prepared as OneClick
before any charge. Requests with a quoteId from POST /api/v1/mv/quote are not
affected. Send generation.engineVersion: "vidu-v1" to always buy OneClick.
Create an Omn V1 MV
Section titled “Create an Omn V1 MV”Use the normal OneClick flow — POST /api/v1/mv/preflight, then POST /api/v1/mv
with preflightId, maxCredits and an Idempotency-Key — with the extra field:
{ "mode": "fast", "source": { "type": "audio", "audioUrl": "https://media.example.com/song.mp3" }, "prompt": "A singer under neon rain, intimate close-ups", "aspectRatio": "9:16", "resolution": "720p", "lipSync": true, "characterImage": "https://media.example.com/singer.png", "subtitles": true, "subtitle": { "mode": "auto" }, "generation": { "engineVersion": "omn-v1" }}The preflight returns warningCodes: ["MV_OMN_RESOLUTION_MAPPED"] and the price
of a 768p Omn video. Poll the Task and read GET /api/v1/mv/{mvId}/final as for
OneClick.
Creative options
Section titled “Creative options”- Singing (
lipSync: true): one performer, who must be shown incharacterImageor the firstgeneration.lipReferenceImagesentry. Scene or style images alone are not enough: the request returns400withdetails.reason: execution_center_reference_requiredbefore any charge. - Without singing: Omn chooses a performer, a character or no people from the song and your prompt. Reference images are optional; when you send them they guide style and places.
- Captions: as for OneClick (
subtitles,subtitle,srtUrl). Automatic captions are included in the price. promptis limited to 3,000 characters, and the prompt plus the instructions Omn derives from your other fields must fit 4,000; longer requests return400before any charge.
Pricing
Section titled “Pricing”| Resolution | Credits / second | 60 s video |
|---|---|---|
| 480p (OneClick 540p or omitted) | 9 | 540 |
| 768p (OneClick 720p) | 12 | 720 |
| 1080p (AI-upscaled) | 20 | 1,200 |
| 1440p / 2K (AI-upscaled) | 48 | 2,880 |
Billed per effective output second, rounded up, 10–600 seconds. Planning,
reference images and captions are included; customer discounts do not apply.
maxCredits caps the charge as for OneClick.
Capabilities and admission
Section titled “Capabilities and admission”GET /api/v1/mv/capabilities lists Omn under the native key; its
selectableContractDetails.oneclickV1 object shows the resolutions (480p, 768p,
1080p, 1440p), aspect ratios and singing for one performer. Whether 1080p/1440p
can be bought right now is shown by availableResolutions on
GET /api/v2/mv/capabilities. Preflight is the authority for a concrete request.
| Error | Meaning |
|---|---|
400 MV_RESOLUTION_INVALID | High quality, an unsupported resolution, or a generation.renderTier that contradicts resolution |
422 MV_ENGINE_UNSUPPORTED | A mode Omn does not sell (details.reason), for example two singers or dance |
400 VALIDATION_ERROR (execution_center_reference_required) | Singing without a performer image |
503 MV_PROVIDER_UNAVAILABLE (capacity_unavailable) | Omn is rendering as many videos as it can; retry after Retry-After (60 s). Nothing is charged |
Edits and upgrades
Section titled “Edits and upgrades”Omn videos bought from November 14, 2026 accept a prompt-only scene edit. The OneClick scene-edit calls keep their shape, but each edit creates a new video and leaves the original MV unchanged:
| Call on an Omn MV | Behavior |
|---|---|
POST /api/v1/mv/quote with step: "scene-edit" | Free quote for re-rendering that scene; priced as an Omn regenerate (rate × seconds the shot is on screen, at least 1) |
POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/render with prompt | Re-renders scene sceneIndex (zero-based, in the order of the delivered cut) and buys a new video. Send quoteId, maxCredits, expectedVersion and an Idempotency-Key as for OneClick. The receipt’s taskId is the new video; poll it to completion |
The same call with referenceImages or shotType | 422 MV_CENTER_EDIT_UNSUPPORTED before any charge |
PATCH /api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering | 422 MV_CENTER_EDIT_UNSUPPORTED: Omn keeps no older renderings to choose from |
POST /api/v1/mv/{mvId}/finalize (and a compose quote) | Free: a delivered video already contains its current shots, so the existing final is returned. Before delivery it returns 422 |
An edit is refused before any charge with 409 MV_CENTER_EDIT_REFUSED (for
example more than 15% of the shots) or 409 MV_CENTER_EDIT_IN_PROGRESS (another
edit of the same MV is running). A failed or cancelled edit is refunded in full.
Omn MVs bought before November 14, 2026 return 422 MV_CENTER_EDIT_UNSUPPORTED.
Recuts, attribute changes and candidates are on /api/v2/mv; see
Edit an Omn video.
Omn videos have no resolution upgrades.
POST /api/v1/mv/{mvId}/upgrade/preflight and POST /api/v1/mv/{mvId}/upgrade
remain for MVs bought before November 12, 2026 and reject new Omn videos.
HD delivery and refunds
Section titled “HD delivery and refunds”The 1080p / 1440p rates are whole-order prices, including upscaling from 768p.
A base render alone cannot complete an HD order. Missing HD delivery or a file
that does not match the purchased dimensions fails with MV_CENTER_HD_FAILED
and refunds the entire amount charged. Refund posting is asynchronous; check
refundedCredits on GET /api/v1/mv/{mvId}/operations. See HD delivery
for the resource API flow. The API value for 2K is 1440p.
Status, errors and settlement
Section titled “Status, errors and settlement”- Cancel with
POST /api/v1/mv/{mvId}/operations/{taskId}/cancel(scopetask:cancel). Once generation has started, the cancel succeeds only after generation confirms it stopped; otherwise you get409and the video continues and is charged normally. - A video that still fails quality review after automatic repairs fails with
MV_CENTER_QUALITY_FAILEDand is refunded in full. - Webhooks (
task.*,mv.ready,mv.failed) andGET /api/v1/tasks/{taskId}work exactly as for OneClick; links point at/api/v1/mv/{mvId}. - Technical failures are refunded automatically; check
GET /api/v1/mv/{mvId}/operationsforrefundedCredits.
Troubleshooting
Section titled “Troubleshooting”| Symptom | What to do |
|---|---|
MV_OMN_RESOLUTION_MAPPED warning | Expected when sending 540p or 720p; the video is 480p or 768p |
400 MV_RESOLUTION_INVALID | Use 480p, 768p, 1080p or 1440p; keep OneClick for High |
422 MV_ENGINE_UNSUPPORTED | Remove the option named in details.reason, or keep OneClick |
503 capacity_unavailable | Nothing was charged. Wait for Retry-After; if the preflight is still valid, repeat the create with the same Idempotency-Key and body, otherwise preflight again and use a new key |
Historical orders
Section titled “Historical orders”Omn MVs bought before November 12, 2026 keep the shot-based plan, render tier and price they were bought with; reading, cancelling and settling them is unchanged.
Looking for an earlier section?
- Choose creativeMode →
- Singing, performance and dance →
- Dance motion reference →
- References and Visual Board →
- Subtitles →
- Creative drafts →
- Render tiers and price →
- Order examples →
- Quote, preflight and maxCredits →
- Read the price card →
- Economy scheduling →
- Read capabilities →
- Check a specific combination →
- Default engine →
- Admission errors →
- Edit one shot →
- Upgrade to a higher render tier →
- Upgrade rejections →
- During generation →
- Queued delivery →
- Task error codes →
- Delivery and fallback warnings →
- Shot repairs at composition →
- Verify credit settlement →
- Select Omn V1 →
- 1. Check the requested capability →
- 2. Save and preflight the request →
- 3. Approve the amount and create once →
- 4. Wait for execution and settlement →
- 5. Read and save the final video →
- Next steps →
- Duration and long songs →
- Legacy request compatibility →
- Rejections →
- Read the highlight →
- Short clips and recovery →
- Omn on API v2 →
- API v2 →
- API v2: Select Omn →
- API v2: Create an Omn MV →
- API v2: 1. Check the requested capability →
- API v2: 2. Save and preflight the request →
- API v2: 3. Approve the amount and create once →
- API v2: 4. Wait for execution and settlement →
- API v2: 5. Read and save the final video →
- API v2: Short clips and recovery →
- API v2: Next steps →