Save creative draft

PUT/api/v1/mv/drafts/{id}

Authentication · x-api-key

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

Request

idpath · Required

string

Resource identifier returned by the corresponding create operation.

Unknown fields are not accepted.

Request · 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
- Request · brief.sourceRequired
  
  object
  
  Public source media or product reference.
  
  Must match at least one alternative.
  2 fields / alternatives
  - Request · brief.source · anyOf 1Alternative
    
    object
    
    Unknown fields are not accepted.
    
    2 fields
    
    Request · brief.source · anyOf 1.clipIdRequired
    
    string
    
    Source clip identifier.
    
    Minimum characters: 1.
    
    Request · brief.source · anyOf 1.typeRequired
    
    "suno"
    
    Source or product type discriminator.
  - Request · brief.source · anyOf 2Alternative
    
    object
    
    Unknown fields are not accepted.
    
    6 fields
    
    Request · brief.source · anyOf 2.audioUrlRequired
    
    string
    
    Public HTTP(S) audio URL.
    
    Format: uri.
    
    Request · brief.source · anyOf 2.typeRequired
    
    "audio"
    
    Source or product type discriminator.
    
    Request · brief.source · anyOf 2.durationSecOptional
    
    number
    
    Requested or known media duration in seconds.
    
    Exclusive lower bound: 0.
    
    Request · brief.source · anyOf 2.lyricsOptional
    
    string
    
    Lyrics or lyric context supplied to the operation.
    
    Maximum characters: 5000.
    
    Request · brief.source · anyOf 2.musicStyleOptional
    
    string
    
    Optional song genre, mood or musical style used to guide automatic visual planning.
    
    Maximum characters: 500.
    
    Request · brief.source · anyOf 2.titleOptional
    
    string
    
    Optional customer-facing title.
    
    Maximum characters: 200.
- Request · brief.aspectRatioOptional
  
  "16:9" | "9:16" | "1:1" | "4:3" | "3:4"
  
  Requested output aspect ratio.
- Request · brief.characterImageOptional
  
  string
  
  Public character reference image URL.
  
  Format: uri.
- Request · brief.descriptionOptional
  
  string
  
  Optional customer-facing resource description.
  
  Maximum characters: 2000.
- Request · 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".
- Request · 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".
- Request · brief.referenceImagesOptional
  
  array<string>
  
  Public reference image URLs.
  
  Maximum items: 6.
  1 field
  - Request · brief.referenceImages[]Each item
    
    string
    
    Format: uri.
- Request · 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.
- Request · 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".
- Request · 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.
- Request · brief.styleIdOptional
  
  "auto" | "cinematic" | "anime" | "ink" | "3d" | "vaporwave" | "brand"
  
  Omit or use auto to let the planner choose visual art direction.
  
  Default: "auto".
- Request · brief.subtitlesOptional
  
  boolean
  
  Whether subtitles are enabled for the MV.
Request · expectedVersionRequired

string | integer

Optimistic-concurrency guard using the current resource version.

Minimum: 1. Must match at least one alternative.
2 fields / alternatives
- Request · expectedVersion · anyOf 1Alternative
  
  string
  
  Format: integer. Default: 0.
- Request · expectedVersion · anyOf 2Alternative
  
  integer
  
  Minimum: 1.

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

curl --globoff --request PUT \
  --url 'https://api.omnapi.com/api/v1/mv/drafts/{id}' \
  --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/v1/mv/drafts/{id}", {
  method: "PUT",
  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(
    "PUT", "https://api.omnapi.com/api/v1/mv/drafts/{id}",
    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

Save creative draft

Request

Request · briefRequired

Request · brief.sourceRequired

Request · brief.source · anyOf 1Alternative

Request · brief.source · anyOf 1.clipIdRequired

Request · brief.source · anyOf 1.typeRequired

Request · brief.source · anyOf 2Alternative

Request · brief.source · anyOf 2.audioUrlRequired

Request · brief.source · anyOf 2.typeRequired

Request · brief.source · anyOf 2.durationSecOptional

Request · brief.source · anyOf 2.lyricsOptional

Request · brief.source · anyOf 2.musicStyleOptional

Request · brief.source · anyOf 2.titleOptional

Request · brief.aspectRatioOptional

Request · brief.characterImageOptional

Request · brief.descriptionOptional

Request · brief.engineVersionOptional

Request · brief.performanceModeOptional

Request · brief.referenceImagesOptional

Request · brief.referenceImages[]Each item

Request · brief.renderTierOptional

Request · brief.resolutionOptional

Request · brief.scheduleOptional

Request · brief.styleIdOptional

Request · brief.subtitlesOptional

Request · expectedVersionRequired

Request · expectedVersion · anyOf 1Alternative

Request · expectedVersion · anyOf 2Alternative

Responses

Response 200 · briefRequired

Response 200 · brief.sourceRequired

Response 200 · brief.source · anyOf 1Alternative

Response 200 · brief.source · anyOf 1.clipIdRequired

Response 200 · brief.source · anyOf 1.typeRequired

Response 200 · brief.source · anyOf 2Alternative

Response 200 · brief.source · anyOf 2.audioUrlRequired

Response 200 · brief.source · anyOf 2.typeRequired

Response 200 · brief.source · anyOf 2.durationSecOptional

Response 200 · brief.source · anyOf 2.lyricsOptional

Response 200 · brief.source · anyOf 2.musicStyleOptional

Response 200 · brief.source · anyOf 2.titleOptional

Response 200 · brief.aspectRatioOptional

Response 200 · brief.characterImageOptional

Response 200 · brief.descriptionOptional

Response 200 · brief.engineVersionOptional

Response 200 · brief.performanceModeOptional

Response 200 · brief.referenceImagesOptional

Response 200 · brief.referenceImages[]Each item

Response 200 · brief.renderTierOptional

Response 200 · brief.resolutionOptional

Response 200 · brief.scheduleOptional

Response 200 · brief.styleIdOptional

Response 200 · brief.subtitlesOptional

Response 200 · expiresAtRequired

Response 200 · idRequired

Response 200 · planRequired

Response 200 · plan.performanceModeRequired

Response 200 · plan.requiresPortraitRequired

Response 200 · plan.statusRequired

Response 200 · plan.styleRequired

Response 200 · plan.warningCodesOptional

Response 200 · plan.warningCodes[]Each item

Response 200 · versionRequired

Response 200 · version · anyOf 1Alternative

Response 200 · version · anyOf 2Alternative

Response 400 · errorRequired

Response 400 · error.codeRequired

Response 400 · error.messageRequired

Response 400 · error.detailsOptional

Response 400 · successRequired

Response 401 · errorRequired

Response 401 · error.codeRequired

Response 401 · error.messageRequired

Response 401 · error.detailsOptional

Response 401 · successRequired

Response 403 · errorRequired

Response 403 · error.codeRequired

Response 403 · error.messageRequired

Response 403 · error.detailsOptional

Request · `brief`Required

Request · `brief.source`Required

Request · `brief.source · anyOf 1`Alternative

Request · `brief.source · anyOf 1.clipId`Required

Request · `brief.source · anyOf 1.type`Required

Request · `brief.source · anyOf 2`Alternative

Request · `brief.source · anyOf 2.audioUrl`Required

Request · `brief.source · anyOf 2.type`Required

Request · `brief.source · anyOf 2.durationSec`Optional

Request · `brief.source · anyOf 2.lyrics`Optional

Request · `brief.source · anyOf 2.musicStyle`Optional

Request · `brief.source · anyOf 2.title`Optional

Request · `brief.aspectRatio`Optional

Request · `brief.characterImage`Optional

Request · `brief.description`Optional

Request · `brief.engineVersion`Optional

Request · `brief.performanceMode`Optional

Request · `brief.referenceImages`Optional

Request · `brief.referenceImages[]`Each item

Request · `brief.renderTier`Optional

Request · `brief.resolution`Optional

Request · `brief.schedule`Optional

Request · `brief.styleId`Optional

Request · `brief.subtitles`Optional

Request · `expectedVersion`Required

Request · `expectedVersion · anyOf 1`Alternative

Request · `expectedVersion · anyOf 2`Alternative

Response 200 · `brief`Required

Response 200 · `brief.source`Required

Response 200 · `brief.source · anyOf 1`Alternative

Response 200 · `brief.source · anyOf 1.clipId`Required

Response 200 · `brief.source · anyOf 1.type`Required

Response 200 · `brief.source · anyOf 2`Alternative

Response 200 · `brief.source · anyOf 2.audioUrl`Required

Response 200 · `brief.source · anyOf 2.type`Required

Response 200 · `brief.source · anyOf 2.durationSec`Optional

Response 200 · `brief.source · anyOf 2.lyrics`Optional

Response 200 · `brief.source · anyOf 2.musicStyle`Optional

Response 200 · `brief.source · anyOf 2.title`Optional

Response 200 · `brief.aspectRatio`Optional

Response 200 · `brief.characterImage`Optional

Response 200 · `brief.description`Optional

Response 200 · `brief.engineVersion`Optional

Response 200 · `brief.performanceMode`Optional

Response 200 · `brief.referenceImages`Optional

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

Response 200 · `brief.renderTier`Optional

Response 200 · `brief.resolution`Optional

Response 200 · `brief.schedule`Optional

Response 200 · `brief.styleId`Optional

Response 200 · `brief.subtitles`Optional

Response 200 · `expiresAt`Required

Response 200 · `id`Required

Response 200 · `plan`Required

Response 200 · `plan.performanceMode`Required

Response 200 · `plan.requiresPortrait`Required

Response 200 · `plan.status`Required

Response 200 · `plan.style`Required

Response 200 · `plan.warningCodes`Optional

Response 200 · `plan.warningCodes[]`Each item

Response 200 · `version`Required

Response 200 · `version · anyOf 1`Alternative

Response 200 · `version · anyOf 2`Alternative

Response 400 · `error`Required

Response 400 · `error.code`Required

Response 400 · `error.message`Required

Response 400 · `error.details`Optional

Response 400 · `success`Required

Response 401 · `error`Required

Response 401 · `error.code`Required

Response 401 · `error.message`Required

Response 401 · `error.details`Optional

Response 401 · `success`Required

Response 403 · `error`Required

Response 403 · `error.code`Required

Response 403 · `error.message`Required

Response 403 · `error.details`Optional

Response 403 · `success`Required

Response 404 · `error`Required

Response 404 · `error.code`Required