Skip to content

    API documentation

    Read an Omn quote

    GET/api/v2/mv/quotes/{id}

    Authentication · x-api-key

    Your own quote with its frozen spec, price and status: valid until expiresAt, used once bought, or expired.

    Scope: task:read

    Billing and effects: Free resource read; no generation purchase.

    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.

    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 · expiresAtRequired

      string

      Buy before this time (ISO 8601).

    • Response 200 · idRequired

      string

      Quote id; buy it once with POST /videos {quoteId}.

    • Response 200 · priceRequired

      object

      Price fixed by the quote.

      3 fields
      • Response 200 · price.billableSecondsRequired

        integer

        Effective output seconds, rounded up.

        Minimum: 0.

      • Response 200 · price.creditsRequired

        number

        Credits charged on purchase.

        Minimum: 0.

      • Response 200 · price.creditsPerSecondRequired

        number

        Rate for the chosen resolution, per billable second.

        Minimum: 0.

    • Response 200 · specRequired

      object

      The normalized request, with defaults filled in.

      Only the listed fields are accepted in this object.

      6 fields
      • Response 200 · spec.sourceRequired

        object

        The song.

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

        2 options
        • Response 200 · Option 1 — type = "audio_url"Option

          object

          Only the listed fields are accepted in this object.

          4 fields
          • Response 200 · spec.source.typeRequired

            "audio_url"

            Audio from a public URL.

          • Response 200 · spec.source.urlRequired

            string

            Public HTTPS audio URL (MP3, WAV, AAC, M4A; ≤ 128 MB).

            Maximum characters: 4096. Format: uri.

          • Response 200 · spec.source.lyricsOptional

            string

            Song lyrics, one line per line; improve story and captions.

            Maximum characters: 5000.

          • Response 200 · spec.source.rangeOptional

            object

            Use only this part of the song (10–600 s).

            Only the listed fields are accepted in this object.

            2 fields
        • Response 200 · Option 2 — type = "suno_clip"Option

          object

          Only the listed fields are accepted in this object.

          4 fields
          • Response 200 · spec.source.clipIdRequired

            string

            Suno clip id you own.

            Minimum characters: 1. Maximum characters: 128.

          • Response 200 · spec.source.typeRequired

            "suno_clip"

            Audio from your Suno clip.

          • Response 200 · spec.source.lyricsOptional

            string

            Song lyrics, one line per line; improve story and captions.

            Maximum characters: 5000.

          • Response 200 · spec.source.rangeOptional

            object

            Use only this part of the song (10–600 s).

            Only the listed fields are accepted in this object.

            2 fields
      • Response 200 · spec.captionsOptional

        object

        Burned-in captions.

        Only the listed fields are accepted in this object.

        4 fields
        • Response 200 · spec.captions.modeRequired

          "off" | "auto" | "provided"

          off, auto (timed from the audio) or provided (your SRT).

          Default: "off".

        • Response 200 · spec.captions.languageOptional

          "auto" | "en" | "zh"

          Caption language: auto (detect from the song), en (English) or zh (Chinese).

          Default: "auto".

        • Response 200 · spec.captions.requiredOptional

          boolean

          Fail instead of delivering without captions.

        • Response 200 · spec.captions.srtUrlOptional

          string

          Public SRT URL (≤ 4 MB), times relative to the used range.

          Maximum characters: 4096. Format: uri.

      • Response 200 · spec.creativeOptional

        object

        What the video shows.

        Only the listed fields are accepted in this object.

        5 fields
        • Response 200 · spec.creative.briefOptional

          string

          What the video shows: story, setting, people, events.

          Maximum characters: 3000.

        • Response 200 · spec.creative.modeOptional

          "auto" | "sing" | "story" | "mood"

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

        • Response 200 · spec.creative.peopleOptional

          "auto" | "none"

          none: no people or characters on screen (not with sing).

          Default: "auto".

        • Response 200 · spec.creative.storySourceOptional

          "lyrics" | "brief"

          Required 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".

        • Response 200 · spec.creative.styleOptional

          string

          Visual treatment: look, palette, camera feel.

          Maximum characters: 1000.

      • Response 200 · spec.outputOptional

        object

        Resolution and aspect ratio.

        Only the listed fields are accepted in this object.

        2 fields
        • Response 200 · spec.output.aspectRatioOptional

          "16:9" | "9:16" | "1:1" | "4:3" | "3:4" | "3:2" | "2:3" | "21:9" | "5:4" | "4:5" | "9:21"

          Aspect ratio of the video.

          Default: "16:9".

        • Response 200 · spec.output.resolutionOptional

          "480p" | "768p" | "1080p" | "1440p"

          Delivery 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".

      • Response 200 · spec.referencesOptional

        object

        Reference images.

        Only the listed fields are accepted in this object.

        3 fields
        • Response 200 · spec.references.locationsOptional

          array<string>

          Up to three images of places to show.

          Maximum items: 3.

          1 field
        • Response 200 · spec.references.performerOptional

          object

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

          2 fields
        • Response 200 · spec.references.stylesOptional

          array<string>

          Up to three images that set the visual style, not identity.

          Maximum items: 3.

          1 field
      • Response 200 · spec.titleOptional

        string

        Video title.

        Maximum characters: 200.

    • Response 200 · statusRequired

      "valid" | "used" | "expired"

      valid until expiresAt; used once bought.

      Default: "valid".

    • Response 200 · warningsRequired

      array<string>

      Advisory warning codes for this request.

      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