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/videosAuthentication · x-api-key
Buys a quote (quoteId) once, or quotes and buys a spec in one step. Requires Idempotency-Key; credits are debited when the video is created and refunded on failure or confirmed cancellation.
Scope: task:create
Billing and effects: Paid operation: credits are authorized when the Task is accepted. Review the quote or preflight and save the receipt.
Recovery: Save one Idempotency-Key with the exact request body before submission. Reuse both after an uncertain response.
Follow this operation’s workflow → · All permission rulesOmn music video endpoint. Check capabilities and preflight before purchasing. How Music Video requests work
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.Content-Type: application/json · Required body
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
Only the listed fields are accepted in this object.
maxCreditsOptionalCharge authorization ceiling; the purchase fails before debit when the price is higher.
Minimum: 1.
quoteIdOptionalBuy a quote from POST /quotes (once). Exclusive with spec.
Minimum characters: 1. Maximum characters: 100.
specOptionalQuote and buy this spec in one step. Exclusive with quoteId.
Only the listed fields are accepted in this object.
spec.sourceRequiredThe song.
Use a complete option below; the value must satisfy at least one option.
Option 1 — type = "audio_url"OptionOnly the listed fields are accepted in this object.
spec.source.typeRequiredAudio from a public URL.
spec.source.urlRequiredPublic HTTPS audio URL (MP3, WAV, AAC, M4A; ≤ 128 MB).
Maximum characters: 4096. Format: uri.
spec.source.lyricsOptionalSong lyrics, one line per line; improve story and captions.
Maximum characters: 5000.
spec.source.rangeOptionalUse only this part of the song (10–600 s).
Only the listed fields are accepted in this object.
spec.source.range.endSecRequiredEnd of the used audio, seconds.
Exclusive lower bound: 0.
spec.source.range.startSecRequiredStart of the used audio, seconds.
Minimum: 0.
Option 2 — type = "suno_clip"OptionOnly the listed fields are accepted in this object.
spec.source.clipIdRequiredSuno clip id you own.
Minimum characters: 1. Maximum characters: 128.
spec.source.typeRequiredAudio from your Suno clip.
spec.source.lyricsOptionalSong lyrics, one line per line; improve story and captions.
Maximum characters: 5000.
spec.source.rangeOptionalUse only this part of the song (10–600 s).
Only the listed fields are accepted in this object.
spec.source.range.endSecRequiredEnd of the used audio, seconds.
Exclusive lower bound: 0.
spec.source.range.startSecRequiredStart of the used audio, seconds.
Minimum: 0.
spec.captionsOptionalBurned-in captions.
Only the listed fields are accepted in this object.
spec.captions.modeRequiredoff, auto (timed from the audio) or provided (your SRT).
Default: "off".
spec.captions.languageOptionalCaption language: auto (detect from the song), en (English) or zh (Chinese).
Default: "auto".
spec.captions.requiredOptionalFail instead of delivering without captions.
spec.captions.srtUrlOptionalPublic SRT URL (≤ 4 MB), times relative to the used range.
Maximum characters: 4096. Format: uri.
spec.creativeOptionalWhat the video shows.
Only the listed fields are accepted in this object.
spec.creative.briefOptionalWhat the video shows: story, setting, people, events.
Maximum characters: 3000.
spec.creative.modeOptionalauto: Omn chooses the direction and whether people appear (no singing). sing: the referenced performer sings the song (lip-synced, requires references.performer). story: a narrative from the lyrics or brief (requires storySource). mood: atmospheric visuals.
Default: "auto".
spec.creative.peopleOptionalnone: no people or characters on screen (not with sing).
Default: "auto".
spec.creative.storySourceOptionalRequired when mode is story, not allowed otherwise. lyrics: tell the story of the lyrics. brief: tell the story in creative.brief (brief required).
Default: "lyrics".
spec.creative.styleOptionalVisual treatment: look, palette, camera feel.
Maximum characters: 1000.
spec.outputOptionalResolution and aspect ratio.
Only the listed fields are accepted in this object.
spec.output.aspectRatioOptionalAspect ratio of the video.
Default: "16:9".
spec.output.resolutionOptionalDelivery resolution. 480p and 768p are native; 1080p and 1440p (2K) are AI-upscaled from 768p. Default 768p. If 1080p/1440p cannot be delivered the video fails and the entire charge is refunded.
Default: "480p".
spec.referencesOptionalReference images.
Only the listed fields are accepted in this object.
spec.references.locationsOptionalUp to three images of places to show.
Maximum items: 3.
spec.references.locations[]Each itemPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
spec.references.performerOptionalThe singer (required for sing) or main character: one PNG, JPEG or WebP image, at most 10 MB.
Only the listed fields are accepted in this object.
spec.references.performer.imageUrlRequiredPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
spec.references.performer.descriptionOptionalWho this is; helps keep the identity consistent.
Maximum characters: 500.
spec.references.stylesOptionalUp to three images that set the visual style, not identity.
Maximum items: 3.
spec.references.styles[]Each itemPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
spec.titleOptionalVideo title.
Maximum characters: 200.
webhookUrlOptionalHTTPS URL that receives this video's webhook events (task.* and mv.ready / mv.failed). See the webhook guide for bodies and signatures.
Maximum characters: 4096. Format: uri.
Read the HTTP status and body together. A receipt confirms acceptance; poll the returned Task or product view for terminal execution and media delivery. Example IDs and credit amounts are illustrative, not a price quote.
Complete JSON example (optional fields may be omitted).
{ "success": false, "error": { "code": "INVALID_API_KEY", "message": "Invalid API key" }}application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
createdAtRequiredCreation time (ISO 8601).
failureRequiredWhy the video failed; null unless status is failed.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires code, message, retryableOptionWhy the video failed; null unless status is failed.
failure.codeRequiredError code.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionError code.
Option 2 — nullOptionfailure.messageRequiredHuman-readable reason.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionHuman-readable reason.
Option 2 — nullOptionfailure.retryableRequiredWhether buying again may succeed unchanged.
Option 2 — nullOptionidRequiredVideo id.
linksRequiredRelated resources.
links.chargesRequiredCharges and refunds.
links.eventsRequiredSSE progress stream.
links.fileRequiredDelivered file link; null until completed.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionDelivered file link; null until completed.
Option 2 — nullOptionlinks.selfRequiredThis video.
links.shotsRequiredPer-shot progress.
priceRequiredCharge and refund so far.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires credits, refundedCreditsOptionCharge and refund so far.
price.creditsRequiredCredits charged.
Minimum: 0.
price.refundedCreditsRequiredCredits refunded.
Minimum: 0.
Option 2 — nullOptionprogressRequiredProgress percent.
Minimum: 0. Maximum: 100.
specRequiredWhat was bought.
spec.creativeRequiredWhat the video shows.
Only the listed fields are accepted in this object.
spec.creative.briefOptionalWhat the video shows: story, setting, people, events.
Maximum characters: 3000.
spec.creative.modeOptionalauto: Omn chooses the direction and whether people appear (no singing). sing: the referenced performer sings the song (lip-synced, requires references.performer). story: a narrative from the lyrics or brief (requires storySource). mood: atmospheric visuals.
Default: "auto".
spec.creative.peopleOptionalnone: no people or characters on screen (not with sing).
Default: "auto".
spec.creative.storySourceOptionalRequired when mode is story, not allowed otherwise. lyrics: tell the story of the lyrics. brief: tell the story in creative.brief (brief required).
Default: "lyrics".
spec.creative.styleOptionalVisual treatment: look, palette, camera feel.
Maximum characters: 1000.
spec.outputRequiredDelivered output.
spec.output.aspectRatioRequiredDelivered aspect ratio.
spec.output.resolutionRequiredPurchased delivery resolution: 480p, 768p, 1080p or 1440p.
spec.sourceRequiredAudio used for the video.
spec.source.typeRequiredAudio source kind.
Default: "audio_url".
spec.source.durationSecOptionalEffective audio length in seconds.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — numberOptionEffective audio length in seconds.
Option 2 — nullOptionspec.source.endSecOptionalSelected range end in seconds.
spec.source.startSecOptionalSelected range start in seconds.
spec.titleRequiredVideo title.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionVideo title.
Option 2 — nullOptionstatusRequiredProduct status of the video.
Default: "queued".
taskIdRequiredThe generation Task; Task webhooks and /api/v1/tasks/{taskId} carry this id.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionThe generation Task; Task webhooks and /api/v1/tasks/{taskId} carry this id.
Option 2 — nullOptionupdatedAtRequiredLast change (ISO 8601).
warningsRequiredAdvisory warning codes.
warnings[]Each itemapplication/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
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
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
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
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredRATE_LIMITED for request and task admission rejections.
error.messageRequiredHuman-readable explanation. Wording may change; use the machine-readable code for programmatic decisions.
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details.currentOptionalCurrent count for the rate-limit window identified by policy and scope.
Minimum: 0.
error.details.inFlightOptionalCurrent accepted tasks counted against the relevant account or API-key admission limit.
Minimum: 0.
error.details.limitOptionalMaximum count allowed by this response context. A limit is not a throughput guarantee.
Minimum: 0.
error.details.policyOptionalAllowance bucket: query for resource reads, operation for task-producing or operation requests. See the rate-limit response headers.
error.details.retryAfterSecOptionalSuggested delay in seconds before another request. Honor the Retry-After header when present; use bounded backoff.
Minimum: 1.
error.details.scopeOptionalEntity whose allowance was exceeded, such as the user, API key or IP address.
error.details.tierOptionalAccount allowance tier used for this admission or rate-limit decision.
error.details.typeOptionalAdmission limit that rejected the request: rps (continuously refilled requests-per-second bucket), daily or monthly UTC request budget. Interpret with policy, scope and retryAfterSec.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredWhether this response reports a successful action; false accompanies the structured error object.
Default: false.
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses
application/json
Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.
errorRequiredStructured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.
error.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalOptional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.
error.details[key]Each valueKey pattern: ^(.*)$.
successRequiredAlways false for error responses