Preflight MV create

POST/api/v1/mv/preflightCopy URL

Authentication · x-api-key

Validate MV create resources and return a reusable create-time estimate without creating a task or charging credits. The returned preflightId may be supplied to POST /api/v1/mv with the same media and generation body to reuse the validated snapshot. Create-time quoteId and maxCredits may be added or changed without invalidating media validation; final credits are determined immediately before task creation and maxCredits caps the authorized charge.

All endpointsRequestResponsesCode

Request

Must match at least one alternative.

• Request · body · anyOf 1Alternative

  object

  Unknown fields are not accepted.

  17 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.promptOptional

    string

    Primary creative or operation instruction.

    Maximum characters: 3000.

  • 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.

  17 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.promptOptional

    string

    Primary creative or operation instruction.

    Maximum characters: 3000.

  • 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

Unknown fields are not accepted.

• Response 200 · checksRequired

  object

  Unknown fields are not accepted.

  5 fields

  • Response 200 · checks.referenceImagesRequired

    array<object>
    1 field

    • Response 200 · checks.referenceImages[]Each item

      object
      8 fields

      • Response 200 · checks.referenceImages[].kindRequired

        string

      • Response 200 · checks.referenceImages[].statusRequired

        "ok"

      • Response 200 · checks.referenceImages[].clipIdOptional

        string

      • Response 200 · checks.referenceImages[].durationSecOptional

        number

      • Response 200 · checks.referenceImages[].processingModeOptional

        string

      • Response 200 · checks.referenceImages[].rangeOptional

        object
        2 fields

        • Response 200 · checks.referenceImages[].range.endSecOptional

          number

          Minimum: 0.

          1 field

          • Response 200 · checks.referenceImages[].range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Response 200 · checks.referenceImages[].range.startSecOptional

          number

          Minimum: 0.

          1 field

          • Response 200 · checks.referenceImages[].range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

      • Response 200 · checks.referenceImages[].sourceDurationSecOptional

        number

      • Response 200 · checks.referenceImages[].urlOptional

        string

  • Response 200 · checks.sourceRequired

    object
    8 fields

    • Response 200 · checks.source.kindRequired

      string

    • Response 200 · checks.source.statusRequired

      "ok"

    • Response 200 · checks.source.clipIdOptional

      string

    • Response 200 · checks.source.durationSecOptional

      number

    • Response 200 · checks.source.processingModeOptional

      string

    • Response 200 · checks.source.rangeOptional

      object
      2 fields

      • Response 200 · checks.source.range.endSecOptional

        number

        Minimum: 0.

      • Response 200 · checks.source.range.startSecOptional

        number

        Minimum: 0.

    • Response 200 · checks.source.sourceDurationSecOptional

      number

    • Response 200 · checks.source.urlOptional

      string

  • Response 200 · checks.characterImageOptional

    object
    8 fields

    • Response 200 · checks.characterImage.kindRequired

      string

    • Response 200 · checks.characterImage.statusRequired

      "ok"

    • Response 200 · checks.characterImage.clipIdOptional

      string

    • Response 200 · checks.characterImage.durationSecOptional

      number

    • Response 200 · checks.characterImage.processingModeOptional

      string

    • Response 200 · checks.characterImage.rangeOptional

      object
      2 fields

      • Response 200 · checks.characterImage.range.endSecOptional

        number

        Minimum: 0.

      • Response 200 · checks.characterImage.range.startSecOptional

        number

        Minimum: 0.

    • Response 200 · checks.characterImage.sourceDurationSecOptional

      number

    • Response 200 · checks.characterImage.urlOptional

      string

  • Response 200 · checks.srtUrlOptional

    object
    8 fields

    • Response 200 · checks.srtUrl.kindRequired

      string

    • Response 200 · checks.srtUrl.statusRequired

      "ok"

    • Response 200 · checks.srtUrl.clipIdOptional

      string

    • Response 200 · checks.srtUrl.durationSecOptional

      number

    • Response 200 · checks.srtUrl.processingModeOptional

      string

    • Response 200 · checks.srtUrl.rangeOptional

      object
      2 fields

      • Response 200 · checks.srtUrl.range.endSecOptional

        number

        Minimum: 0.

      • Response 200 · checks.srtUrl.range.startSecOptional

        number

        Minimum: 0.

    • Response 200 · checks.srtUrl.sourceDurationSecOptional

      number

    • Response 200 · checks.srtUrl.urlOptional

      string

  • Response 200 · checks.visualBoardOptional

    object
    8 fields

    • Response 200 · checks.visualBoard.kindRequired

      string

    • Response 200 · checks.visualBoard.statusRequired

      "ok"

    • Response 200 · checks.visualBoard.clipIdOptional

      string

    • Response 200 · checks.visualBoard.durationSecOptional

      number

    • Response 200 · checks.visualBoard.processingModeOptional

      string

    • Response 200 · checks.visualBoard.rangeOptional

      object
      2 fields

      • Response 200 · checks.visualBoard.range.endSecOptional

        number

        Minimum: 0.

      • Response 200 · checks.visualBoard.range.startSecOptional

        number

        Minimum: 0.

    • Response 200 · checks.visualBoard.sourceDurationSecOptional

      number

    • Response 200 · checks.visualBoard.urlOptional

      string

• Response 200 · creditsRequiredRequired

  number

  Minimum: 0.

• Response 200 · expiresAtRequired

  string

• Response 200 · modeRequired

  "fast" | "studio"

• Response 200 · preflightIdRequired

  string

• Response 200 · quoteRequired

  object

  Unknown fields are not accepted.

  15 fields

  • Response 200 · quote.breakdownRequired

    object

    Unknown fields are not accepted.

    9 fields

    • Response 200 · quote.breakdown.baseOptional

      number

    • Response 200 · quote.breakdown.composeOperationsOptional

      number

    • Response 200 · quote.breakdown.durationOptional

      number

    • Response 200 · quote.breakdown.estimatedSceneCountOptional

      number

    • Response 200 · quote.breakdown.finalizeOptional

      number

    • Response 200 · quote.breakdown.lipSyncOptional

      number

    • Response 200 · quote.breakdown.renderPerSceneOptional

      number

    • Response 200 · quote.breakdown.scenesOptional

      number

    • Response 200 · quote.breakdown.visualBoardOptional

      number

  • Response 200 · quote.creditsRequired

    number

    Minimum: 0.

  • Response 200 · quote.assumptionsOptional

    array<string>
    1 field

    • Response 200 · quote.assumptions[]Each item

      string

  • Response 200 · quote.baseCreditsOptional

    number

  • Response 200 · quote.billingIncrementCreditsOptional

    number

    Minimum: 0.0001.

  • Response 200 · quote.calculatedSubtotalCreditsOptional

    number

  • Response 200 · quote.componentsOptional

    array<object>
    1 field

    • Response 200 · quote.components[]Each item

      object

      Unknown fields are not accepted.

      7 fields

      • Response 200 · quote.components[].discountCreditsRequired

        number

      • Response 200 · quote.components[].discountedCreditsRequired

        number

      • Response 200 · quote.components[].finalCreditsRequired

        number

      • Response 200 · quote.components[].keyRequired

        string

      • Response 200 · quote.components[].labelRequired

        string

      • Response 200 · quote.components[].publicCreditsRequired

        number

      • Response 200 · quote.components[].quantityOptional

        number

  • Response 200 · quote.discountCreditsOptional

    number

  • Response 200 · quote.expiresAtOptional

    string

  • Response 200 · quote.operationOptional

    string

  • Response 200 · quote.pricingVersionOptional

    number

  • Response 200 · quote.quoteIdOptional

    string

  • Response 200 · quote.settlementPolicyVersionOptional

    string

  • Response 200 · quote.settlementRoundingCreditsOptional

    number

  • Response 200 · quote.warningCodesOptional

    array<string>
    1 field

    • Response 200 · quote.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 · quoteTypeRequired

  "validated_estimate"

• 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.

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

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

408 Request Timeout

application/json

• Response 408 · errorRequired

  object
  3 fields

  • Response 408 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 408 · error.messageRequired

    string

    Human readable error message

  • Response 408 · error.detailsOptional

    object

    Additional error details (optional)

• Response 408 · 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/preflight' \
  --header "x-api-key: $OMNAPI_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/preflight", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OMNAPI_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/preflight",
    headers={
        "x-api-key": os.environ["OMNAPI_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.

Interactive API Explorer → · OpenAPI JSON