Read v2 creative draft

GET/api/v2/mv/drafts/{id}Copy URL

Authentication · x-api-key

Omn creative draft operation. Drafts retain a version; generation and preview require a new customer charge authorization and an Idempotency-Key. Preview is independently billed.

All endpointsRequestResponsesCode

Request

idpath · Required

string

Resource identifier returned by the corresponding create operation.

Responses

200 OK

application/json

• Response 200 · contractVersionRequired

  "v2"

• Response 200 · expiresAtRequired

  string

• Response 200 · idRequired

  string

• Response 200 · requestRequired

  object

  Unknown fields are not accepted.

  10 fields

  • Response 200 · request.sourceRequired

    object

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

    Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · request.source · anyOf 1Alternative

      object

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

      Unknown fields are not accepted.

      4 fields

      • Response 200 · request.source · anyOf 1.typeRequired

        "audio_url"

        audio_url requires url; suno_clip requires clipId.

      • Response 200 · request.source · anyOf 1.urlRequired

        string

        Public HTTP(S) audio URL.

        Format: uri.

      • Response 200 · request.source · anyOf 1.lyricsOptional

        string

        Optional original lyrics to guide song understanding and transcription.

        Maximum characters: 5000.

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

        • Response 200 · request.source · anyOf 1.range.endSecRequired

          number

          Selection end in the original audio, later than startSec.

          Exclusive lower bound: 0.

          1 field

          • Response 200 · request.source · anyOf 1.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Exclusive lower bound: 0.

        • Response 200 · request.source · anyOf 1.range.startSecRequired

          number

          Inclusive selection start in the original audio.

          Minimum: 0.

          1 field

          • Response 200 · request.source · anyOf 1.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

    • Response 200 · request.source · anyOf 2Alternative

      object

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

      Unknown fields are not accepted.

      4 fields

      • Response 200 · request.source · anyOf 2.clipIdRequired

        string

        Accessible Suno clip identifier.

        Minimum characters: 1.

      • Response 200 · request.source · anyOf 2.typeRequired

        "suno_clip"

        audio_url requires url; suno_clip requires clipId.

      • Response 200 · request.source · anyOf 2.lyricsOptional

        string

        Optional original lyrics to guide song understanding and transcription.

        Maximum characters: 5000.

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

        • Response 200 · request.source · anyOf 2.range.endSecRequired

          number

          Selection end in the original audio, later than startSec.

          Exclusive lower bound: 0.

          1 field

          • Response 200 · request.source · anyOf 2.range.endSecSee schema

            number

            Expand this value in the interactive reference.

            Exclusive lower bound: 0.

        • Response 200 · request.source · anyOf 2.range.startSecRequired

          number

          Inclusive selection start in the original audio.

          Minimum: 0.

          1 field

          • Response 200 · request.source · anyOf 2.range.startSecSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

  • Response 200 · request.captionsOptional

    object

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

    Unknown fields are not accepted.

    4 fields

    • Response 200 · request.captions.modeRequired

      "off" | "auto" | "provided"

      off, auto or provided. provided requires srtUrl; other modes reject it.

      Default: "off".

    • Response 200 · request.captions.languageOptional

      "auto" | "en" | "zh"

      Expected subtitle language (auto, en or zh).

      Default: "auto".

    • Response 200 · request.captions.requiredOptional

      boolean

      When true, do not silently deliver without requested captions. Invalid with mode off.

    • Response 200 · request.captions.srtUrlOptional

      string

      Public SRT URL with cue times relative to the selected audio segment.

      Format: uri.

  • Response 200 · request.configOptional

    object
    4 fields

    • Response 200 · request.config.metadataOptional

      object

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

    • Response 200 · request.config.priorityOptional

      number

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

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

    • Response 200 · request.config.tagsOptional

      array<string>

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

      Maximum items: 20.

      1 field

      • Response 200 · request.config.tags[]Each item

        string

        Maximum characters: 100.

    • Response 200 · request.config.webhookUrlOptional

      string

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

      Format: uri.

  • Response 200 · request.creativeOptional

    object

    Creative intent, independent of output resolution.

    Unknown fields are not accepted.

    5 fields

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

    • Response 200 · request.creative.briefOptional

      string

      Describe the desired story, subjects, action and mood. Required for a brief-led story.

      Maximum characters: 3000.

    • Response 200 · request.creative.charactersOptional

      object

      Whether characters may appear and the desired count.

      Unknown fields are not accepted.

      2 fields

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

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

        • Response 200 · request.creative.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 · request.creative.characters.count · anyOf 1See schema

            string

            Expand this value in the interactive reference.

            Format: integer. Default: 0.

        • Response 200 · request.creative.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 · request.creative.characters.count · anyOf 2See schema

            integer

            Expand this value in the interactive reference.

            Minimum: 1. Maximum: 2.

    • Response 200 · request.creative.optionsOptional

      object

      Mode-specific choices; irrelevant options are rejected.

      Unknown fields are not accepted.

      3 fields

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

      • Response 200 · request.creative.options.instrumentOptional

        string

        Instrument to feature in perform or sing_play.

        Minimum characters: 1. Maximum characters: 100.

      • Response 200 · request.creative.options.storySourceOptional

        "lyrics" | "brief"

        Required for story: lyrics uses song evidence; brief uses creative.brief.

        Default: "lyrics".

    • Response 200 · request.creative.styleOptional

      string

      Visual treatment passed to director planning and shot generation.

      Maximum characters: 1000.

  • Response 200 · request.maxCreditsOptional

    number

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

    Minimum: 1.

  • Response 200 · request.outputOptional

    object

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

    Unknown fields are not accepted.

    2 fields

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

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

  • Response 200 · request.preflightIdOptional

    string

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

    Minimum characters: 1. Maximum characters: 100.

  • Response 200 · request.quoteIdOptional

    string

    Minimum characters: 1. Maximum characters: 100.

  • Response 200 · request.referencesOptional

    object

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

    Unknown fields are not accepted.

    4 fields

    • Response 200 · request.references.charactersOptional

      array<object>

      Up to two ordered identity references; omit to let Omn create characters.

      Maximum items: 2.

      1 field

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

        • Response 200 · request.references.characters[].idRequired

          string

          Unique character identifier used to bind a motion reference.

          Minimum characters: 1. Maximum characters: 64.

          1 field

          • Response 200 · request.references.characters[].idSee schema

            string

            Expand this value in the interactive reference.

            Minimum characters: 1. Maximum characters: 64.

        • Response 200 · request.references.characters[].imageUrlRequired

          string

          Public HTTP(S) portrait URL.

          Format: uri.

          1 field

          • Response 200 · request.references.characters[].imageUrlSee schema

            string

            Expand this value in the interactive reference.

            Format: uri.

        • Response 200 · request.references.characters[].descriptionOptional

          string

          Role and appearance guidance for this character.

          Maximum characters: 500.

          1 field

          • Response 200 · request.references.characters[].descriptionSee schema

            string

            Expand this value in the interactive reference.

            Maximum characters: 500.

    • Response 200 · request.references.locationsOptional

      array<string>

      Up to three scene or location image URLs.

      Maximum items: 3.

      1 field

      • Response 200 · request.references.locations[]Each item

        string

        Up to three scene or location image URLs.

        Format: uri.

    • Response 200 · request.references.motionOptional

      object

      Optional motion reference for dance only; runtime support is checked before debit.

      Unknown fields are not accepted.

      3 fields

      • Response 200 · request.references.motion.rightsConfirmedRequired

        true

        Must be true to confirm you have permission to use the motion reference.

      • Response 200 · request.references.motion.videoUrlRequired

        string

        Public HTTP(S) motion reference video URL.

        Format: uri.

      • Response 200 · request.references.motion.characterIdOptional

        string

        Identifier of a supplied character that performs the referenced movement; defaults to the first character.

    • Response 200 · request.references.stylesOptional

      array<string>

      Up to three visual style image URLs.

      Maximum items: 3.

      1 field

      • Response 200 · request.references.styles[]Each item

        string

        Up to three visual style image URLs.

        Format: uri.

  • Response 200 · request.titleOptional

    string

    Maximum characters: 200.

• Response 200 · versionRequired

  string | integer

  Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · version · anyOf 1Alternative

    string

    Format: integer. Default: 0.

  • Response 200 · version · anyOf 2Alternative

    integer

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

Wrap lines

cURL

curl --globoff --request GET \
  --url 'https://api.omnapi.com/api/v2/mv/drafts/{id}' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v2/mv/drafts/{id}", {
  method: "GET",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os
import requests

response = requests.request(
    "GET", "https://api.omnapi.com/api/v2/mv/drafts/{id}",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables.

Interactive API Explorer → · OpenAPI JSON