idpath · RequiredResource identifier returned by the corresponding create operation.
Minimum characters: 1. Maximum characters: 128./api/v2/mv/videos/{id}/adoptAuthentication · x-api-key
Free (the candidates were paid with the edit). picks covers every changed shot: a ready candidate index or "original". The same picks can be sent again; the video then composes and is delivered. 409 MV_CENTER_EDIT_NOT_PENDING when it is not waiting for a selection.
Scope: task:create
Billing and effects: Free: picks candidates already paid for with the edit; the edited video then composes and is delivered.
Recovery: Read the current resource before retrying a mutation; do not assume this operation supports Idempotency-Key.
Follow this operation’s workflow → · All permission rulesOmn music video endpoint. Check capabilities and preflight before purchasing. How Music Video requests work
idpath · RequiredResource identifier returned by the corresponding create operation.
Minimum characters: 1. Maximum characters: 128.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.
picksRequiredFor every changed shot: a ready candidate index, or "original" to keep the old shot.
picks[key]Each valueKey pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$. Use a complete option below; the value must satisfy at least one option.
Option 1 — string | integerOptionMinimum: 1. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionFormat: integer. Default: 0.
Option 2 — integerOptionMinimum: 1.
Option 2 — "original"OptionRead 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 itemcandidatesOptionalCandidates of an edit version (null for other videos).
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires status, count, chainStale, adoptedAt, shotsOptionCandidates of an edit version (null for other videos).
candidates.adoptedAtRequiredWhen the selection was adopted.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionWhen the selection was adopted.
Option 2 — nullOptioncandidates.chainStaleRequiredShots that continue from a changed shot's last frame and keep their old clip.
candidates.chainStale[]Each itemcandidates.countRequiredCandidates per changed shot.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — integerOptionCandidates per changed shot.
Option 2 — nullOptioncandidates.shotsRequiredChanged shots with their candidates.
candidates.shots[]Each itemcandidates.shots[].adoptedRequiredAdopted pick.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — integer | "original"OptionAdopted pick.
Use a complete option below; the value must satisfy at least one option.
Option 1 — integerOptionOption 2 — "original"OptionOption 2 — nullOptioncandidates.shots[].candidatesRequiredCandidates made for this shot.
candidates.shots[].candidates[]Each itemcandidates.shots[].candidates[].adoptedRequiredWhether this candidate was adopted.
candidates.shots[].candidates[].indexRequiredPick this number in adopt.
candidates.shots[].candidates[].previewUrlRequiredOmnAPI link (send your API key) to the bytes; null when the file is not available.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionOmnAPI link (send your API key) to the bytes; null when the file is not available.
Option 2 — nullOptioncandidates.shots[].candidates[].qcRequiredAutomatic check of the candidate; null when not checked.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires verdict, fails, warnsOptionAutomatic check of the candidate; null when not checked.
candidates.shots[].candidates[].qc.failsRequiredFailed checks.
candidates.shots[].candidates[].qc.fails[]Each itemcandidates.shots[].candidates[].qc.verdictRequiredAutomatic check verdict.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionAutomatic check verdict.
Option 2 — nullOptioncandidates.shots[].candidates[].qc.warnsRequiredWarnings.
candidates.shots[].candidates[].qc.warns[]Each itemOption 2 — nullOptioncandidates.shots[].candidates[].repairRequiredExtra candidate made after all failed checks.
candidates.shots[].candidates[].secondsRequiredClip length in seconds.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — numberOptionClip length in seconds.
Option 2 — nullOptioncandidates.shots[].candidates[].statusRequiredOnly ready can be picked.
Default: "ready".
candidates.shots[].candidates[].thumbnailUrlRequiredOmnAPI link (send your API key) to the bytes; null when the file is not available.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionOmnAPI link (send your API key) to the bytes; null when the file is not available.
Option 2 — nullOptioncandidates.shots[].changeRequiredHow the requested attribute change was applied; null for a shots + instruction edit.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires sentence, conflictsOptionHow the requested attribute change was applied; null for a shots + instruction edit.
candidates.shots[].change.conflictsRequiredRequested changes not applied.
candidates.shots[].change.conflicts[]Each itemcandidates.shots[].change.sentenceRequiredThe shot's new description.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionThe shot's new description.
Option 2 — nullOptionOption 2 — nullOptioncandidates.shots[].firstFrameRequiredWhether the shot's first frame was drawn again for this edit.
candidates.shots[].firstFrame.reasonRequiredWhy it was not redrawn.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionWhy it was not redrawn.
Option 2 — nullOptioncandidates.shots[].firstFrame.redrawnRequiredWhether the first frame was drawn again.
candidates.shots[].instructionRequiredThe change as applied.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionThe change as applied.
Option 2 — nullOptioncandidates.shots[].shotRequiredChanged shot.
candidates.statusRequiredgenerating, ready, awaiting_selection or adopted.
Option 2 — nullOptioneditOptionalThe edit that made this version; null for a purchase.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — action = "regenerate" | "recut"OptionThe edit that made this version; null for a purchase.
edit.actionRequiredEdit bought.
Default: "regenerate".
edit.candidatesRequiredCandidates billed per shot.
edit.shotsRequiredShots regenerated.
edit.shots[]Each itemOption 2 — nullOptionetaOptionalEstimate while queued or processing; null otherwise. An estimate, not a commitment; local delivery adds a few minutes.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires queuePosition, startAt, finishAt, remainingSecondsOptionEstimate while queued or processing; null otherwise. An estimate, not a commitment; local delivery adds a few minutes.
eta.finishAtRequiredEstimated generation finish (ISO 8601).
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionEstimated generation finish (ISO 8601).
Option 2 — nullOptioneta.queuePositionRequiredPlace in the generation queue; 0 = running.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — integerOptionPlace in the generation queue; 0 = running.
Minimum: 0.
Option 2 — nullOptioneta.remainingSecondsRequiredEstimated seconds remaining.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — integerOptionEstimated seconds remaining.
Minimum: 0.
Option 2 — nullOptioneta.startAtRequiredEstimated or actual generation start (ISO 8601).
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionEstimated or actual generation start (ISO 8601).
Option 2 — nullOptionOption 2 — nullOptionparentIdOptionalThe video this version was edited from; null for a purchase.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionThe video this version was edited from; null for a purchase.
Option 2 — nullOptionqualityOptionalQuality grade of a completed video; null before completion.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires grade, issuesOptionQuality grade of a completed video; null before completion.
quality.gradeRequiredRelease grade of the delivered video: A, B or C. C is still a completed, charged delivery; see issues.
quality.issuesRequiredWhat the grade reflects; empty for a clean A.
quality.issues[]Each itemOne finding behind the grade.
quality.issues[].typeRequiredconstraint_not_met, constraint_unverified, beat_missing, beat_unverified or shot_defect.
quality.issues[].atOptionalTime spans in the delivered video, [startSec, endSec].
quality.issues[].at[]Each itemMinimum items: 2. Maximum items: 2.
quality.issues[].at[][]Each itemquality.issues[].defectsOptionalRemaining defect kinds of the shot.
quality.issues[].defects[]Each itemquality.issues[].shotOptionalShot id (shot_defect).
quality.issues[].textOptionalThe brief requirement concerned, in words.
Option 2 — nullOptionstageOptionalGeneration stage while queued or processing: planning, generating, reviewing, composing or delivering. Null otherwise or when unknown.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionGeneration stage while queued or processing: planning, generating, reviewing, composing or delivering. Null otherwise or when unknown.
Option 2 — nullOptionwaitingOptionalAction needed before the version continues.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires reasonOptionAction needed before the version continues.
waiting.reasonRequiredWhy generation is paused while still processing: storyboard_approval, review (held for a quality review before release) or candidate_selection (adopt one candidate per changed shot with POST /videos/{id}/adopt). Null otherwise.
Option 2 — nullOptionapplication/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
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