Skip to content
API documentation

Create Omn MV

POST/api/v2/mv/

Authentication · x-api-key

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

Request

Idempotency-Keyheader · Required
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.

Unknown fields are not accepted.

  • Request · preflightIdRequired

    string

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

    Minimum characters: 1. Maximum characters: 100.

  • Request · maxCreditsOptional

    number

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

    Minimum: 1.

  • Request · quoteIdOptional

    string

    Replaces the quote captured at preflight. When omitted, an explicit maxCredits replaces it; otherwise the preflight quote applies.

    Minimum characters: 1. Maximum characters: 100.

Responses

200 OK

application/json

Unknown fields are not accepted.

  • Response 200 · autoFinalizeRequired

    boolean
  • Response 200 · contractVersionRequired

    "v2"
  • 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 · mvIdRequired

    string
  • Response 200 · pollUrlRequired

    string
  • Response 200 · pricingRequired

    object

    Unknown fields are not accepted.

    9 fields
  • Response 200 · productRequired

    object

    Unknown fields are not accepted.

    5 fields
  • Response 200 · requestIdRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives
  • 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. 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 · estimatedCompletionTimeOptional

    Date | string | number | null

    May be null. Must match at least one alternative.

    2 fields / alternatives
  • 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

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

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 · 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

Interactive API Explorer → · OpenAPI JSON