Recompose Omn MV

POST/api/v2/mv/{mvId}/recomposeCopy URL

Authentication · x-api-key

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

All endpointsRequestResponsesCode

Request

mvIdpath · Required

string

MV identifier returned by create or read operations.

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

  number

  Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.

  Minimum: 0.

• Request · maxCreditsOptional

  number

  Maximum OmnAPI credits authorized for this paid request.

  Minimum: 0.

• Request · quoteIdOptional

  string

  Short-lived quote identifier for the matching paid operation.

  Minimum characters: 1. Maximum characters: 100.

• Request · retryOptional

  boolean

  Whether to retry a supported failed operation.

Responses

200 OK

application/json

Unknown fields are not accepted.

• Response 200 · contractVersionRequired

  "v2"

• Response 200 · creditsRequiredRequired

  number

  Minimum: 0.

• Response 200 · idempotentRequired

  boolean

• Response 200 · statusRequired

  "PENDING" | "PROCESSING" | "READY" | "FAILED" | "CANCELLED"

• Response 200 · taskIdRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · taskId · anyOf 1Alternative

    string

  • Response 200 · taskId · anyOf 2Alternative

    null

• Response 200 · compositionHashOptional

  string

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

  Date | string | number | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · estimatedCompletionTime · anyOf 1Alternative

    Date | string | number

    Estimated completion time

    Must match at least one alternative.

    4 fields / alternatives

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

      Date

      Estimated completion time

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

      string

      Format: date-time.

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

      string

      Format: date.

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

      number

  • Response 200 · estimatedCompletionTime · anyOf 2Alternative

    null

• Response 200 · finalMvIdOptional

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · finalMvId · anyOf 1Alternative

    string

  • Response 200 · finalMvId · anyOf 2Alternative

    null

• Response 200 · linksOptional

  object

  Unknown fields are not accepted.

  4 fields

  • Response 200 · links.finalRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.final · anyOf 1Alternative

      string

      Final downloadable resource URL when available

    • Response 200 · links.final · anyOf 2Alternative

      null

  • Response 200 · links.resourceRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · links.resource · anyOf 1Alternative

      string

      Product resource URL when the product has a dedicated view endpoint

    • Response 200 · links.resource · anyOf 2Alternative

      null

  • Response 200 · links.streamRequired

    string

    Task SSE stream URL for the created task

  • Response 200 · links.taskRequired

    string

    Task polling URL for the created task

• Response 200 · messageOptional

  string

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

  object

  Unknown fields are not accepted.

  9 fields

  • Response 200 · pricing.adjustmentCreditsRequired

    number

    chargedCredits - baseCredits

  • Response 200 · pricing.baseCreditsRequired

    number

    Standard quoted credits before customer pricing adjustment

  • Response 200 · pricing.chargedCreditsRequired

    number

    Credits charged for this create request

    Minimum: 0.

  • Response 200 · pricing.quoteVersionRequired

    number

    Pricing quote version stored with the task

  • Response 200 · pricing.sourceRequired

    "standard" | "customer_rule"

    Public pricing source category

  • Response 200 · pricing.billingIncrementCreditsOptional

    number

    Smallest customer charge increment

    Minimum: 0.0001.

  • Response 200 · pricing.calculatedCreditsOptional

    number

    Precise whole-order subtotal before settlement rounding

  • Response 200 · pricing.settlementPolicyVersionOptional

    string

    Versioned customer settlement policy

  • Response 200 · pricing.settlementRoundingCreditsOptional

    number

    Whole-order rounding adjustment added at settlement

    Minimum: 0.

• Response 200 · productOptional

  object

  Unknown fields are not accepted.

  5 fields

  • Response 200 · product.featureCodeRequired

    string

    Resolved feature code

  • Response 200 · product.resourceIdRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.resourceId · anyOf 1Alternative

      string

      Product resource id when created synchronously

    • Response 200 · product.resourceId · anyOf 2Alternative

      null

  • Response 200 · product.typeRequired

    string

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

  • Response 200 · product.autoFinalizeOptional

    boolean

    Whether the product should finalize automatically

  • Response 200 · product.deliveryStatusOptional

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · product.deliveryStatus · anyOf 1Alternative

      string

      Product-level delivery status when applicable

    • Response 200 · product.deliveryStatus · anyOf 2Alternative

      null

• Response 200 · requestIdOptional

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · requestId · anyOf 1Alternative

    string

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

  • Response 200 · requestId · anyOf 2Alternative

    null

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

• Response 200 · retryableOptional

  boolean

• Response 200 · warningCodesOptional

  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.

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 · 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/v2/mv/{mvId}/recompose' \
  --header "x-api-key: $OMNAPI_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json

Node.js

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

Python

import os, json
import requests

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

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

Interactive API Explorer → · OpenAPI JSON