Create MV

POST/api/v1/mv/Copy URL

Authentication · x-api-key

Create a Fast finished MV or Studio storyboard. The accepted response returns `taskId` and the same value as an immediately stable `mvId` alias, addressable through `viewUrl`; the resolved MVView may later expose the canonical project/storyboard id. Send an `Idempotency-Key` header to make retries safe — a duplicate key replays the original response without charging again. If maxCredits is present, the final create-time quote must not exceed it.

All endpointsRequestResponsesCode

Request

Idempotency-Keyheader · Optional

string

Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.

Maximum characters: 255.

Must match at least one alternative.

• Request · body · anyOf 1Alternative

  object

  Unknown fields are not accepted.

  19 fields

  • Request · body · anyOf 1.modeRequired

    "fast"

    Operation or product mode discriminator for this schema variant.

  • Request · body · anyOf 1.sourceRequired

    object

    Public source media or product reference.

    Must match at least one alternative.

    2 fields / alternatives

    • Request · body · anyOf 1.source · anyOf 1Alternative

      object

      Unknown fields are not accepted.

      4 fields

      • Request · body · anyOf 1.source · anyOf 1.clipIdRequired

        string

        Source clip identifier.

        Minimum characters: 1.

      • Request · body · anyOf 1.source · anyOf 1.typeRequired

        "suno"

        Source or product type discriminator.

      • Request · body · anyOf 1.source · anyOf 1.lyricsOptional

        string

        Lyrics or lyric context supplied to the operation.

        Maximum characters: 5000.

      • Request · body · anyOf 1.source · anyOf 1.rangeOptional

        object

        Optional source-media range.

        2 fields

        • Request · body · anyOf 1.source · anyOf 1.range.endSecOptional

          number

          Scene or source-range end time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 1.source · anyOf 1.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Request · body · anyOf 1.source · anyOf 1.range.startSecOptional

          number

          Scene or source-range start time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 1.source · anyOf 1.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

    • Request · body · anyOf 1.source · anyOf 2Alternative

      object

      Unknown fields are not accepted.

      7 fields

      • Request · body · anyOf 1.source · anyOf 2.audioUrlRequired

        string

        Public HTTP(S) audio URL.

        Format: uri.

      • Request · body · anyOf 1.source · anyOf 2.typeRequired

        "audio"

        Source or product type discriminator.

      • Request · body · anyOf 1.source · anyOf 2.durationSecOptional

        number

        Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.

        Exclusive lower bound: 0.

      • Request · body · anyOf 1.source · anyOf 2.lyricsOptional

        string

        Lyrics or lyric context supplied to the operation.

        Maximum characters: 5000.

      • Request · body · anyOf 1.source · anyOf 2.musicStyleOptional

        string

        Optional song genre, mood or musical style used to guide automatic visual planning.

        Maximum characters: 500.

      • Request · body · anyOf 1.source · anyOf 2.rangeOptional

        object

        Optional source-media range.

        2 fields

        • Request · body · anyOf 1.source · anyOf 2.range.endSecOptional

          number

          Scene or source-range end time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 1.source · anyOf 2.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Request · body · anyOf 1.source · anyOf 2.range.startSecOptional

          number

          Scene or source-range start time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 1.source · anyOf 2.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

      • Request · body · anyOf 1.source · anyOf 2.titleOptional

        string

        Optional song title used as creative context; does not force a visual style or performance mode.

        Maximum characters: 200.

  • Request · body · anyOf 1.aspectRatioOptional

    "16:9" | "9:16" | "1:1" | "4:3" | "3:4"

    Requested output aspect ratio.

    Must match at least one alternative.

    5 fields / alternatives

    • Request · body · anyOf 1.aspectRatio · anyOf 1Alternative

      "16:9"

    • Request · body · anyOf 1.aspectRatio · anyOf 2Alternative

      "9:16"

    • Request · body · anyOf 1.aspectRatio · anyOf 3Alternative

      "1:1"

    • Request · body · anyOf 1.aspectRatio · anyOf 4Alternative

      "4:3"

    • Request · body · anyOf 1.aspectRatio · anyOf 5Alternative

      "3:4"

  • Request · body · anyOf 1.characterImageOptional

    string

    Public character reference image URL.

    Minimum characters: 1.

  • Request · body · anyOf 1.configOptional

    object

    Standard task configuration: priority, tags, metadata, and webhookUrl.

    4 fields

    • Request · body · anyOf 1.config.metadataOptional

      object

      Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

    • Request · body · anyOf 1.config.priorityOptional

      number

      Task priority 1-10 (higher = sooner). Default 5.

      Minimum: 1. Maximum: 10. Default: 5.

    • Request · body · anyOf 1.config.tagsOptional

      array<string>

      Free-form labels for filtering. Up to 20, 100 chars each.

      Maximum items: 20.

      1 field

      • Request · body · anyOf 1.config.tags[]Each item

        string

        Maximum characters: 100.

    • Request · body · anyOf 1.config.webhookUrlOptional

      string

      URL to receive task.* lifecycle events via the central webhook service.

      Format: uri.

  • Request · body · anyOf 1.generationOptional

    object

    Product-specific generation controls.

    Unknown fields are not accepted.

    16 fields

    • Request · body · anyOf 1.generation.creativeModeOptional

      "auto" | "lyrics_story" | "prompt_story" | "mood_visual" | "performance" | "sing_dance" | "sing_play"

      Creative intent used by Fast MV prompt and reference planning.

      Must match at least one alternative.

      7 fields / alternatives

      • Request · body · anyOf 1.generation.creativeMode · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 2Alternative

        "lyrics_story"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 3Alternative

        "prompt_story"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 4Alternative

        "mood_visual"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 5Alternative

        "performance"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 6Alternative

        "sing_dance"

      • Request · body · anyOf 1.generation.creativeMode · anyOf 7Alternative

        "sing_play"

    • Request · body · anyOf 1.generation.engineVersionOptional

      "vidu-v1" | "vidu-v2" | "omn-v1"

      Explicit MV generation option. Check capabilities and preflight before selecting omn-v1; unsupported combinations fail before credit debit.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 1.generation.engineVersion · anyOf 1Alternative

        "vidu-v1"

      • Request · body · anyOf 1.generation.engineVersion · anyOf 2Alternative

        "vidu-v2"

      • Request · body · anyOf 1.generation.engineVersion · anyOf 3Alternative

        "omn-v1"

    • Request · body · anyOf 1.generation.lipReferenceImagesOptional

      array<string>

      Ordered singer portrait URLs for sing/sing_perform; optional on Omn V1 (a performer is generated when omitted), required on Vidu V2 unless characterImage is supplied. The first item maps to the first singer.

      Minimum items: 1. Maximum items: 2.

      1 field

      • Request · body · anyOf 1.generation.lipReferenceImages[]Each item

        string

        Minimum characters: 1.

    • Request · body · anyOf 1.generation.managedVersionOptional

      "oneclick-v1" | "premium-v2"

      Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.generation.managedVersion · anyOf 1Alternative

        "oneclick-v1"

      • Request · body · anyOf 1.generation.managedVersion · anyOf 2Alternative

        "premium-v2"

    • Request · body · anyOf 1.generation.motionPresetOptional

      "stable_performance" | "cinematic_light" | "dynamic_dance" | "lip_sync_closeup"

      Fast MV motion prompt policy.

      Must match at least one alternative.

      4 fields / alternatives

      • Request · body · anyOf 1.generation.motionPreset · anyOf 1Alternative

        "stable_performance"

      • Request · body · anyOf 1.generation.motionPreset · anyOf 2Alternative

        "cinematic_light"

      • Request · body · anyOf 1.generation.motionPreset · anyOf 3Alternative

        "dynamic_dance"

      • Request · body · anyOf 1.generation.motionPreset · anyOf 4Alternative

        "lip_sync_closeup"

    • Request · body · anyOf 1.generation.motionReferenceVideoOptional

      string

      Omn V1 Premium V2 dance only: public HTTPS URL of a motion reference video whose moves drive dance shots (render tiers draft/standard). Requires motionRightsConfirmed=true. The URL must declare its size (at most 128 MB) and, when it declares a content type, a video/* or application/octet-stream one; otherwise 400 VALIDATION_ERROR on this field. The video should be 2–660 seconds long with a short side of at least 240 px and a long side of at most 4096 px; its audio is not used (each dance shot uses a silent clip aligned to its song window, looping a shorter video). Motion transfer applies only to 16:9 and 9:16 MVs, and a 16:9 or 9:16 request is rejected with 422 MV_ENGINE_UNSUPPORTED (reason specialist_mode_unsupported) before any charge when motion transfer is unavailable; other aspect ratios, and videos that turn out to be unusable (unreachable, not decodable, or outside these bounds), dance without motion transfer at the same price.

      Minimum characters: 1.

    • Request · body · anyOf 1.generation.motionRightsConfirmedOptional

      true

      Required with motionReferenceVideo: you confirm you hold the rights to use the motion footage.

    • Request · body · anyOf 1.generation.performanceModeOptional

      "sing" | "sing_perform" | "perform" | "dance"

      Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance.

      Must match at least one alternative.

      4 fields / alternatives

      • Request · body · anyOf 1.generation.performanceMode · anyOf 1Alternative

        "sing"

      • Request · body · anyOf 1.generation.performanceMode · anyOf 2Alternative

        "sing_perform"

      • Request · body · anyOf 1.generation.performanceMode · anyOf 3Alternative

        "perform"

      • Request · body · anyOf 1.generation.performanceMode · anyOf 4Alternative

        "dance"

    • Request · body · anyOf 1.generation.promptModeOptional

      "auto" | "verbatim" | "creative_brief"

      Whether Fast MV preserves or compiles the caller prompt.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 1.generation.promptMode · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 1.generation.promptMode · anyOf 2Alternative

        "verbatim"

      • Request · body · anyOf 1.generation.promptMode · anyOf 3Alternative

        "creative_brief"

    • Request · body · anyOf 1.generation.qualityOptional

      "standard" | "high"

      Requested public quality tier.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.generation.quality · anyOf 1Alternative

        "standard"

      • Request · body · anyOf 1.generation.quality · anyOf 2Alternative

        "high"

    • Request · body · anyOf 1.generation.referenceStrategyOptional

      "direct" | "synthesize"

      Fast MV policy for direct or synthesized references.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.generation.referenceStrategy · anyOf 1Alternative

        "direct"

      • Request · body · anyOf 1.generation.referenceStrategy · anyOf 2Alternative

        "synthesize"

    • Request · body · anyOf 1.generation.renderTierOptional

      "draft" | "standard" | "hd" | "ultra"

      Omn V1 only. draft delivers 540p; standard 720p; hd 1080p; ultra 720p, 1080p or 1440p. When omitted: resolution=1440p or quality="high" selects ultra, standard quality selects draft at 540p and standard at 720p and hd at 1080p. Native shot rendering offers these tiers for both managed versions subject to capability and preflight checks. Dance motion transfer supports draft or standard only.

      Must match at least one alternative.

      4 fields / alternatives

      • Request · body · anyOf 1.generation.renderTier · anyOf 1Alternative

        "draft"

      • Request · body · anyOf 1.generation.renderTier · anyOf 2Alternative

        "standard"

      • Request · body · anyOf 1.generation.renderTier · anyOf 3Alternative

        "hd"

      • Request · body · anyOf 1.generation.renderTier · anyOf 4Alternative

        "ultra"

    • Request · body · anyOf 1.generation.scheduleOptional

      "standard" | "economy"

      Omn V1 only. economy renders shots only in the off-peak window at the same video price as standard scheduling, with a longer delivery window: shots start between 00:00 and 07:40 Beijing time (no new shot in the window's last 20 minutes, so none runs into peak pricing). MVView.generation.scheduleWindow reports the window the waiting shots are bought in; its offPeakEndsAt is the 08:00 window end.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.generation.schedule · anyOf 1Alternative

        "standard"

      • Request · body · anyOf 1.generation.schedule · anyOf 2Alternative

        "economy"

    • Request · body · anyOf 1.generation.styleOptional

      string

      Requested creative style direction.

      Maximum characters: 200.

    • Request · body · anyOf 1.generation.subtitleModeOptional

      "vidu" | "custom"

      Fast MV subtitle rendering mode.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.generation.subtitleMode · anyOf 1Alternative

        "vidu"

      • Request · body · anyOf 1.generation.subtitleMode · anyOf 2Alternative

        "custom"

    • Request · body · anyOf 1.generation.visualBoardOptional

      object

      Fast MV Visual Board configuration.

      Unknown fields are not accepted.

      2 fields

      • Request · body · anyOf 1.generation.visualBoard.imageProviderOptional

        "gpt-image-2" | "p-image" | "viduq2"

        Public image-generation option code.

        Must match at least one alternative.

        3 fields / alternatives

        • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 1Alternative

          "gpt-image-2"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 1See schema

            "gpt-image-2"

            Expand this value in the interactive reference.

        • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 2Alternative

          "p-image"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 2See schema

            "p-image"

            Expand this value in the interactive reference.

        • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 3Alternative

          "viduq2"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.imageProvider · anyOf 3See schema

            "viduq2"

            Expand this value in the interactive reference.

      • Request · body · anyOf 1.generation.visualBoard.presetOptional

        "auto" | "speed" | "detail" | "off"

        Visual Board speed/detail policy.

        Must match at least one alternative.

        4 fields / alternatives

        • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 1Alternative

          "auto"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 1See schema

            "auto"

            Expand this value in the interactive reference.

        • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 2Alternative

          "speed"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 2See schema

            "speed"

            Expand this value in the interactive reference.

        • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 3Alternative

          "detail"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 3See schema

            "detail"

            Expand this value in the interactive reference.

        • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 4Alternative

          "off"
          1 field

          • Request · body · anyOf 1.generation.visualBoard.preset · anyOf 4See schema

            "off"

            Expand this value in the interactive reference.

  • Request · body · anyOf 1.languageOptional

    "auto" | "en" | "zh"

    Requested or known language code/name.

    Must match at least one alternative.

    3 fields / alternatives

    • Request · body · anyOf 1.language · anyOf 1Alternative

      "auto"

    • Request · body · anyOf 1.language · anyOf 2Alternative

      "en"

    • Request · body · anyOf 1.language · anyOf 3Alternative

      "zh"

  • Request · body · anyOf 1.lipSyncOptional

    boolean

    Whether the MV should use the supported lip-sync workflow.

  • Request · body · anyOf 1.maxCreditsOptional

    number

    Maximum OmnAPI credits authorized for this paid request.

    Minimum: 1.

  • Request · body · anyOf 1.preflightIdOptional

    string

    Reusable MV preflight snapshot identifier.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 1.promptOptional

    string

    Primary creative or operation instruction.

    Maximum characters: 3000.

  • Request · body · anyOf 1.quoteIdOptional

    string

    Short-lived quote identifier for the matching paid operation.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 1.referenceImagesOptional

    array<string>

    Public reference image URLs.

    Maximum items: 7.

    1 field

    • Request · body · anyOf 1.referenceImages[]Each item

      string

      Minimum characters: 1.

  • Request · body · anyOf 1.resolutionOptional

    "540p" | "720p" | "1080p" | "1440p"

    Delivery resolution. Default 540p. 1440p is available only with generation.engineVersion="omn-v1"; other engines return MV_RESOLUTION_INVALID.

    Must match at least one alternative.

    4 fields / alternatives

    • Request · body · anyOf 1.resolution · anyOf 1Alternative

      "540p"

    • Request · body · anyOf 1.resolution · anyOf 2Alternative

      "720p"

    • Request · body · anyOf 1.resolution · anyOf 3Alternative

      "1080p"

    • Request · body · anyOf 1.resolution · anyOf 4Alternative

      "1440p"

  • Request · body · anyOf 1.srtUrlOptional

    string

    Public URL of caller-supplied SRT subtitles.

    Minimum characters: 1.

  • Request · body · anyOf 1.subtitleOptional

    object

    MV subtitle generation and fallback policy.

    Unknown fields are not accepted.

    6 fields

    • Request · body · anyOf 1.subtitle.fallbackOptional

      "fail" | "continue_without_subtitles"

      Behavior when the preferred subtitle path cannot complete.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.subtitle.fallback · anyOf 1Alternative

        "fail"

      • Request · body · anyOf 1.subtitle.fallback · anyOf 2Alternative

        "continue_without_subtitles"

    • Request · body · anyOf 1.subtitle.languageOptional

      "auto" | "en" | "zh"

      Requested or known language code/name.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 1.subtitle.language · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 1.subtitle.language · anyOf 2Alternative

        "en"

      • Request · body · anyOf 1.subtitle.language · anyOf 3Alternative

        "zh"

    • Request · body · anyOf 1.subtitle.maxCostUsdPerMinOptional

      number

      Maximum accepted public subtitle price in USD per minute.

      Minimum: 0.001. Maximum: 1.

    • Request · body · anyOf 1.subtitle.modeOptional

      "auto" | "provided" | "off"

      Operation or product mode discriminator for this schema variant.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 1.subtitle.mode · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 1.subtitle.mode · anyOf 2Alternative

        "provided"

      • Request · body · anyOf 1.subtitle.mode · anyOf 3Alternative

        "off"

    • Request · body · anyOf 1.subtitle.qualityOptional

      "standard" | "premium"

      Requested public quality tier.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 1.subtitle.quality · anyOf 1Alternative

        "standard"

      • Request · body · anyOf 1.subtitle.quality · anyOf 2Alternative

        "premium"

    • Request · body · anyOf 1.subtitle.requiredOptional

      boolean

      Whether the selected subtitle policy must succeed.

  • Request · body · anyOf 1.subtitleColorOptional

    string

    Requested subtitle foreground color.

    Maximum characters: 20.

  • Request · body · anyOf 1.subtitlesOptional

    boolean

    Whether subtitles are enabled for the MV.

  • Request · body · anyOf 1.titleOptional

    string

    Optional customer-facing title.

    Maximum characters: 200.

• Request · body · anyOf 2Alternative

  object

  Unknown fields are not accepted.

  19 fields

  • Request · body · anyOf 2.modeRequired

    "studio"

    Operation or product mode discriminator for this schema variant.

  • Request · body · anyOf 2.sourceRequired

    object

    Public source media or product reference.

    Must match at least one alternative.

    2 fields / alternatives

    • Request · body · anyOf 2.source · anyOf 1Alternative

      object

      Unknown fields are not accepted.

      4 fields

      • Request · body · anyOf 2.source · anyOf 1.clipIdRequired

        string

        Source clip identifier.

        Minimum characters: 1.

      • Request · body · anyOf 2.source · anyOf 1.typeRequired

        "suno"

        Source or product type discriminator.

      • Request · body · anyOf 2.source · anyOf 1.lyricsOptional

        string

        Lyrics or lyric context supplied to the operation.

        Maximum characters: 5000.

      • Request · body · anyOf 2.source · anyOf 1.rangeOptional

        object

        Optional source-media range.

        2 fields

        • Request · body · anyOf 2.source · anyOf 1.range.endSecOptional

          number

          Scene or source-range end time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 2.source · anyOf 1.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Request · body · anyOf 2.source · anyOf 1.range.startSecOptional

          number

          Scene or source-range start time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 2.source · anyOf 1.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

    • Request · body · anyOf 2.source · anyOf 2Alternative

      object

      Unknown fields are not accepted.

      7 fields

      • Request · body · anyOf 2.source · anyOf 2.audioUrlRequired

        string

        Public HTTP(S) audio URL.

        Format: uri.

      • Request · body · anyOf 2.source · anyOf 2.typeRequired

        "audio"

        Source or product type discriminator.

      • Request · body · anyOf 2.source · anyOf 2.durationSecOptional

        number

        Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.

        Exclusive lower bound: 0.

      • Request · body · anyOf 2.source · anyOf 2.lyricsOptional

        string

        Lyrics or lyric context supplied to the operation.

        Maximum characters: 5000.

      • Request · body · anyOf 2.source · anyOf 2.musicStyleOptional

        string

        Optional song genre, mood or musical style used to guide automatic visual planning.

        Maximum characters: 500.

      • Request · body · anyOf 2.source · anyOf 2.rangeOptional

        object

        Optional source-media range.

        2 fields

        • Request · body · anyOf 2.source · anyOf 2.range.endSecOptional

          number

          Scene or source-range end time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 2.source · anyOf 2.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Request · body · anyOf 2.source · anyOf 2.range.startSecOptional

          number

          Scene or source-range start time in seconds.

          Minimum: 0.

          1 field

          • Request · body · anyOf 2.source · anyOf 2.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

      • Request · body · anyOf 2.source · anyOf 2.titleOptional

        string

        Optional song title used as creative context; does not force a visual style or performance mode.

        Maximum characters: 200.

  • Request · body · anyOf 2.aspectRatioOptional

    "16:9" | "9:16" | "1:1" | "4:3" | "3:4"

    Requested output aspect ratio.

    Must match at least one alternative.

    5 fields / alternatives

    • Request · body · anyOf 2.aspectRatio · anyOf 1Alternative

      "16:9"

    • Request · body · anyOf 2.aspectRatio · anyOf 2Alternative

      "9:16"

    • Request · body · anyOf 2.aspectRatio · anyOf 3Alternative

      "1:1"

    • Request · body · anyOf 2.aspectRatio · anyOf 4Alternative

      "4:3"

    • Request · body · anyOf 2.aspectRatio · anyOf 5Alternative

      "3:4"

  • Request · body · anyOf 2.characterImageOptional

    string

    Public character reference image URL.

    Minimum characters: 1.

  • Request · body · anyOf 2.configOptional

    object

    Standard task configuration: priority, tags, metadata, and webhookUrl.

    4 fields

    • Request · body · anyOf 2.config.metadataOptional

      object

      Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

    • Request · body · anyOf 2.config.priorityOptional

      number

      Task priority 1-10 (higher = sooner). Default 5.

      Minimum: 1. Maximum: 10. Default: 5.

    • Request · body · anyOf 2.config.tagsOptional

      array<string>

      Free-form labels for filtering. Up to 20, 100 chars each.

      Maximum items: 20.

      1 field

      • Request · body · anyOf 2.config.tags[]Each item

        string

        Maximum characters: 100.

    • Request · body · anyOf 2.config.webhookUrlOptional

      string

      URL to receive task.* lifecycle events via the central webhook service.

      Format: uri.

  • Request · body · anyOf 2.generationOptional

    object

    Product-specific generation controls.

    Unknown fields are not accepted.

    3 fields

    • Request · body · anyOf 2.generation.imageProviderOptional

      "p-image" | "gpt-image-2" | "viduq2"

      Public image-generation option code.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 2.generation.imageProvider · anyOf 1Alternative

        "p-image"

      • Request · body · anyOf 2.generation.imageProvider · anyOf 2Alternative

        "gpt-image-2"

      • Request · body · anyOf 2.generation.imageProvider · anyOf 3Alternative

        "viduq2"

    • Request · body · anyOf 2.generation.videoModelOptional

      string

      Public scene-video model code.

      Maximum characters: 100.

    • Request · body · anyOf 2.generation.videoProviderOptional

      "p-video" | "hailuo" | "minimax-h3" | "vidu"

      Public scene-video option code.

      Must match at least one alternative.

      4 fields / alternatives

      • Request · body · anyOf 2.generation.videoProvider · anyOf 1Alternative

        "p-video"

      • Request · body · anyOf 2.generation.videoProvider · anyOf 2Alternative

        "hailuo"

      • Request · body · anyOf 2.generation.videoProvider · anyOf 3Alternative

        "minimax-h3"

      • Request · body · anyOf 2.generation.videoProvider · anyOf 4Alternative

        "vidu"

  • Request · body · anyOf 2.languageOptional

    "auto" | "en" | "zh"

    Requested or known language code/name.

    Must match at least one alternative.

    3 fields / alternatives

    • Request · body · anyOf 2.language · anyOf 1Alternative

      "auto"

    • Request · body · anyOf 2.language · anyOf 2Alternative

      "en"

    • Request · body · anyOf 2.language · anyOf 3Alternative

      "zh"

  • Request · body · anyOf 2.lipSyncOptional

    boolean

    Whether the MV should use the supported lip-sync workflow.

  • Request · body · anyOf 2.maxCreditsOptional

    number

    Maximum OmnAPI credits authorized for this paid request.

    Minimum: 1.

  • Request · body · anyOf 2.preflightIdOptional

    string

    Reusable MV preflight snapshot identifier.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 2.promptOptional

    string

    Primary creative or operation instruction.

    Maximum characters: 3000.

  • Request · body · anyOf 2.quoteIdOptional

    string

    Short-lived quote identifier for the matching paid operation.

    Minimum characters: 1. Maximum characters: 100.

  • Request · body · anyOf 2.referenceImagesOptional

    array<string>

    Public reference image URLs.

    Maximum items: 7.

    1 field

    • Request · body · anyOf 2.referenceImages[]Each item

      string

      Minimum characters: 1.

  • Request · body · anyOf 2.resolutionOptional

    "540p" | "720p" | "1080p" | "1440p"

    Delivery resolution. Default 540p. 1440p is available only with generation.engineVersion="omn-v1"; other engines return MV_RESOLUTION_INVALID.

    Must match at least one alternative.

    4 fields / alternatives

    • Request · body · anyOf 2.resolution · anyOf 1Alternative

      "540p"

    • Request · body · anyOf 2.resolution · anyOf 2Alternative

      "720p"

    • Request · body · anyOf 2.resolution · anyOf 3Alternative

      "1080p"

    • Request · body · anyOf 2.resolution · anyOf 4Alternative

      "1440p"

  • Request · body · anyOf 2.srtUrlOptional

    string

    Public URL of caller-supplied SRT subtitles.

    Minimum characters: 1.

  • Request · body · anyOf 2.subtitleOptional

    object

    MV subtitle generation and fallback policy.

    Unknown fields are not accepted.

    6 fields

    • Request · body · anyOf 2.subtitle.fallbackOptional

      "fail" | "continue_without_subtitles"

      Behavior when the preferred subtitle path cannot complete.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 2.subtitle.fallback · anyOf 1Alternative

        "fail"

      • Request · body · anyOf 2.subtitle.fallback · anyOf 2Alternative

        "continue_without_subtitles"

    • Request · body · anyOf 2.subtitle.languageOptional

      "auto" | "en" | "zh"

      Requested or known language code/name.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 2.subtitle.language · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 2.subtitle.language · anyOf 2Alternative

        "en"

      • Request · body · anyOf 2.subtitle.language · anyOf 3Alternative

        "zh"

    • Request · body · anyOf 2.subtitle.maxCostUsdPerMinOptional

      number

      Maximum accepted public subtitle price in USD per minute.

      Minimum: 0.001. Maximum: 1.

    • Request · body · anyOf 2.subtitle.modeOptional

      "auto" | "provided" | "off"

      Operation or product mode discriminator for this schema variant.

      Must match at least one alternative.

      3 fields / alternatives

      • Request · body · anyOf 2.subtitle.mode · anyOf 1Alternative

        "auto"

      • Request · body · anyOf 2.subtitle.mode · anyOf 2Alternative

        "provided"

      • Request · body · anyOf 2.subtitle.mode · anyOf 3Alternative

        "off"

    • Request · body · anyOf 2.subtitle.qualityOptional

      "standard" | "premium"

      Requested public quality tier.

      Must match at least one alternative.

      2 fields / alternatives

      • Request · body · anyOf 2.subtitle.quality · anyOf 1Alternative

        "standard"

      • Request · body · anyOf 2.subtitle.quality · anyOf 2Alternative

        "premium"

    • Request · body · anyOf 2.subtitle.requiredOptional

      boolean

      Whether the selected subtitle policy must succeed.

  • Request · body · anyOf 2.subtitleColorOptional

    string

    Requested subtitle foreground color.

    Maximum characters: 20.

  • Request · body · anyOf 2.subtitlesOptional

    boolean

    Whether subtitles are enabled for the MV.

  • Request · body · anyOf 2.titleOptional

    string

    Optional customer-facing title.

    Maximum characters: 200.

Responses

200 OK

application/json

• Response 200 · autoFinalizeRequired

  boolean

• Response 200 · creditsRequiredRequired

  number

  Minimum: 0.

• Response 200 · deliveryStatusRequired

  "drafting" | "incomplete" | "rendering" | "packaging" | "ready" | "failed"

• Response 200 · finalUrlRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · finalUrl · anyOf 1Alternative

    string

  • Response 200 · finalUrl · anyOf 2Alternative

    null

• Response 200 · linksRequired

  object

  Unknown fields are not accepted.

  4 fields

  • Response 200 · links.finalRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.final · anyOf 1Alternative

      string

      Final downloadable resource URL when available

    • Response 200 · links.final · anyOf 2Alternative

      null

  • Response 200 · links.resourceRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.resource · anyOf 1Alternative

      string

      Product resource URL when the product has a dedicated view endpoint

    • Response 200 · links.resource · anyOf 2Alternative

      null

  • Response 200 · links.streamRequired

    string

    Task SSE stream URL for the created task

  • Response 200 · links.taskRequired

    string

    Task polling URL for the created task

• Response 200 · modeRequired

  "fast" | "studio"

• Response 200 · mvIdRequired

  string

• Response 200 · pollUrlRequired

  string

• Response 200 · pricingRequired

  object

  Unknown fields are not accepted.

  9 fields

  • Response 200 · pricing.adjustmentCreditsRequired

    number

    chargedCredits - baseCredits

  • Response 200 · pricing.baseCreditsRequired

    number

    Standard quoted credits before customer pricing adjustment

  • Response 200 · pricing.chargedCreditsRequired

    number

    Credits charged for this create request

    Minimum: 0.

  • Response 200 · pricing.quoteVersionRequired

    number

    Pricing quote version stored with the task

  • Response 200 · pricing.sourceRequired

    "standard" | "customer_rule"

    Public pricing source category

  • Response 200 · pricing.billingIncrementCreditsOptional

    number

    Smallest customer charge increment

    Minimum: 0.0001.

  • Response 200 · pricing.calculatedCreditsOptional

    number

    Precise whole-order subtotal before settlement rounding

  • Response 200 · pricing.settlementPolicyVersionOptional

    string

    Versioned customer settlement policy

  • Response 200 · pricing.settlementRoundingCreditsOptional

    number

    Whole-order rounding adjustment added at settlement

    Minimum: 0.

• Response 200 · productRequired

  object

  Unknown fields are not accepted.

  7 fields

  • Response 200 · product.featureCodeRequired

    string

    Resolved feature code

  • Response 200 · product.modelCodeRequired

    string

    Resolved model code

  • Response 200 · product.providerCodeRequired

    string

    Resolved provider code

  • Response 200 · product.resourceIdRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.resourceId · anyOf 1Alternative

      string

      Product resource id when created synchronously

    • Response 200 · product.resourceId · anyOf 2Alternative

      null

  • Response 200 · product.typeRequired

    string

    Product family for this task, e.g. suno, producer, mv

  • Response 200 · product.autoFinalizeOptional

    boolean

    Whether the product should finalize automatically

  • Response 200 · product.deliveryStatusOptional

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.deliveryStatus · anyOf 1Alternative

      string

      Product-level delivery status when applicable

    • Response 200 · product.deliveryStatus · anyOf 2Alternative

      null

• Response 200 · requestIdRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · requestId · anyOf 1Alternative

    string

    Request id echoed from X-Request-Id or generated by API

  • Response 200 · requestId · anyOf 2Alternative

    null

• Response 200 · statusRequired

  "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED"

• Response 200 · taskIdRequired

  string

• Response 200 · viewUrlRequired

  string

• Response 200 · warningCodesRequired

  array<string>
  1 field

  • Response 200 · warningCodes[]Each item

    string

    MV advisory warning codes. Non-fatal: the request still succeeds; these flag degraded, adjusted, or automatically recovered inputs and are projected into public Task warningCodes. Omn review codes (MV_NATIVE_CREATIVE_*, MV_NATIVE_SHOT_INTERNAL_CUT, MV_NATIVE_FRAME_BORDERS) describe the delivered video; their observations and affected scenes are in `quality` of GET /api/v1/tasks/{taskId}/workflow.

• Response 200 · estimatedCompletionTimeOptional

  Date | string | number | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · estimatedCompletionTime · anyOf 1Alternative

    Date | string | number

    Estimated completion time

    Must match at least one alternative.

    4 fields / alternatives

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 1Alternative

      Date

      Estimated completion time

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 2Alternative

      string

      Format: date-time.

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 3Alternative

      string

      Format: date.

    • Response 200 · estimatedCompletionTime · anyOf 1 · anyOf 4Alternative

      number

  • Response 200 · estimatedCompletionTime · anyOf 2Alternative

    null

400 Bad Request

application/json

• Response 400 · errorRequired

  object
  3 fields

  • Response 400 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 400 · error.messageRequired

    string

    Human readable error message

  • Response 400 · error.detailsOptional

    object

    Additional error details (optional)

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

• Response 401 · errorRequired

  object
  3 fields

  • Response 401 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 401 · error.messageRequired

    string

    Human readable error message

  • Response 401 · error.detailsOptional

    object

    Additional error details (optional)

• Response 401 · successRequired

  false

  Always false for error responses

402 Payment Required

application/json

• Response 402 · errorRequired

  object
  3 fields

  • Response 402 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 402 · error.messageRequired

    string

    Human readable error message

  • Response 402 · error.detailsOptional

    object

    Additional error details (optional)

• Response 402 · successRequired

  false

  Always false for error responses

403 Forbidden

Response for status 403 Forbidden: API-key scope/IP restrictions or billing hold. A positive balance does not bypass payment review. Check GET /api/v1/account/credits billingStatus before further paid requests.

application/json

• Response 403 · errorRequired

  object
  3 fields

  • Response 403 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 403 · error.messageRequired

    string

    Human readable error message

  • Response 403 · error.detailsOptional

    object

    Additional error details (optional)

• Response 403 · successRequired

  false

  Always false for error responses

409 Conflict

application/json

• Response 409 · errorRequired

  object
  3 fields

  • Response 409 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 409 · error.messageRequired

    string

    Human readable error message

  • Response 409 · error.detailsOptional

    object

    Additional error details (optional)

• Response 409 · successRequired

  false

  Always false for error responses

413 Payload Too Large

application/json

• Response 413 · errorRequired

  object
  3 fields

  • Response 413 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 413 · error.messageRequired

    string

    Human readable error message

  • Response 413 · error.detailsOptional

    object

    Additional error details (optional)

• Response 413 · successRequired

  false

  Always false for error responses

422 Unprocessable Entity

application/json

• Response 422 · errorRequired

  object
  3 fields

  • Response 422 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 422 · error.messageRequired

    string

    Human readable error message

  • Response 422 · error.detailsOptional

    object

    Additional error details (optional)

• Response 422 · successRequired

  false

  Always false for error responses

429 Too Many Requests

Request allowance or task admission capacity exceeded. Follow Retry-After when present; otherwise wait for active tasks and use bounded backoff. Limits do not guarantee throughput. For SSE, this is the HTTP connection response, not an event.

application/json

• Response 429 · errorRequired

  object
  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

  • Response 429 · error.detailsOptional

    object

    Optional and scope-dependent. Request limits supply scope/policy/type/limit/current/retryAfterSec. Task admission supplies inFlight/limit/tier, plus scope=apiKey for a key cap. IP rejection can omit details. In-flight rejection does not promise Retry-After.

    8 fields

    • Response 429 · error.details.currentOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

      "user" | "api-key" | "ip" | "apiKey"

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

• Response 429 · successRequired

  false

  Default: false.

500 Internal Server Error

application/json

• Response 500 · errorRequired

  object
  3 fields

  • Response 500 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 500 · error.messageRequired

    string

    Human readable error message

  • Response 500 · error.detailsOptional

    object

    Additional error details (optional)

• Response 500 · successRequired

  false

  Always false for error responses

502 Bad Gateway

application/json

• Response 502 · errorRequired

  object
  3 fields

  • Response 502 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 502 · error.messageRequired

    string

    Human readable error message

  • Response 502 · error.detailsOptional

    object

    Additional error details (optional)

• Response 502 · successRequired

  false

  Always false for error responses

503 Service Unavailable

application/json

• Response 503 · errorRequired

  object
  3 fields

  • Response 503 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 503 · error.messageRequired

    string

    Human readable error message

  • Response 503 · error.detailsOptional

    object

    Additional error details (optional)

• Response 503 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request POST \
  --url 'https://api.omnapi.com/api/v1/mv/' \
  --header "x-api-key: $OMNAPI_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json

Node.js

import { readFile } from "node:fs/promises";
const response = await fetch("https://api.omnapi.com/api/v1/mv/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
    "Idempotency-Key": process.env.IDEMPOTENCY_KEY,
    "Content-Type": "application/json",
  },
  body: await readFile("request.json", "utf8"),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os, json
import requests

response = requests.request(
    "POST", "https://api.omnapi.com/api/v1/mv/",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
        "Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
    },
    json=json.load(open("request.json")),
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables. Save your JSON body as request.json. Reuse the same IDEMPOTENCY_KEY and body on retries.

Interactive API Explorer → · OpenAPI JSON