Skip to content

    API documentation

    Quote an edit of an Omn video

    POST/api/v2/mv/videos/{id}/edits/quote

    Authentication · 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 rules

    Omn music video endpoint. Check capabilities and preflight before purchasing. How Music Video requests work

    Request

    Path parameters

    idpath · Required
    string

    Resource identifier returned by the corresponding create operation.

    Minimum characters: 1. Maximum characters: 128.

    JSON request body

    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, optional and null

    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.

    • Request · actionRequired

      "regenerate" | "recut"

      regenerate: 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".

    • Request · candidatesOptional

      string | integer

      regenerate: 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.

      2 options
      • Request · Option 1 — stringOption

        string

        Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1, maximum 4). Prefer a JSON number.

        Format: integer.

      • Request · Option 2 — integerOption

        integer

        regenerate: 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.

    • Request · changesOptional

      array<object>

      regenerate by attributes (exclusive with shots / instruction). Candidates are made and the new version waits for POST /adopt.

      Minimum items: 1. Maximum items: 90.

      1 field
      • Request · changes[]Each item

        object

        Only the listed fields are accepted in this object.

        4 fields
        • Request · changes[].shotRequired

          string

          Shot id as listed by the edit quote, storyboard or timeline.

          Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.

        • Request · changes[].instructionOptional

          string

          Optional free-text change for this shot, applied together with set.

          Maximum characters: 1000.

        • Request · changes[].keepOptional

          array<"identity" | "action" | "lip_sync" | "framing">

          Attributes to preserve. Keeping an attribute you also change is rejected.

          Maximum items: 4.

          1 field
          • Request · changes[].keep[]Each item

            "identity" | "action" | "lip_sync" | "framing"

            Default: "identity".

        • Request · changes[].setOptional

          object

          Attributes of the shot to change.

          Only the listed fields are accepted in this object.

          9 fields
          • Request · changes[].set.actionOptional

            string

            New action of the people in the shot. Sung shots keep their singer and sung line.

            Maximum characters: 300.

          • Request · changes[].set.cameraOptional

            string

            New camera angle or movement.

            Maximum characters: 300.

          • Request · changes[].set.lightOptional

            string

            New lighting.

            Maximum characters: 300.

          • Request · changes[].set.peopleOptional

            string

            Only fewer people than the shot has, or the background.

            Maximum characters: 300.

          • Request · changes[].set.placeOptional

            string

            New location of the shot.

            Maximum characters: 300.

          • Request · changes[].set.shotSizeOptional

            "close" | "medium" | "wide"

            New shot size.

            Default: "close".

          • Request · changes[].set.timeOfDayOptional

            "dawn" | "morning" | "midday" | "afternoon" | "golden_hour" | "dusk" | "night"

            New time of day.

            Default: "dawn".

          • Request · changes[].set.wardrobeOptional

            string

            Other clothing for the same person; face, hair and build do not change.

            Maximum characters: 300.

          • Request · changes[].set.weatherOptional

            string

            New weather.

            Maximum characters: 300.

    • Request · instructionOptional

      string

      regenerate with shots: what to change.

      Minimum characters: 1. Maximum characters: 1000.

    • Request · lyricsOverlayOptional

      boolean

      recut: ask for the lyric layer on or off.

    • Request · shotsOptional

      array<string>

      regenerate: shots to make again (at most 15% of the video's shots).

      Minimum items: 1. Maximum items: 90.

      1 field
      • Request · shots[]Each item

        string

        Shot id as listed by the edit quote, storyboard or timeline.

        Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.

    • Request · timelineOptional

      array<object>

      recut: the whole new cut (24 fps frames) from GET /videos/{id}/timeline; the center checks every rule.

      Minimum items: 1. Maximum items: 4.

      1 field
      • Request · timeline[]Each item

        object

        Only the listed fields are accepted in this object.

        2 fields
        • Request · timeline[].editsRequired

          array<object>

          The complete new cut for this format, in order, starting at frame 0 and covering the whole song.

          Minimum items: 1. Maximum items: 600.

          1 field
          • Request · timeline[].edits[]Each item

            object

            Only the listed fields are accepted in this object.

            5 fields
            • Request · timeline[].edits[].endFrameRequired

              string | integer

              Frame 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.

              2 options
              • Request · Option 1 — stringOption

                string

                Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1). Prefer a JSON number.

                Format: integer.

              • Request · Option 2 — integerOption

                integer

                Frame after the last frame of this edit in the new cut (24 fps).

                Minimum: 1.

            • Request · timeline[].edits[].shotRequired

              string

              Shot id as listed by the edit quote, storyboard or timeline.

              Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_./-]{0,120}$.

            • Request · timeline[].edits[].startFrameRequired

              string | integer

              First 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.

              2 options
              • Request · Option 1 — stringOption

                string

                Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 0). Prefer a JSON number.

                Format: integer.

              • Request · Option 2 — integerOption

                integer

                First frame of this edit in the new cut (24 fps).

                Minimum: 0.

            • Request · timeline[].edits[].sourceInFrameOptional

              string | integer

              Frame 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.

              2 options
              • Request · Option 1 — stringOption

                string

                Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 0). Prefer a JSON number.

                Format: integer.

              • Request · Option 2 — integerOption

                integer

                Frame of the shot's clip where this edit starts; by default sung edits stay locked to the vocal.

                Minimum: 0.

            • Request · timeline[].edits[].takeOptional

              string

              Existing take of the shot, as listed in the timeline; defaults to the take in the current cut.

              Minimum characters: 1. Maximum characters: 40.

        • Request · timeline[].variantOptional

          string

          Format the cut belongs to, as listed in the timeline; omit for a single-format video.

          Maximum characters: 40.

    Responses

    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.

    HTTP 401 · Request rejected; correct the key before retrying

    Complete JSON example (optional fields may be omitted).

    {
    "success": false,
    "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
    }
    }
    200 OK

    application/json

    Required, optional and null

    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.

    • Response 200 · actionRequired

      "regenerate" | "recut"

      Edit priced.

      Default: "regenerate".

    • Response 200 · allowedRequired

      boolean

      false: the same edit would be refused (see refusals); nothing is charged.

    • Response 200 · etaRequired

      object

      Expected delivery of the new version; values are null when unknown.

      2 fields
      • Response 200 · eta.finishAtRequired

        string | null

        Expected delivery time.

        May be null. Use a complete option below; the value must satisfy at least one option.

        2 options
      • Response 200 · eta.secondsRequired

        number | null

        Expected seconds until delivery.

        May be null. Use a complete option below; the value must satisfy at least one option.

        2 options
    • Response 200 · priceRequired

      object | null

      Price; credits = creditsPerSecond x billableSeconds x candidates.

      May be null. Use a complete option below; the value must satisfy at least one option.

      2 options
    • Response 200 · refusalsRequired

      array<object>

      Every reason the edit would be refused.

      1 field
    • Response 200 · shotsRequired

      object

      Impact of the edit.

      2 fields
      • Response 200 · shots.affectedRequired

        array<object>

        Every shot the edit touches, with its relation to a requested shot, the effect and where it is on screen.

        1 field
      • Response 200 · shots.regenerateRequired

        array<string>

        Shots that will be made again.

        1 field
    • Response 200 · sourcesRequired

      object

      Whether the stored editing material of this video is still available.

      2 fields
      • Response 200 · sources.availableRequired

        boolean

        Whether the kept clips are still stored.

      • Response 200 · sources.editableUntilRequired

        string | null

        Editing material is kept until this time.

        May be null. Use a complete option below; the value must satisfy at least one option.

        2 options
    • Response 200 · videoIdRequired

      string

      The video to edit.

    • Response 200 · warningsRequired

      array<object>

      Advisories, e.g. chain_stale.

      1 field
    400 Bad Request

    application/json

    Required, optional and null

    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.

    • Response 400 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 400 · successRequired

      false

      Always false for error responses

    401 Unauthorized

    application/json

    Required, optional and null

    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.

    • Response 401 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 401 · successRequired

      false

      Always false for error responses

    402 Payment Required

    application/json

    Required, optional and null

    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.

    • Response 402 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 402 · error.codeRequired

        string

        Application-specific error code (see error catalog)

      • Response 402 · error.messageRequired

        string

        Human readable error message

      • Response 402 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 402 · successRequired

      false

      Always false for error responses

    403 Forbidden

    application/json

    Required, optional and null

    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.

    • Response 403 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 403 · successRequired

      false

      Always false for error responses

    404 Not Found

    application/json

    Required, optional and null

    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.

    • Response 404 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 404 · successRequired

      false

      Always false for error responses

    409 Conflict

    application/json

    Required, optional and null

    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.

    • Response 409 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 409 · successRequired

      false

      Always false for error responses

    413 Payload Too Large

    application/json

    Required, optional and null

    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.

    • Response 413 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 413 · error.codeRequired

        string

        Application-specific error code (see error catalog)

      • Response 413 · error.messageRequired

        string

        Human readable error message

      • Response 413 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 413 · successRequired

      false

      Always false for error responses

    422 Unprocessable Entity

    application/json

    Required, optional and null

    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.

    • Response 422 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 422 · error.codeRequired

        string

        Application-specific error code (see error catalog)

      • Response 422 · error.messageRequired

        string

        Human readable error message

      • Response 422 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 422 · 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

    Required, optional and null

    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.

    • Response 429 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 429 · error.codeRequired

        string

        RATE_LIMITED for request and task admission rejections.

      • Response 429 · error.messageRequired

        string

        Human-readable explanation. Wording may change; use the machine-readable code for programmatic decisions.

      • Response 429 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        9 fields
        • Response 429 · error.details.currentOptional

          integer

          Current count for the rate-limit window identified by policy and scope.

          Minimum: 0.

        • Response 429 · error.details.inFlightOptional

          integer

          Current accepted tasks counted against the relevant account or API-key admission limit.

          Minimum: 0.

        • Response 429 · error.details.limitOptional

          integer

          Maximum count allowed by this response context. A limit is not a throughput guarantee.

          Minimum: 0.

        • Response 429 · error.details.policyOptional

          "operation" | "query"

          Allowance bucket: query for resource reads, operation for task-producing or operation requests. See the rate-limit response headers.

        • Response 429 · error.details.retryAfterSecOptional

          integer

          Suggested delay in seconds before another request. Honor the Retry-After header when present; use bounded backoff.

          Minimum: 1.

        • Response 429 · error.details.scopeOptional

          "user" | "api-key" | "ip" | "apiKey"

          Entity whose allowance was exceeded, such as the user, API key or IP address.

        • Response 429 · error.details.tierOptional

          "FREE" | "PREMIUM" | "ENTERPRISE"

          Account allowance tier used for this admission or rate-limit decision.

        • Response 429 · error.details.typeOptional

          "rps" | "daily" | "monthly"

          Admission limit that rejected the request: rps (continuously refilled requests-per-second bucket), daily or monthly UTC request budget. Interpret with policy, scope and retryAfterSec.

        • Response 429 · error.details[key]Each value

          any JSON value

          Key pattern: ^(.*)$.

    • Response 429 · successRequired

      false

      Whether this response reports a successful action; false accompanies the structured error object.

      Default: false.

    500 Internal Server Error

    application/json

    Required, optional and null

    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.

    • Response 500 · errorRequired

      object

      Structured 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.

      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

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 500 · successRequired

      false

      Always false for error responses

    502 Bad Gateway

    application/json

    Required, optional and null

    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.

    • Response 502 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 502 · error.codeRequired

        string

        Application-specific error code (see error catalog)

      • Response 502 · error.messageRequired

        string

        Human readable error message

      • Response 502 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 502 · successRequired

      false

      Always false for error responses

    503 Service Unavailable

    application/json

    Required, optional and null

    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.

    • Response 503 · errorRequired

      object

      Structured 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.

      3 fields
      • Response 503 · error.codeRequired

        string

        Application-specific error code (see error catalog)

      • Response 503 · error.messageRequired

        string

        Human readable error message

      • Response 503 · error.detailsOptional

        object

        Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

        1 field
    • Response 503 · successRequired

      false

      Always false for error responses

    Workflow and next steps → · Recover an uncertain request

    Interactive API Explorer → · OpenAPI JSON