Skip to content

    Music Video

    Music Video · Omn on API v1

    Supported compatibility APIOpen App ↗

    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.

    FieldValueNotes
    mode"fast"Studio has no Omn option
    generation.engineVersion"omn-v1"Omn; omit for OneClick
    resolutionomitted, 480p, 540p, 720p, 768p, 1080p, 1440pOmitted or 540p is delivered at 480p; 720p at 768p (MV_OMN_RESOLUTION_MAPPED). 1080p and 1440p are AI-upscaled from 768p
    generation.qualitystandard (default)high returns 400 MV_RESOLUTION_INVALID
    aspectRatio16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9HD delivery keeps the selected aspect ratio. API v2 also offers 5:4, 4:5 and 9:21
    lipSyncbooleantrue sings with the performer in characterImage (or one generation.lipReferenceImages entry)
    generation.creativeModeauto, lyrics_story, prompt_story, mood_visual, performanceNon-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.

    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.

    • Singing (lipSync: true): one performer, who must be shown in characterImage or the first generation.lipReferenceImages entry. Scene or style images alone are not enough: the request returns 400 with details.reason: execution_center_reference_required before 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.
    • prompt is limited to 3,000 characters, and the prompt plus the instructions Omn derives from your other fields must fit 4,000; longer requests return 400 before any charge.
    ResolutionCredits / second60 s video
    480p (OneClick 540p or omitted)9540
    768p (OneClick 720p)12720
    1080p (AI-upscaled)201,200
    1440p / 2K (AI-upscaled)482,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.

    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.

    ErrorMeaning
    400 MV_RESOLUTION_INVALIDHigh quality, an unsupported resolution, or a generation.renderTier that contradicts resolution
    422 MV_ENGINE_UNSUPPORTEDA 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

    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 MVBehavior
    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 promptRe-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 shotType422 MV_CENTER_EDIT_UNSUPPORTED before any charge
    PATCH /api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering422 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.

    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.

    • Cancel with POST /api/v1/mv/{mvId}/operations/{taskId}/cancel (scope task:cancel). Once generation has started, the cancel succeeds only after generation confirms it stopped; otherwise you get 409 and the video continues and is charged normally.
    • A video that still fails quality review after automatic repairs fails with MV_CENTER_QUALITY_FAILED and is refunded in full.
    • Webhooks (task.*, mv.ready, mv.failed) and GET /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}/operations for refundedCredits.
    SymptomWhat to do
    MV_OMN_RESOLUTION_MAPPED warningExpected when sending 540p or 720p; the video is 480p or 768p
    400 MV_RESOLUTION_INVALIDUse 480p, 768p, 1080p or 1440p; keep OneClick for High
    422 MV_ENGINE_UNSUPPORTEDRemove the option named in details.reason, or keep OneClick
    503 capacity_unavailableNothing 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

    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.