Save creative draft

POST/api/v1/mv/draftsCopy URL

Authentication · x-api-key

Save creative choices without purchasing generation. Updates require expectedVersion to match the stored revision; stale updates return 409.

All endpointsRequestResponsesCode

Request

Unknown fields are not accepted.

• Request · sourceRequired

  object

  Public source media or product reference.

  Must match at least one alternative.

  2 fields / alternatives

  • Request · source · anyOf 1Alternative

    object

    Unknown fields are not accepted.

    2 fields

    • Request · source · anyOf 1.clipIdRequired

      string

      Source clip identifier.

      Minimum characters: 1.

    • Request · source · anyOf 1.typeRequired

      "suno"

      Source or product type discriminator.

  • Request · source · anyOf 2Alternative

    object

    Unknown fields are not accepted.

    6 fields

    • Request · source · anyOf 2.audioUrlRequired

      string

      Public HTTP(S) audio URL.

      Format: uri.

    • Request · source · anyOf 2.typeRequired

      "audio"

      Source or product type discriminator.

    • Request · source · anyOf 2.durationSecOptional

      number

      Requested or known media duration in seconds.

      Exclusive lower bound: 0.

    • Request · source · anyOf 2.lyricsOptional

      string

      Lyrics or lyric context supplied to the operation.

      Maximum characters: 5000.

    • Request · source · anyOf 2.musicStyleOptional

      string

      Optional song genre, mood or musical style used to guide automatic visual planning.

      Maximum characters: 500.

    • Request · source · anyOf 2.titleOptional

      string

      Optional customer-facing title.

      Maximum characters: 200.

• Request · aspectRatioOptional

  "16:9" | "9:16" | "1:1" | "4:3" | "3:4"

  Requested output aspect ratio.

• Request · characterImageOptional

  string

  Public character reference image URL.

  Format: uri.

• Request · descriptionOptional

  string

  Optional customer-facing resource description.

  Maximum characters: 2000.

• Request · engineVersionOptional

  "vidu-v2" | "omn-v1"

  Generation option for this draft. Defaults to vidu-v2; omn-v1 requires successful capability and preflight checks.

  Default: "vidu-v2".

• Request · performanceModeOptional

  "auto" | "story" | "perform" | "dance" | "sing" | "sing_perform" | "sing_dance" | "sing_play"

  Omit or use auto for song-led planning. On Omn V1, auto and story use narrative rendering without forced stage performance. story, sing_dance (singing and dancing) and sing_play (singing while playing an instrument) are Omn-only; perform means stage or instrumental performance. Singing and dance require explicit selection.

  Default: "auto".

• Request · referenceImagesOptional

  array<string>

  Public reference image URLs.

  Maximum items: 6.

  1 field

  • Request · referenceImages[]Each item

    string

    Format: uri.

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

• Request · resolutionOptional

  "540p" | "720p" | "1080p" | "1440p"

  Omn V1 delivery resolution. Defaults to the selected tier's default, or 720p. Must match renderTier when supplied.

  Default: "540p".

• Request · scheduleOptional

  "standard" | "economy"

  Omn V1 only. economy renders shots only in the off-peak window at the same video price as standard scheduling, with a longer delivery window: shots start between 00:00 and 07:40 Beijing time (no new shot in the window's last 20 minutes, so none runs into peak pricing). MVView.generation.scheduleWindow reports the window the waiting shots are bought in; its offPeakEndsAt is the 08:00 window end.

• Request · styleIdOptional

  "auto" | "cinematic" | "anime" | "ink" | "3d" | "vaporwave" | "brand"

  Omit or use auto to let the planner choose visual art direction.

  Default: "auto".

• Request · subtitlesOptional

  boolean

  Whether subtitles are enabled for the MV.

Responses

200 OK

application/json

• Response 200 · briefRequired

  object

  Saved creative choices and source media. Omitted visual style and performance use automatic song-led planning.

  Unknown fields are not accepted.

  12 fields

  • Response 200 · brief.sourceRequired

    object

    Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · brief.source · anyOf 1Alternative

      object

      Unknown fields are not accepted.

      2 fields

      • Response 200 · brief.source · anyOf 1.clipIdRequired

        string

        Minimum characters: 1.

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

        "suno"

    • Response 200 · brief.source · anyOf 2Alternative

      object

      Unknown fields are not accepted.

      6 fields

      • Response 200 · brief.source · anyOf 2.audioUrlRequired

        string

        Format: uri.

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

        "audio"

      • Response 200 · brief.source · anyOf 2.durationSecOptional

        number

        Exclusive lower bound: 0.

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

        string

        Maximum characters: 5000.

      • Response 200 · brief.source · anyOf 2.musicStyleOptional

        string

        Optional song genre, mood or musical style used to guide automatic visual planning.

        Maximum characters: 500.

      • Response 200 · brief.source · anyOf 2.titleOptional

        string

        Maximum characters: 200.

  • Response 200 · brief.aspectRatioOptional

    "16:9" | "9:16" | "1:1" | "4:3" | "3:4"

  • Response 200 · brief.characterImageOptional

    string

    Format: uri.

  • Response 200 · brief.descriptionOptional

    string

    Maximum characters: 2000.

  • Response 200 · brief.engineVersionOptional

    "vidu-v2" | "omn-v1"

    Generation option for this draft. Defaults to vidu-v2; omn-v1 requires successful capability and preflight checks.

    Default: "vidu-v2".

  • Response 200 · brief.performanceModeOptional

    "auto" | "story" | "perform" | "dance" | "sing" | "sing_perform" | "sing_dance" | "sing_play"

    Omit or use auto for song-led planning. On Omn V1, auto and story use narrative rendering without forced stage performance. story, sing_dance (singing and dancing) and sing_play (singing while playing an instrument) are Omn-only; perform means stage or instrumental performance. Singing and dance require explicit selection.

    Default: "auto".

  • Response 200 · brief.referenceImagesOptional

    array<string>

    Maximum items: 6.

    1 field

    • Response 200 · brief.referenceImages[]Each item

      string

      Format: uri.

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

    "540p" | "720p" | "1080p" | "1440p"

    Omn V1 delivery resolution. Defaults to the selected tier's default, or 720p. Must match renderTier when supplied.

    Default: "540p".

  • Response 200 · brief.scheduleOptional

    "standard" | "economy"

    Omn V1 only. economy renders shots only in the off-peak window at the same video price as standard scheduling, with a longer delivery window: shots start between 00:00 and 07:40 Beijing time (no new shot in the window's last 20 minutes, so none runs into peak pricing). MVView.generation.scheduleWindow reports the window the waiting shots are bought in; its offPeakEndsAt is the 08:00 window end.

  • Response 200 · brief.styleIdOptional

    "auto" | "cinematic" | "anime" | "ink" | "3d" | "vaporwave" | "brand"

    Omit or use auto to let the planner choose visual art direction.

    Default: "auto".

  • Response 200 · brief.subtitlesOptional

    boolean

• Response 200 · expiresAtRequired

  string

• Response 200 · idRequired

  string

• Response 200 · planRequired

  object
  5 fields

  • Response 200 · plan.performanceModeRequired

    "auto" | "story" | "perform" | "dance" | "sing" | "sing_perform" | "sing_dance" | "sing_play"

  • Response 200 · plan.requiresPortraitRequired

    boolean

  • Response 200 · plan.statusRequired

    "action_required" | "ready_for_preflight"

  • Response 200 · plan.styleRequired

    string

  • Response 200 · plan.warningCodesOptional

    array<string>

    Advisory adjustments applied when this draft is compiled, for example MV_SUBTITLE_DISABLED_NO_TIMELINE for an Omn V1 audio draft without subtitle timing.

    1 field

    • Response 200 · plan.warningCodes[]Each item

      string

      MV advisory warning codes. Non-fatal: the request still succeeds; these flag degraded, adjusted, or automatically recovered inputs and are projected into public Task warningCodes. Omn review codes (MV_NATIVE_CREATIVE_*, MV_NATIVE_SHOT_INTERNAL_CUT, MV_NATIVE_FRAME_BORDERS) describe the delivered video; their observations and affected scenes are in `quality` of GET /api/v1/tasks/{taskId}/workflow.

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

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

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

Request example

Wrap lines

cURL

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

Node.js

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

Python

import os, json
import requests

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