Preflight Omn creation

POST/api/v2/mv/preflight

Authentication · x-api-key

Omn V1 independent product API. Independent Omn request, planning and delivery semantics.

Request

Unknown fields are not accepted.

Request · sourceRequired

object

Public audio URL or an accessible Suno clip. The server verifies duration.

Must match at least one alternative.
2 fields / alternatives
- Request · source · anyOf 1Alternative
  
  object
  
  Public audio URL or an accessible Suno clip. The server verifies duration.
  
  Unknown fields are not accepted.
  4 fields
  - Request · source · anyOf 1.typeRequired
    
    "audio_url"
    
    audio_url requires url; suno_clip requires clipId.
  - Request · source · anyOf 1.urlRequired
    
    string
    
    Public HTTP(S) audio URL.
    
    Format: uri.
  - Request · source · anyOf 1.lyricsOptional
    
    string
    
    Optional original lyrics to guide song understanding and transcription.
    
    Maximum characters: 5000.
  - Request · source · anyOf 1.rangeOptional
    
    object
    
    Audio selection measured in seconds; effective output must be 10–600 seconds.
    
    Unknown fields are not accepted.
    
    2 fields
    
    Request · source · anyOf 1.range.endSecRequired
    
    number
    
    Selection end in the original audio, later than startSec.
    
    Exclusive lower bound: 0.
    
    Request · source · anyOf 1.range.startSecRequired
    
    number
    
    Inclusive selection start in the original audio.
    
    Minimum: 0.
- Request · source · anyOf 2Alternative
  
  object
  
  Public audio URL or an accessible Suno clip. The server verifies duration.
  
  Unknown fields are not accepted.
  4 fields
  - Request · source · anyOf 2.clipIdRequired
    
    string
    
    Accessible Suno clip identifier.
    
    Minimum characters: 1.
  - Request · source · anyOf 2.typeRequired
    
    "suno_clip"
    
    audio_url requires url; suno_clip requires clipId.
  - Request · source · anyOf 2.lyricsOptional
    
    string
    
    Optional original lyrics to guide song understanding and transcription.
    
    Maximum characters: 5000.
  - Request · source · anyOf 2.rangeOptional
    
    object
    
    Audio selection measured in seconds; effective output must be 10–600 seconds.
    
    Unknown fields are not accepted.
    
    2 fields
    
    Request · source · anyOf 2.range.endSecRequired
    
    number
    
    Selection end in the original audio, later than startSec.
    
    Exclusive lower bound: 0.
    
    Request · source · anyOf 2.range.startSecRequired
    
    number
    
    Inclusive selection start in the original audio.
    
    Minimum: 0.
Request · captionsOptional

object

Subtitle policy; captions do not control whether lyrics are analyzed for planning.

Unknown fields are not accepted.
4 fields
- Request · captions.modeRequired
  
  "off" | "auto" | "provided"
  
  off, auto or provided. provided requires srtUrl; other modes reject it.
  
  Default: "off".
- Request · captions.languageOptional
  
  "auto" | "en" | "zh"
  
  Expected subtitle language (auto, en or zh).
  
  Default: "auto".
- Request · captions.requiredOptional
  
  boolean
  
  When true, do not silently deliver without requested captions. Invalid with mode off.
- Request · captions.srtUrlOptional
  
  string
  
  Public SRT URL with cue times relative to the selected audio segment.
  
  Format: uri.
Request · configOptional

object

Standard task configuration: priority, tags, metadata, and webhookUrl.
4 fields
- Request · config.metadataOptional
  
  object
  
  Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
- Request · config.priorityOptional
  
  number
  
  Task priority 1-10 (higher = sooner). Default 5.
  
  Minimum: 1. Maximum: 10. Default: 5.
- Request · config.tagsOptional
  
  array<string>
  
  Free-form labels for filtering. Up to 20, 100 chars each.
  
  Maximum items: 20.
  1 field
  - Request · config.tags[]Each item
    
    string
    
    Maximum characters: 100.
- Request · config.webhookUrlOptional
  
  string
  
  URL to receive task.* lifecycle events via the central webhook service.
  
  Format: uri.
Request · creativeOptional

object

Creative intent, independent of output resolution.

Unknown fields are not accepted.
5 fields
- Request · creative.modeRequired
  
  "auto" | "story" | "mood" | "perform" | "sing" | "dance" | "sing_dance" | "sing_play"
  
  auto, story, mood, perform, sing, dance, sing_dance or sing_play. All use the same request envelope.
  
  Default: "auto".
- Request · creative.briefOptional
  
  string
  
  Describe the desired story, subjects, action and mood. Required for a brief-led story.
  
  Maximum characters: 3000.
- Request · creative.charactersOptional
  
  object
  
  Whether characters may appear and the desired count.
  
  Unknown fields are not accepted.
  2 fields
  - Request · creative.characters.policyRequired
    
    "auto" | "required" | "forbidden"
    
    auto lets the director decide; required mandates characters; forbidden excludes them and conflicts with performance modes or character references.
    
    Default: "auto".
  - Request · creative.characters.countOptional
    
    string | integer
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Minimum: 1. Maximum: 2. Must match at least one alternative.
    
    2 fields / alternatives
    
    Request · creative.characters.count · anyOf 1Alternative
    
    string
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Format: integer. Default: 0.
    
    Request · creative.characters.count · anyOf 2Alternative
    
    integer
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Minimum: 1. Maximum: 2.
- Request · creative.optionsOptional
  
  object
  
  Mode-specific choices; irrelevant options are rejected.
  
  Unknown fields are not accepted.
  3 fields
  - Request · creative.options.combinationOptional
    
    "alternating" | "simultaneous"
    
    Required for sing_dance or sing_play. alternating uses separate shots. simultaneous requests same-shot actions and currently returns 422 before debit.
    
    Default: "alternating".
  - Request · creative.options.instrumentOptional
    
    string
    
    Instrument to feature in perform or sing_play.
    
    Minimum characters: 1. Maximum characters: 100.
  - Request · creative.options.storySourceOptional
    
    "lyrics" | "brief"
    
    Required for story: lyrics uses song evidence; brief uses creative.brief.
    
    Default: "lyrics".
- Request · creative.styleOptional
  
  string
  
  Visual treatment passed to director planning and shot generation.
  
  Maximum characters: 1000.
Request · maxCreditsOptional

number

Maximum authorized customer charge. A lower cap rejects the purchase without reducing the requested output.

Minimum: 1.
Request · outputOptional

object

Delivery format. No render tier or provider selector is accepted.

Unknown fields are not accepted.
2 fields
- Request · output.aspectRatioOptional
  
  "16:9" | "9:16" | "1:1" | "4:3" | "3:4"
  
  Delivery aspect ratio; defaults to 16:9. Motion references require 16:9 or 9:16.
- Request · output.resolutionOptional
  
  "540p" | "720p" | "1080p" | "1440p"
  
  540p, 720p, 1080p or 1440p for every mode. Defaults to 720p. Motion output may be resized from its source resolution.
Request · preflightIdOptional

string

Unexpired preflight identifier bound to this user, API key and exact creative request.

Minimum characters: 1. Maximum characters: 100.
Request · quoteIdOptional

string

Short-lived quote identifier for the matching paid operation.

Minimum characters: 1. Maximum characters: 100.
Request · referencesOptional

object

Optional media references. Secondary characters, style and location images together may not exceed six.

Unknown fields are not accepted.
4 fields
- Request · references.charactersOptional
  
  array<object>
  
  Up to two ordered identity references; omit to let Omn create characters.
  
  Maximum items: 2.
  1 field
  - Request · references.characters[]Each item
    
    object
    
    Up to two ordered identity references; omit to let Omn create characters.
    
    Unknown fields are not accepted.
    
    3 fields
    
    Request · references.characters[].idRequired
    
    string
    
    Unique character identifier used to bind a motion reference.
    
    Minimum characters: 1. Maximum characters: 64.
    
    Request · references.characters[].imageUrlRequired
    
    string
    
    Public HTTP(S) portrait URL.
    
    Format: uri.
    
    Request · references.characters[].descriptionOptional
    
    string
    
    Role and appearance guidance for this character.
    
    Maximum characters: 500.
- Request · references.locationsOptional
  
  array<string>
  
  Up to three scene or location image URLs.
  
  Maximum items: 3.
  1 field
  - Request · references.locations[]Each item
    
    string
    
    Up to three scene or location image URLs.
    
    Format: uri.
- Request · references.motionOptional
  
  object
  
  Optional motion reference for dance only; runtime support is checked before debit.
  
  Unknown fields are not accepted.
  3 fields
  - Request · references.motion.rightsConfirmedRequired
    
    true
    
    Must be true to confirm you have permission to use the motion reference.
  - Request · references.motion.videoUrlRequired
    
    string
    
    Public HTTP(S) motion reference video URL.
    
    Format: uri.
  - Request · references.motion.characterIdOptional
    
    string
    
    Identifier of a supplied character that performs the referenced movement; defaults to the first character.
- Request · references.stylesOptional
  
  array<string>
  
  Up to three visual style image URLs.
  
  Maximum items: 3.
  1 field
  - Request · references.styles[]Each item
    
    string
    
    Up to three visual style image URLs.
    
    Format: uri.
Request · 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
    
    Unknown fields are not accepted.
    
    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
    
    Unknown fields are not accepted.
    
    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
  
  Unknown fields are not accepted.
  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
    
    Unknown fields are not accepted.
    
    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
  
  Unknown fields are not accepted.
  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
    
    Unknown fields are not accepted.
    
    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
  
  Unknown fields are not accepted.
  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
    
    Unknown fields are not accepted.
    
    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
  
  Unknown fields are not accepted.
  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
    
    Unknown fields are not accepted.
    
    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 · contractVersionRequired

"v2"
Response 200 · creditsRequiredRequired

number

Minimum: 0.
Response 200 · expiresAtRequired

string
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.
  8 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.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. MV_CREATIVE_PLANNING_FROM_UNVERIFIED_TRANSCRIPT means recognized text was used for creative planning; MV_CREATIVE_PLANNING_WITHOUT_LYRICS means no usable lyric semantics were used. These two codes are mutually exclusive in the final plan. Customer lyrics with machine-estimated timing use MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED instead. 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. MV_CREATIVE_PLANNING_FROM_UNVERIFIED_TRANSCRIPT means recognized text was used for creative planning; MV_CREATIVE_PLANNING_WITHOUT_LYRICS means no usable lyric semantics were used. These two codes are mutually exclusive in the final plan. Customer lyrics with machine-estimated timing use MV_AUDIO_SUBTITLE_TIMING_UNVERIFIED instead. 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 · creativeOptional

object

Must match at least one alternative.
5 fields / alternatives
- Response 200 · creative · anyOf 1Alternative
  
  object
  
  Unknown fields are not accepted.
  2 fields
  - Response 200 · creative · anyOf 1.presetRequired
    
    "auto"
  - Response 200 · creative · anyOf 1.singingOptional
    
    "allowed" | "forbidden"
    
    Default: "allowed".
- Response 200 · creative · anyOf 2Alternative
  
  object
  
  Unknown fields are not accepted.
  2 fields
  - Response 200 · creative · anyOf 2.presetRequired
    
    "mood"
  - Response 200 · creative · anyOf 2.singingOptional
    
    "allowed" | "forbidden"
    
    Default: "allowed".
- Response 200 · creative · anyOf 3Alternative
  
  object
  
  Unknown fields are not accepted.
  3 fields
  - Response 200 · creative · anyOf 3.presetRequired
    
    "story"
  - Response 200 · creative · anyOf 3.storySourceRequired
    
    "lyrics" | "prompt"
    
    Default: "lyrics".
  - Response 200 · creative · anyOf 3.singingOptional
    
    "allowed" | "forbidden"
    
    Default: "allowed".
- Response 200 · creative · anyOf 4Alternative
  
  object
  
  Unknown fields are not accepted.
  1 field
  - Response 200 · creative · anyOf 4.presetRequired
    
    "sing" | "sing_perform" | "perform" | "dance" | "sing_dance" | "sing_play"
    
    Default: "sing".
- Response 200 · creative · anyOf 5Alternative
  
  object
  
  Creative intent, independent of output resolution.
  
  Unknown fields are not accepted.
  5 fields
  - Response 200 · creative · anyOf 5.modeRequired
    
    "auto" | "story" | "mood" | "perform" | "sing" | "dance" | "sing_dance" | "sing_play"
    
    auto, story, mood, perform, sing, dance, sing_dance or sing_play. All use the same request envelope.
    
    Default: "auto".
  - Response 200 · creative · anyOf 5.briefOptional
    
    string
    
    Describe the desired story, subjects, action and mood. Required for a brief-led story.
    
    Maximum characters: 3000.
  - Response 200 · creative · anyOf 5.charactersOptional
    
    object
    
    Whether characters may appear and the desired count.
    
    Unknown fields are not accepted.
    
    2 fields
    
    Response 200 · creative · anyOf 5.characters.policyRequired
    
    "auto" | "required" | "forbidden"
    
    auto lets the director decide; required mandates characters; forbidden excludes them and conflicts with performance modes or character references.
    
    Default: "auto".
    
    Response 200 · creative · anyOf 5.characters.countOptional
    
    string | integer
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Minimum: 1. Maximum: 2. Must match at least one alternative.
    
    2 fields / alternatives
    
    Response 200 · creative · anyOf 5.characters.count · anyOf 1Alternative
    
    string
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Format: integer. Default: 0.
    
    1 field
    
    Response 200 · creative · anyOf 5.characters.count · anyOf 1See schema
    
    string
    
    Expand this value in the interactive reference.
    
    Format: integer. Default: 0.
    
    Response 200 · creative · anyOf 5.characters.count · anyOf 2Alternative
    
    integer
    
    Desired number of main characters (1 or 2); cannot be combined with forbidden.
    
    Minimum: 1. Maximum: 2.
    
    1 field
    
    Response 200 · creative · anyOf 5.characters.count · anyOf 2See schema
    
    integer
    
    Expand this value in the interactive reference.
    
    Minimum: 1. Maximum: 2.
  - Response 200 · creative · anyOf 5.optionsOptional
    
    object
    
    Mode-specific choices; irrelevant options are rejected.
    
    Unknown fields are not accepted.
    
    3 fields
    
    Response 200 · creative · anyOf 5.options.combinationOptional
    
    "alternating" | "simultaneous"
    
    Required for sing_dance or sing_play. alternating uses separate shots. simultaneous requests same-shot actions and currently returns 422 before debit.
    
    Default: "alternating".
    
    Response 200 · creative · anyOf 5.options.instrumentOptional
    
    string
    
    Instrument to feature in perform or sing_play.
    
    Minimum characters: 1. Maximum characters: 100.
    
    Response 200 · creative · anyOf 5.options.storySourceOptional
    
    "lyrics" | "brief"
    
    Required for story: lyrics uses song evidence; brief uses creative.brief.
    
    Default: "lyrics".
  - Response 200 · creative · anyOf 5.styleOptional
    
    string
    
    Visual treatment passed to director planning and shot generation.
    
    Maximum characters: 1000.
Response 200 · outputOptional

object

Unknown fields are not accepted.
3 fields
- Response 200 · output.aspectRatioOptional
  
  "16:9" | "9:16" | "1:1" | "4:3" | "3:4"
  
  Delivery aspect ratio; defaults to 16:9. Motion references require 16:9 or 9:16.
- Response 200 · output.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.
- Response 200 · output.resolutionOptional
  
  "540p" | "720p" | "1080p" | "1440p"
  
  540p, 720p, 1080p or 1440p for every mode. Defaults to 720p. Motion output may be resized from its source resolution.
Response 200 · requestedOutputOptional

object

Unknown fields are not accepted.
3 fields
- Response 200 · requestedOutput.aspectRatioOptional
  
  "16:9" | "9:16" | "1:1" | "4:3" | "3:4"
  
  Delivery aspect ratio; defaults to 16:9. Motion references require 16:9 or 9:16.
- Response 200 · requestedOutput.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.
- Response 200 · requestedOutput.resolutionOptional
  
  "540p" | "720p" | "1080p" | "1440p"
  
  540p, 720p, 1080p or 1440p for every mode. Defaults to 720p. Motion output may be resized from its source resolution.

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

404 Not Found

application/json

Response 404 · errorRequired

object
3 fields
- Response 404 · error.codeRequired
  
  string
  
  Application-specific error code (see error catalog)
- Response 404 · error.messageRequired
  
  string
  
  Human readable error message
- Response 404 · error.detailsOptional
  
  object
  
  Additional error details (optional)
Response 404 · 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

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

import { readFile } from "node:fs/promises";
const response = await fetch("https://api.omnapi.com/api/v2/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());

import os, json
import requests

response = requests.request(
    "POST", "https://api.omnapi.com/api/v2/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

Preflight Omn creation

Request

Request · sourceRequired

Request · source · anyOf 1Alternative

Request · source · anyOf 1.typeRequired

Request · source · anyOf 1.urlRequired

Request · source · anyOf 1.lyricsOptional

Request · source · anyOf 1.rangeOptional

Request · source · anyOf 1.range.endSecRequired

Request · source · anyOf 1.range.startSecRequired

Request · source · anyOf 2Alternative

Request · source · anyOf 2.clipIdRequired

Request · source · anyOf 2.typeRequired

Request · source · anyOf 2.lyricsOptional

Request · source · anyOf 2.rangeOptional

Request · source · anyOf 2.range.endSecRequired

Request · source · anyOf 2.range.startSecRequired

Request · captionsOptional

Request · captions.modeRequired

Request · captions.languageOptional

Request · captions.requiredOptional

Request · captions.srtUrlOptional

Request · configOptional

Request · config.metadataOptional

Request · config.priorityOptional

Request · config.tagsOptional

Request · config.tags[]Each item

Request · config.webhookUrlOptional

Request · creativeOptional

Request · creative.modeRequired

Request · creative.briefOptional

Request · creative.charactersOptional

Request · creative.characters.policyRequired

Request · creative.characters.countOptional

Request · creative.characters.count · anyOf 1Alternative

Request · creative.characters.count · anyOf 2Alternative

Request · creative.optionsOptional

Request · creative.options.combinationOptional

Request · creative.options.instrumentOptional

Request · creative.options.storySourceOptional

Request · creative.styleOptional

Request · maxCreditsOptional

Request · outputOptional

Request · output.aspectRatioOptional

Request · output.resolutionOptional

Request · preflightIdOptional

Request · quoteIdOptional

Request · referencesOptional

Request · references.charactersOptional

Request · references.characters[]Each item

Request · references.characters[].idRequired

Request · references.characters[].imageUrlRequired

Request · references.characters[].descriptionOptional

Request · references.locationsOptional

Request · references.locations[]Each item

Request · references.motionOptional

Request · references.motion.rightsConfirmedRequired

Request · references.motion.videoUrlRequired

Request · references.motion.characterIdOptional

Request · references.stylesOptional

Request · references.styles[]Each item

Request · titleOptional

Responses

Response 200 · checksRequired

Response 200 · checks.referenceImagesRequired

Response 200 · checks.referenceImages[]Each item

Response 200 · checks.referenceImages[].kindRequired

Response 200 · checks.referenceImages[].statusRequired

Response 200 · checks.referenceImages[].clipIdOptional

Response 200 · checks.referenceImages[].durationSecOptional

Response 200 · checks.referenceImages[].processingModeOptional

Response 200 · checks.referenceImages[].rangeOptional

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

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

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

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

Response 200 · checks.referenceImages[].sourceDurationSecOptional

Response 200 · checks.referenceImages[].urlOptional

Response 200 · checks.sourceRequired

Response 200 · checks.source.kindRequired

Request · `source`Required

Request · `source · anyOf 1`Alternative

Request · `source · anyOf 1.type`Required

Request · `source · anyOf 1.url`Required

Request · `source · anyOf 1.lyrics`Optional

Request · `source · anyOf 1.range`Optional

Request · `source · anyOf 1.range.endSec`Required

Request · `source · anyOf 1.range.startSec`Required

Request · `source · anyOf 2`Alternative

Request · `source · anyOf 2.clipId`Required

Request · `source · anyOf 2.type`Required

Request · `source · anyOf 2.lyrics`Optional

Request · `source · anyOf 2.range`Optional

Request · `source · anyOf 2.range.endSec`Required

Request · `source · anyOf 2.range.startSec`Required

Request · `captions`Optional

Request · `captions.mode`Required

Request · `captions.language`Optional

Request · `captions.required`Optional

Request · `captions.srtUrl`Optional

Request · `config`Optional

Request · `config.metadata`Optional

Request · `config.priority`Optional

Request · `config.tags`Optional

Request · `config.tags[]`Each item

Request · `config.webhookUrl`Optional

Request · `creative`Optional

Request · `creative.mode`Required

Request · `creative.brief`Optional

Request · `creative.characters`Optional

Request · `creative.characters.policy`Required

Request · `creative.characters.count`Optional

Request · `creative.characters.count · anyOf 1`Alternative

Request · `creative.characters.count · anyOf 2`Alternative

Request · `creative.options`Optional

Request · `creative.options.combination`Optional

Request · `creative.options.instrument`Optional

Request · `creative.options.storySource`Optional

Request · `creative.style`Optional

Request · `maxCredits`Optional

Request · `output`Optional

Request · `output.aspectRatio`Optional

Request · `output.resolution`Optional

Request · `preflightId`Optional

Request · `quoteId`Optional

Request · `references`Optional

Request · `references.characters`Optional

Request · `references.characters[]`Each item

Request · `references.characters[].id`Required

Request · `references.characters[].imageUrl`Required

Request · `references.characters[].description`Optional

Request · `references.locations`Optional

Request · `references.locations[]`Each item

Request · `references.motion`Optional

Request · `references.motion.rightsConfirmed`Required

Request · `references.motion.videoUrl`Required

Request · `references.motion.characterId`Optional

Request · `references.styles`Optional

Request · `references.styles[]`Each item

Request · `title`Optional

Response 200 · `checks`Required

Response 200 · `checks.referenceImages`Required

Response 200 · `checks.referenceImages[]`Each item

Response 200 · `checks.referenceImages[].kind`Required

Response 200 · `checks.referenceImages[].status`Required

Response 200 · `checks.referenceImages[].clipId`Optional

Response 200 · `checks.referenceImages[].durationSec`Optional

Response 200 · `checks.referenceImages[].processingMode`Optional

Response 200 · `checks.referenceImages[].range`Optional

Response 200 · `checks.referenceImages[].range.endSec`Optional

Response 200 · `checks.referenceImages[].range.endSec`See schema

Response 200 · `checks.referenceImages[].range.startSec`Optional

Response 200 · `checks.referenceImages[].range.startSec`See schema

Response 200 · `checks.referenceImages[].sourceDurationSec`Optional

Response 200 · `checks.referenceImages[].url`Optional

Response 200 · `checks.source`Required

Response 200 · `checks.source.kind`Required

Response 200 · `checks.source.status`Required

Response 200 · `checks.source.clipId`Optional

Response 200 · `checks.source.durationSec`Optional