idpath · RequiredResource identifier returned by the corresponding create operation.
Minimum characters: 1. Maximum characters: 128./api/v2/mv/videos/{id}/edits/quoteAuthentication · x-api-key
Free and read-only. Which shots are made again and which are affected, every reason the edit would be refused (allowed=false), the expected delivery time and the price: regenerate = rate x seconds of the regenerated shots in the cut (at least 1) x candidates; recut = rate x 10.
Scope: task:read
Billing and effects: Free validation or estimate; no generation purchase, price reservation or capacity reservation.
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
The edit to price. Same body as POST /videos/{id}/edits without maxCredits / webhookUrl.
The edit to price. Same body as POST /videos/{id}/edits without maxCredits / webhookUrl.
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.
actionRequiredregenerate: make the listed shots again (shots + instruction, or attribute changes) and recompose. recut: compose the cut again from existing clips (optionally an edited timeline); nothing is generated. Both create a new video; the original stays unchanged.
Default: "regenerate".
candidatesOptionalregenerate: candidates per shot (default 2 with changes, 1 with shots). With candidates the new version waits for POST /adopt. Each candidate is billed.
Minimum: 1. Maximum: 4. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionNumeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1, maximum 4). Prefer a JSON number.
Format: integer.
Option 2 — integerOptionregenerate: candidates per shot (default 2 with changes, 1 with shots). With candidates the new version waits for POST /adopt. Each candidate is billed.
Minimum: 1. Maximum: 4.
changesOptionalregenerate by attributes (exclusive with shots / instruction). Candidates are made and the new version waits for POST /adopt.
Minimum items: 1. Maximum items: 90.
changes[]Each itemOnly the listed fields are accepted in this object.
changes[].shotRequiredShot id as listed by the edit quote, storyboard or timeline.
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.
changes[].instructionOptionalOptional free-text change for this shot, applied together with set.
Maximum characters: 1000.
changes[].keepOptionalAttributes to preserve. Keeping an attribute you also change is rejected.
Maximum items: 4.
changes[].keep[]Each itemDefault: "identity".
changes[].setOptionalAttributes of the shot to change.
Only the listed fields are accepted in this object.
changes[].set.actionOptionalNew action of the people in the shot. Sung shots keep their singer and sung line.
Maximum characters: 300.
changes[].set.cameraOptionalNew camera angle or movement.
Maximum characters: 300.
changes[].set.lightOptionalNew lighting.
Maximum characters: 300.
changes[].set.peopleOptionalOnly fewer people than the shot has, or the background.
Maximum characters: 300.
changes[].set.placeOptionalNew location of the shot.
Maximum characters: 300.
changes[].set.shotSizeOptionalNew shot size.
Default: "close".
changes[].set.timeOfDayOptionalNew time of day.
Default: "dawn".
changes[].set.wardrobeOptionalOther clothing for the same person; face, hair and build do not change.
Maximum characters: 300.
changes[].set.weatherOptionalNew weather.
Maximum characters: 300.
instructionOptionalregenerate with shots: what to change.
Minimum characters: 1. Maximum characters: 1000.
lyricsOverlayOptionalrecut: ask for the lyric layer on or off.
shotsOptionalregenerate: shots to make again (at most 15% of the video's shots).
Minimum items: 1. Maximum items: 90.
shots[]Each itemShot id as listed by the edit quote, storyboard or timeline.
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.
timelineOptionalrecut: the whole new cut (24 fps frames) from GET /videos/{id}/timeline; the center checks every rule.
Minimum items: 1. Maximum items: 4.
timeline[]Each itemOnly the listed fields are accepted in this object.
timeline[].editsRequiredThe complete new cut for this format, in order, starting at frame 0 and covering the whole song.
Minimum items: 1. Maximum items: 600.
timeline[].edits[]Each itemOnly the listed fields are accepted in this object.
timeline[].edits[].endFrameRequiredFrame after the last frame of this edit in the new cut (24 fps).
Minimum: 1. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionNumeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1). Prefer a JSON number.
Format: integer.
Option 2 — integerOptionFrame after the last frame of this edit in the new cut (24 fps).
Minimum: 1.
timeline[].edits[].shotRequiredShot id as listed by the edit quote, storyboard or timeline.
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.
timeline[].edits[].startFrameRequiredFirst frame of this edit in the new cut (24 fps).
Minimum: 0. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionNumeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 0). Prefer a JSON number.
Format: integer.
Option 2 — integerOptionFirst frame of this edit in the new cut (24 fps).
Minimum: 0.
timeline[].edits[].sourceInFrameOptionalFrame of the shot's clip where this edit starts; by default sung edits stay locked to the vocal.
Minimum: 0. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionNumeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 0). Prefer a JSON number.
Format: integer.
Option 2 — integerOptionFrame of the shot's clip where this edit starts; by default sung edits stay locked to the vocal.
Minimum: 0.
timeline[].edits[].takeOptionalExisting take of the shot, as listed in the timeline; defaults to the take in the current cut.
Minimum characters: 1. Maximum characters: 40.
timeline[].variantOptionalFormat the cut belongs to, as listed in the timeline; omit for a single-format video.
Maximum characters: 40.
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.
actionRequiredEdit priced.
Default: "regenerate".
allowedRequiredfalse: the same edit would be refused (see refusals); nothing is charged.
etaRequiredExpected delivery of the new version; values are null when unknown.
eta.finishAtRequiredExpected delivery time.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionExpected delivery time.
Option 2 — nullOptioneta.secondsRequiredExpected seconds until delivery.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — numberOptionExpected seconds until delivery.
Option 2 — nullOptionpriceRequiredPrice; credits = creditsPerSecond x billableSeconds x candidates.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — requires credits, creditsPerSecond, billableSeconds, candidates, resolution, pricingVersionOptionPrice; credits = creditsPerSecond x billableSeconds x candidates.
price.billableSecondsRequiredregenerate: seconds of the regenerated shots in the cut (min 1); recut: 10.
price.candidatesRequiredCandidates billed per shot.
price.creditsRequiredCredits the edit costs now.
price.creditsPerSecondRequiredRate of the video's resolution.
price.pricingVersionRequiredEdit price card.
price.resolutionRequiredResolution of the video.
Option 2 — nullOptionrefusalsRequiredEvery reason the edit would be refused.
refusals[]Each itemrefusals[].codeRequiredReason code.
refusals[].messageRequiredExplanation.
refusals[].limitOptionalLimit, e.g. most shots per regenerate.
refusals[].shotsOptionalShots concerned.
refusals[].shots[]Each itemshotsRequiredImpact of the edit.
shots.affectedRequiredEvery shot the edit touches, with its relation to a requested shot, the effect and where it is on screen.
shots.affected[]Each itemshots.affected[].atRequiredSeconds of the current cut where the shot is on screen.
shots.affected[].at[]Each itemMinimum items: 2. Maximum items: 2.
shots.affected[].at[][]Each itemshots.affected[].effectRequiredregenerated, unchanged or keeps_old_take_chain_stale.
shots.affected[].ofRequiredThe requested shot it relates to.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionThe requested shot it relates to.
Option 2 — nullOptionshots.affected[].relationRequiredrequested, chained_after, same_first_frame, same_reference or same_take.
shots.affected[].shotRequiredShot.
shots.regenerateRequiredShots that will be made again.
shots.regenerate[]Each itemsourcesRequiredWhether the stored editing material of this video is still available.
sources.availableRequiredWhether the kept clips are still stored.
sources.editableUntilRequiredEditing material is kept until this time.
May be null. Use a complete option below; the value must satisfy at least one option.
Option 1 — stringOptionEditing material is kept until this time.
Option 2 — nullOptionvideoIdRequiredThe video to edit.
warningsRequiredAdvisories, e.g. chain_stale.
warnings[]Each itemwarnings[].codeRequiredReason code.
warnings[].messageRequiredExplanation.
warnings[].limitOptionalLimit, e.g. most shots per regenerate.
warnings[].shotsOptionalShots concerned.
warnings[].shots[]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
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