Idempotency-Keyheader · RequiredUnique 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./api/v2/mv/Authentication · x-api-key
Omn V1 independent product API. Independent Omn request, planning and delivery semantics.
Idempotency-Keyheader · RequiredUnique 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.
preflightIdRequiredUnexpired preflight identifier bound to this user, API key and exact creative request.
Minimum characters: 1. Maximum characters: 100.
maxCreditsOptionalMaximum authorized customer charge. A lower cap rejects the purchase without reducing the requested output.
Minimum: 1.
quoteIdOptionalReplaces the quote captured at preflight. When omitted, an explicit maxCredits replaces it; otherwise the preflight quote applies.
Minimum characters: 1. Maximum characters: 100.
application/json
Unknown fields are not accepted.
autoFinalizeRequiredcontractVersionRequiredcreditsRequiredRequiredMinimum: 0.
deliveryStatusRequiredfinalUrlRequiredMay be null. Must match at least one alternative.
finalUrl · anyOf 1AlternativefinalUrl · anyOf 2AlternativelinksRequiredUnknown fields are not accepted.
links.finalRequiredMay be null. Must match at least one alternative.
links.final · anyOf 1AlternativeFinal downloadable resource URL when available
links.final · anyOf 2Alternativelinks.resourceRequiredMay be null. Must match at least one alternative.
links.resource · anyOf 1AlternativeProduct resource URL when the product has a dedicated view endpoint
links.resource · anyOf 2Alternativelinks.streamRequiredTask SSE stream URL for the created task
links.taskRequiredTask polling URL for the created task
mvIdRequiredpollUrlRequiredpricingRequiredUnknown fields are not accepted.
pricing.adjustmentCreditsRequiredchargedCredits - baseCredits
pricing.baseCreditsRequiredStandard quoted credits before customer pricing adjustment
pricing.chargedCreditsRequiredCredits charged for this create request
Minimum: 0.
pricing.quoteVersionRequiredPricing quote version stored with the task
pricing.sourceRequiredPublic pricing source category
pricing.billingIncrementCreditsOptionalSmallest customer charge increment
Minimum: 0.0001.
pricing.calculatedCreditsOptionalPrecise whole-order subtotal before settlement rounding
pricing.settlementPolicyVersionOptionalVersioned customer settlement policy
pricing.settlementRoundingCreditsOptionalWhole-order rounding adjustment added at settlement
Minimum: 0.
productRequiredUnknown fields are not accepted.
product.featureCodeRequiredResolved feature code
product.resourceIdRequiredMay be null. Must match at least one alternative.
product.resourceId · anyOf 1AlternativeProduct resource id when created synchronously
product.resourceId · anyOf 2Alternativeproduct.typeRequiredProduct family for this task, e.g. suno, producer, mv
product.autoFinalizeOptionalWhether the product should finalize automatically
product.deliveryStatusOptionalMay be null. Must match at least one alternative.
product.deliveryStatus · anyOf 1AlternativeProduct-level delivery status when applicable
product.deliveryStatus · anyOf 2AlternativerequestIdRequiredMay be null. Must match at least one alternative.
requestId · anyOf 1AlternativeRequest id echoed from X-Request-Id or generated by API
requestId · anyOf 2AlternativestatusRequiredtaskIdRequiredviewUrlRequiredwarningCodesRequiredwarningCodes[]Each itemMV 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.
creativeOptionalMust match at least one alternative.
creative · anyOf 1AlternativeUnknown fields are not accepted.
creative · anyOf 1.presetRequiredcreative · anyOf 1.singingOptionalDefault: "allowed".
creative · anyOf 2AlternativeUnknown fields are not accepted.
creative · anyOf 2.presetRequiredcreative · anyOf 2.singingOptionalDefault: "allowed".
creative · anyOf 3AlternativeUnknown fields are not accepted.
creative · anyOf 3.presetRequiredcreative · anyOf 3.storySourceRequiredDefault: "lyrics".
creative · anyOf 3.singingOptionalDefault: "allowed".
creative · anyOf 4AlternativeUnknown fields are not accepted.
creative · anyOf 4.presetRequiredDefault: "sing".
creative · anyOf 5AlternativeCreative intent, independent of output resolution.
Unknown fields are not accepted.
creative · anyOf 5.modeRequiredauto, story, mood, perform, sing, dance, sing_dance or sing_play. All use the same request envelope.
Default: "auto".
creative · anyOf 5.briefOptionalDescribe the desired story, subjects, action and mood. Required for a brief-led story.
Maximum characters: 3000.
creative · anyOf 5.charactersOptionalWhether characters may appear and the desired count.
Unknown fields are not accepted.
creative · anyOf 5.characters.policyRequiredauto lets the director decide; required mandates characters; forbidden excludes them and conflicts with performance modes or character references.
Default: "auto".
creative · anyOf 5.characters.countOptionalDesired number of main characters (1 or 2); cannot be combined with forbidden.
Minimum: 1. Maximum: 2. Must match at least one alternative.
creative · anyOf 5.characters.count · anyOf 1AlternativeDesired number of main characters (1 or 2); cannot be combined with forbidden.
Format: integer. Default: 0.
creative · anyOf 5.characters.count · anyOf 1See schemaExpand this value in the interactive reference.
Format: integer. Default: 0.
creative · anyOf 5.characters.count · anyOf 2AlternativeDesired number of main characters (1 or 2); cannot be combined with forbidden.
Minimum: 1. Maximum: 2.
creative · anyOf 5.characters.count · anyOf 2See schemaExpand this value in the interactive reference.
Minimum: 1. Maximum: 2.
creative · anyOf 5.optionsOptionalMode-specific choices; irrelevant options are rejected.
Unknown fields are not accepted.
creative · anyOf 5.options.combinationOptionalRequired for sing_dance or sing_play. alternating uses separate shots. simultaneous requests same-shot actions and currently returns 422 before debit.
Default: "alternating".
creative · anyOf 5.options.instrumentOptionalInstrument to feature in perform or sing_play.
Minimum characters: 1. Maximum characters: 100.
creative · anyOf 5.options.storySourceOptionalRequired for story: lyrics uses song evidence; brief uses creative.brief.
Default: "lyrics".
creative · anyOf 5.styleOptionalVisual treatment passed to director planning and shot generation.
Maximum characters: 1000.
estimatedCompletionTimeOptionalMay be null. Must match at least one alternative.
estimatedCompletionTime · anyOf 1AlternativeEstimated completion time
Must match at least one alternative.
estimatedCompletionTime · anyOf 1 · anyOf 1AlternativeEstimated completion time
estimatedCompletionTime · anyOf 1 · anyOf 2AlternativeFormat: date-time.
estimatedCompletionTime · anyOf 1 · anyOf 3AlternativeFormat: date.
estimatedCompletionTime · anyOf 1 · anyOf 4AlternativeestimatedCompletionTime · anyOf 2AlternativeoutputOptionalUnknown fields are not accepted.
output.aspectRatioOptionalDelivery aspect ratio; defaults to 16:9. Motion references require 16:9 or 9:16.
output.renderTierOptionalOmn 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.
output.resolutionOptional540p, 720p, 1080p or 1440p for every mode. Defaults to 720p. Motion output may be resized from its source resolution.
requestedOutputOptionalUnknown fields are not accepted.
requestedOutput.aspectRatioOptionalDelivery aspect ratio; defaults to 16:9. Motion references require 16:9 or 9:16.
requestedOutput.renderTierOptionalOmn 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.
requestedOutput.resolutionOptional540p, 720p, 1080p or 1440p for every mode. Defaults to 720p. Motion output may be resized from its source resolution.
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
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
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
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
errorRequirederror.codeRequiredRATE_LIMITED for request and task admission rejections.
error.messageRequirederror.detailsOptionalOptional 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.
error.details.currentOptionalMinimum: 0.
error.details.inFlightOptionalMinimum: 0.
error.details.limitOptionalMinimum: 0.
error.details.policyOptionalerror.details.retryAfterSecOptionalMinimum: 1.
error.details.scopeOptionalerror.details.tierOptionalerror.details.typeOptionalsuccessRequiredDefault: false.
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses