Skip to content

    API documentation

    Check a OneClick V1 request for Omn

    POST/api/v2/mv/migrations/v1-check

    Authentication · x-api-key

    Translates a /api/v1/mv create body into an Omn spec, lists every field mapping, what would block migration and both prices. Charges nothing and validates no media.

    Scope: task:create

    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

    JSON request body

    Content-Type: application/json · Required body

    These groups describe alternative shapes of the same JSON value, not extra wrapper fields. Field names below are actual JSON paths.

    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.

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

    • Request · Option 1 — mode = "fast"Option

      object

      Only the listed fields are accepted in this object.

      20 fields
      • Request · modeRequired

        "fast"

        Operation or product mode discriminator for this schema variant.

      • Request · sourceRequired

        object

        Choose one source: a Suno clip ID or publicly reachable audio URL. Use range to select a segment; supplied duration is only a hint and media preflight validates the actual audio.

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

        2 options
        • Request · Option 1 — type = "suno"Option

          object

          Only the listed fields are accepted in this object.

          4 fields
          • Request · source.clipIdRequired

            string

            Source clip identifier.

            Minimum characters: 1.

          • Request · source.typeRequired

            "suno"

            Source or product type discriminator.

          • Request · source.lyricsOptional

            string

            Lyrics or lyric context supplied to the operation.

            Maximum characters: 5000.

          • Request · source.rangeOptional

            object

            Optional source-media range.

            2 fields
            • Request · source.range.endSecOptional

              number

              End offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

            • Request · source.range.startSecOptional

              number

              Start offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

        • Request · Option 2 — type = "audio"Option

          object

          Only the listed fields are accepted in this object.

          7 fields
          • Request · source.audioUrlRequired

            string

            Public HTTP(S) audio URL.

            Format: uri.

          • Request · source.typeRequired

            "audio"

            Source or product type discriminator.

          • Request · source.durationSecOptional

            number

            Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.

            Exclusive lower bound: 0.

          • Request · source.lyricsOptional

            string

            Lyrics or lyric context supplied to the operation.

            Maximum characters: 5000.

          • Request · source.musicStyleOptional

            string

            Optional song genre, mood or musical style used to guide automatic visual planning.

            Maximum characters: 500.

          • Request · source.rangeOptional

            object

            Optional source-media range.

            2 fields
            • Request · source.range.endSecOptional

              number

              End offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

            • Request · source.range.startSecOptional

              number

              Start offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

          • Request · source.titleOptional

            string

            Optional song title used as creative context; does not force a visual style or performance mode.

            Maximum characters: 200.

      • Request · aspectRatioOptional

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

        Requested output aspect ratio.

      • Request · characterImageOptional

        string

        Public character reference image URL.

        Minimum characters: 1.

      • Request · configOptional

        object

        Standard task configuration: priority, tags, metadata, and webhookUrl.

        4 fields
        • Request · config.metadataOptional

          object

          Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

          1 field
        • Request · config.priorityOptional

          number

          Task priority 1-10 (higher = sooner). Default 5.

          Minimum: 1. Maximum: 10. Default: 5.

        • Request · config.tagsOptional

          array<string>

          Free-form labels for filtering. Up to 20, 100 chars each.

          Maximum items: 20.

          1 field
          • Request · config.tags[]Each item

            string

            Maximum characters: 100.

        • Request · config.webhookUrlOptional

          string

          URL to receive task.* lifecycle events via the central webhook service.

          Format: uri.

      • Request · generationOptional

        object

        API v1 generation settings. Choose engineVersion before engine-specific options. Explicit omn-v1 accepts performanceMode with managedVersion omitted or premium-v2; performance modes reject lipSync and quality. Use the input reference for cross-field rules.

        Only the listed fields are accepted in this object.

        16 fields
        • Request · generation.creativeModeOptional

          "auto" | "lyrics_story" | "prompt_story" | "mood_visual" | "performance" | "sing_dance" | "sing_play"

          API v1 creative direction. Default auto lets the song guide narrative, concept, performance or mixed scenes. lyrics_story follows lyrics; prompt_story requires a nonempty top-level prompt; mood_visual follows atmosphere; performance leads with performance; Omn-only sing_dance and sing_play must not be combined with performanceMode. Explicit lipSync=false forbids singing lip-sync.

        • Request · generation.engineVersionOptional

          "vidu-v1" | "omn-v1"

          Explicit MV generation option: vidu-v1 (OneClick V1) or omn-v1 (Omn native 480p/768p or AI-upscaled 1080p/1440p; OneClick 540p maps to 480p, 720p to 768p). OneClick V2 Turbo (vidu-v2) is retired.

        • Request · generation.lipReferenceImagesOptional

          array<string>

          Ordered singer portrait URLs for Omn singing (sing/sing_perform). Omn sings with one performer; the first item is the singer.

          Minimum items: 1. Maximum items: 2.

          1 field
        • Request · generation.managedVersionOptional

          "oneclick-v1"

          Compatibility request profile. Only oneclick-v1 is purchasable; OneClick V2 Turbo (premium-v2) is retired.

        • Request · generation.motionPresetOptional

          "stable_performance" | "cinematic_light" | "dynamic_dance" | "lip_sync_closeup"

          Fast MV motion prompt policy.

        • Request · generation.motionReferenceVideoOptional

          string

          Omn V1 Premium V2 dance only: public HTTPS URL of a motion reference video whose moves drive dance shots (render tiers draft/standard). Requires motionRightsConfirmed=true. The URL must declare its size (at most 128 MB) and, when it declares a content type, a video/* or application/octet-stream one; otherwise 400 VALIDATION_ERROR on this field. The video should be 2–660 seconds long with a short side of at least 240 px and a long side of at most 4096 px; its audio is not used (each dance shot uses a silent clip aligned to its song window, looping a shorter video). Motion transfer applies only to 16:9 and 9:16 MVs, and a 16:9 or 9:16 request is rejected with 422 MV_ENGINE_UNSUPPORTED (reason specialist_mode_unsupported) before any charge when motion transfer is unavailable; other aspect ratios, and videos that turn out to be unusable (unreachable, not decodable, or outside these bounds), dance without motion transfer at the same price.

          Minimum characters: 1.

        • Request · generation.motionRightsConfirmedOptional

          true

          Required with motionReferenceVideo: you confirm you hold the rights to use the motion footage.

        • Request · generation.performanceModeOptional

          "sing" | "sing_perform" | "perform" | "dance"

          Omn compatibility only (with engineVersion=omn-v1): sing / sing_perform select singing. OneClick V2 Turbo modes are retired.

        • Request · generation.promptModeOptional

          "auto" | "verbatim" | "creative_brief"

          Whether Fast MV preserves or compiles the caller prompt.

        • Request · generation.qualityOptional

          "standard" | "high"

          Requested public quality tier.

        • Request · generation.referenceStrategyOptional

          "direct" | "synthesize"

          Fast MV policy for direct or synthesized references.

        • Request · generation.renderTierOptional

          "draft" | "standard" | "hd" | "ultra"

          Omn only; resolution determines the purchased tier: draft 480p, standard 768p, hd 1080p, ultra 1440p. 1080p/1440p are AI-upscaled from 768p. quality=high is unavailable; use standard quality. Historical purchased plans retain their original tiers.

        • Request · generation.scheduleOptional

          "standard" | "economy"

          Omn V1 only. economy renders shots only in the off-peak window at the same video price as standard scheduling, with a longer delivery window: shots start between 00:00 and 07:40 Beijing time (no new shot in the window's last 20 minutes, so none runs into peak pricing). MVView.generation.scheduleWindow reports the window the waiting shots are bought in; its offPeakEndsAt is the 08:00 window end.

        • Request · generation.styleOptional

          string

          Requested creative style direction.

          Maximum characters: 200.

        • Request · generation.subtitleModeOptional

          "vidu" | "custom"

          Fast MV subtitle rendering mode.

        • Request · generation.visualBoardOptional

          object

          Fast MV Visual Board configuration.

          Only the listed fields are accepted in this object.

          2 fields
      • Request · languageOptional

        "auto" | "en" | "zh"

        Requested or known language code/name.

      • Request · lipSyncOptional

        boolean

        Whether the MV should use the supported lip-sync workflow.

      • Request · maxCreditsOptional

        number

        Maximum OmnAPI credits authorized for this paid request.

        Minimum: 1.

      • Request · omniOptional

        object

        Direct multimodal plan (omni-task-v1). Not available on the execution center; requests carrying it are rejected before any charge.

        Only the listed fields are accepted in this object.

        8 fields
        • Request · omni.defaultsRequired

          object

          Materials and prompt used by every scene without an override.

          Only the listed fields are accepted in this object.

          7 fields
          • Request · omni.defaults.imageIdsRequired

            array<string>

            Ids of reference images from images.

            Maximum items: 9.

            1 field
            • Request · omni.defaults.imageIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

          • Request · omni.defaults.audioDeliveryOptional

            "original-song" | "generated"

            Original song is the default. Generated sound is time-fitted together with the complete picture to the MV scene window.

          • Request · omni.defaults.audioIdsOptional

            array<string>

            Ids of reference audio from audios.

            Maximum items: 3.

            1 field
            • Request · omni.defaults.audioIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

          • Request · omni.defaults.firstFrameIdOptional

            string

            Image id used as the first frame of the scene.

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

          • Request · omni.defaults.lastFrameIdOptional

            string

            Image id used as the last frame of the scene.

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

          • Request · omni.defaults.promptOptional

            string

            Scene prompt used with these materials.

            Minimum characters: 1. Maximum characters: 3000.

          • Request · omni.defaults.videoIdsOptional

            array<string>

            Ids of reference clips from videos.

            Maximum items: 3.

            1 field
            • Request · omni.defaults.videoIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

        • Request · omni.versionRequired

          "omni-task-v1"

          Requested compatibility or resource version.

        • Request · omni.audiosOptional

          array<object>

          Reference audio available to scene bindings.

          Maximum items: 16.

          1 field
          • Request · omni.audios[]Each item

            object

            Only the listed fields are accepted in this object.

            3 fields
            • Request · omni.audios[].durationSecRequired

              number

              Audio length in seconds.

              Minimum: 0.2. Maximum: 15.

            • Request · omni.audios[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.audios[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

        • Request · omni.imagesOptional

          array<object>

          Reference images available to scene bindings.

          Maximum items: 32.

          1 field
          • Request · omni.images[]Each item

            object

            Only the listed fields are accepted in this object.

            2 fields
            • Request · omni.images[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.images[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

        • Request · omni.planningOptional

          "director" | "direct"

          Director is the default. Direct uses customer scene prompts and complete fixed 5/10-second windows, without generative planning.

        • Request · omni.shotDurationSecOptional

          5 | 10

          Direct planning only; default 5. The effective song selection must be a multiple of this window.

        • Request · omni.shotsOptional

          array<object>

          Per-scene overrides of the default binding.

          Maximum items: 120.

          1 field
          • Request · omni.shots[]Each item

            object

            Only the listed fields are accepted in this object.

            8 fields
            • Request · omni.shots[].imageIdsRequired

              array<string>

              Ids of reference images from images.

              Maximum items: 9.

              1 field
              • Request · omni.shots[].imageIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

            • Request · omni.shots[].sceneIndexRequired

              string | integer

              Zero-based index in the persisted director plan. Overrides replace the complete default binding; unknown indices fail before any GPU purchase.

              Minimum: 0. Maximum: 119. 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, maximum 119). Prefer a JSON number.

                Format: integer.

              • Request · Option 2 — integerOption

                integer

                Zero-based index in the persisted director plan. Overrides replace the complete default binding; unknown indices fail before any GPU purchase.

                Minimum: 0. Maximum: 119.

            • Request · omni.shots[].audioDeliveryOptional

              "original-song" | "generated"

              Original song is the default. Generated sound is time-fitted together with the complete picture to the MV scene window.

            • Request · omni.shots[].audioIdsOptional

              array<string>

              Ids of reference audio from audios.

              Maximum items: 3.

              1 field
              • Request · omni.shots[].audioIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

            • Request · omni.shots[].firstFrameIdOptional

              string

              Image id used as the first frame of the scene.

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

            • Request · omni.shots[].lastFrameIdOptional

              string

              Image id used as the last frame of the scene.

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

            • Request · omni.shots[].promptOptional

              string

              Scene prompt used with these materials.

              Minimum characters: 1. Maximum characters: 3000.

            • Request · omni.shots[].videoIdsOptional

              array<string>

              Ids of reference clips from videos.

              Maximum items: 3.

              1 field
              • Request · omni.shots[].videoIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

        • Request · omni.videosOptional

          array<object>

          Reference video clips available to scene bindings.

          Maximum items: 16.

          1 field
          • Request · omni.videos[]Each item

            object

            Only the listed fields are accepted in this object.

            4 fields
            • Request · omni.videos[].durationSecRequired

              number

              Clip length in seconds.

              Minimum: 0.2. Maximum: 5.

            • Request · omni.videos[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.videos[].includeAudioRequired

              boolean

              Whether the clip's own sound may be used.

            • Request · omni.videos[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

      • Request · preflightIdOptional

        string

        Reusable MV preflight snapshot identifier.

        Minimum characters: 1. Maximum characters: 100.

      • Request · promptOptional

        string

        Primary creative or operation instruction.

        Maximum characters: 3000.

      • Request · quoteIdOptional

        string

        Short-lived quote identifier for the matching paid operation.

        Minimum characters: 1. Maximum characters: 100.

      • Request · referenceImagesOptional

        array<string>

        Public reference image URLs.

        Maximum items: 7.

        1 field
      • Request · resolutionOptional

        "480p" | "540p" | "720p" | "768p" | "1080p" | "1440p"

        Delivery resolution. Default 540p for OneClick. Omn accepts native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p and 720p to 768p. OneClick does not support 480p, 768p or 1440p.

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

        6 options
        • Request · Option 1 — "480p"Option

          "480p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 2 — "540p"Option

          "540p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 3 — "720p"Option

          "720p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 4 — "768p"Option

          "768p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 5 — "1080p"Option

          "1080p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 6 — "1440p"Option

          "1440p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

      • Request · srtUrlOptional

        string

        Public URL of caller-supplied SRT subtitles.

        Minimum characters: 1.

      • Request · subtitleOptional

        object

        MV subtitle generation and fallback policy.

        Only the listed fields are accepted in this object.

        6 fields
        • Request · subtitle.fallbackOptional

          "fail" | "continue_without_subtitles"

          Behavior when the preferred subtitle path cannot complete.

        • Request · subtitle.languageOptional

          "auto" | "en" | "zh"

          Requested or known language code/name.

        • Request · subtitle.maxCostUsdPerMinOptional

          number

          Maximum accepted public subtitle price in USD per minute.

          Minimum: 0.001. Maximum: 1.

        • Request · subtitle.modeOptional

          "auto" | "provided" | "off"

          Operation or product mode discriminator for this schema variant.

        • Request · subtitle.qualityOptional

          "standard" | "premium"

          Requested public quality tier.

        • Request · subtitle.requiredOptional

          boolean

          Whether the selected subtitle policy must succeed.

      • Request · subtitleColorOptional

        string

        Requested subtitle foreground color.

        Maximum characters: 20.

      • Request · subtitlesOptional

        boolean

        Whether subtitles are enabled for the MV.

      • Request · titleOptional

        string

        Optional customer-facing title.

        Maximum characters: 200.

    • Request · Option 2 — mode = "studio"Option

      object

      Only the listed fields are accepted in this object.

      20 fields
      • Request · modeRequired

        "studio"

        Operation or product mode discriminator for this schema variant.

      • Request · sourceRequired

        object

        Choose one source: a Suno clip ID or publicly reachable audio URL. Use range to select a segment; supplied duration is only a hint and media preflight validates the actual audio.

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

        2 options
        • Request · Option 1 — type = "suno"Option

          object

          Only the listed fields are accepted in this object.

          4 fields
          • Request · source.clipIdRequired

            string

            Source clip identifier.

            Minimum characters: 1.

          • Request · source.typeRequired

            "suno"

            Source or product type discriminator.

          • Request · source.lyricsOptional

            string

            Lyrics or lyric context supplied to the operation.

            Maximum characters: 5000.

          • Request · source.rangeOptional

            object

            Optional source-media range.

            2 fields
            • Request · source.range.endSecOptional

              number

              End offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

            • Request · source.range.startSecOptional

              number

              Start offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

        • Request · Option 2 — type = "audio"Option

          object

          Only the listed fields are accepted in this object.

          7 fields
          • Request · source.audioUrlRequired

            string

            Public HTTP(S) audio URL.

            Format: uri.

          • Request · source.typeRequired

            "audio"

            Source or product type discriminator.

          • Request · source.durationSecOptional

            number

            Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.

            Exclusive lower bound: 0.

          • Request · source.lyricsOptional

            string

            Lyrics or lyric context supplied to the operation.

            Maximum characters: 5000.

          • Request · source.musicStyleOptional

            string

            Optional song genre, mood or musical style used to guide automatic visual planning.

            Maximum characters: 500.

          • Request · source.rangeOptional

            object

            Optional source-media range.

            2 fields
            • Request · source.range.endSecOptional

              number

              End offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

            • Request · source.range.startSecOptional

              number

              Start offset in seconds in the containing timeline or selected source range.

              Minimum: 0.

          • Request · source.titleOptional

            string

            Optional song title used as creative context; does not force a visual style or performance mode.

            Maximum characters: 200.

      • Request · aspectRatioOptional

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

        Requested output aspect ratio.

      • Request · characterImageOptional

        string

        Public character reference image URL.

        Minimum characters: 1.

      • Request · configOptional

        object

        Standard task configuration: priority, tags, metadata, and webhookUrl.

        4 fields
        • Request · config.metadataOptional

          object

          Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

          1 field
        • Request · config.priorityOptional

          number

          Task priority 1-10 (higher = sooner). Default 5.

          Minimum: 1. Maximum: 10. Default: 5.

        • Request · config.tagsOptional

          array<string>

          Free-form labels for filtering. Up to 20, 100 chars each.

          Maximum items: 20.

          1 field
          • Request · config.tags[]Each item

            string

            Maximum characters: 100.

        • Request · config.webhookUrlOptional

          string

          URL to receive task.* lifecycle events via the central webhook service.

          Format: uri.

      • Request · generationOptional

        object

        Product-specific generation controls.

        Only the listed fields are accepted in this object.

        3 fields
      • Request · languageOptional

        "auto" | "en" | "zh"

        Requested or known language code/name.

      • Request · lipSyncOptional

        boolean

        Whether the MV should use the supported lip-sync workflow.

      • Request · maxCreditsOptional

        number

        Maximum OmnAPI credits authorized for this paid request.

        Minimum: 1.

      • Request · omniOptional

        object

        Direct multimodal plan (omni-task-v1). Not available on the execution center; requests carrying it are rejected before any charge.

        Only the listed fields are accepted in this object.

        8 fields
        • Request · omni.defaultsRequired

          object

          Materials and prompt used by every scene without an override.

          Only the listed fields are accepted in this object.

          7 fields
          • Request · omni.defaults.imageIdsRequired

            array<string>

            Ids of reference images from images.

            Maximum items: 9.

            1 field
            • Request · omni.defaults.imageIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

          • Request · omni.defaults.audioDeliveryOptional

            "original-song" | "generated"

            Original song is the default. Generated sound is time-fitted together with the complete picture to the MV scene window.

          • Request · omni.defaults.audioIdsOptional

            array<string>

            Ids of reference audio from audios.

            Maximum items: 3.

            1 field
            • Request · omni.defaults.audioIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

          • Request · omni.defaults.firstFrameIdOptional

            string

            Image id used as the first frame of the scene.

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

          • Request · omni.defaults.lastFrameIdOptional

            string

            Image id used as the last frame of the scene.

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

          • Request · omni.defaults.promptOptional

            string

            Scene prompt used with these materials.

            Minimum characters: 1. Maximum characters: 3000.

          • Request · omni.defaults.videoIdsOptional

            array<string>

            Ids of reference clips from videos.

            Maximum items: 3.

            1 field
            • Request · omni.defaults.videoIds[]Each item

              string

              Caller-chosen material id, unique within this task.

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

        • Request · omni.versionRequired

          "omni-task-v1"

          Requested compatibility or resource version.

        • Request · omni.audiosOptional

          array<object>

          Reference audio available to scene bindings.

          Maximum items: 16.

          1 field
          • Request · omni.audios[]Each item

            object

            Only the listed fields are accepted in this object.

            3 fields
            • Request · omni.audios[].durationSecRequired

              number

              Audio length in seconds.

              Minimum: 0.2. Maximum: 15.

            • Request · omni.audios[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.audios[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

        • Request · omni.imagesOptional

          array<object>

          Reference images available to scene bindings.

          Maximum items: 32.

          1 field
          • Request · omni.images[]Each item

            object

            Only the listed fields are accepted in this object.

            2 fields
            • Request · omni.images[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.images[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

        • Request · omni.planningOptional

          "director" | "direct"

          Director is the default. Direct uses customer scene prompts and complete fixed 5/10-second windows, without generative planning.

        • Request · omni.shotDurationSecOptional

          5 | 10

          Direct planning only; default 5. The effective song selection must be a multiple of this window.

        • Request · omni.shotsOptional

          array<object>

          Per-scene overrides of the default binding.

          Maximum items: 120.

          1 field
          • Request · omni.shots[]Each item

            object

            Only the listed fields are accepted in this object.

            8 fields
            • Request · omni.shots[].imageIdsRequired

              array<string>

              Ids of reference images from images.

              Maximum items: 9.

              1 field
              • Request · omni.shots[].imageIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

            • Request · omni.shots[].sceneIndexRequired

              string | integer

              Zero-based index in the persisted director plan. Overrides replace the complete default binding; unknown indices fail before any GPU purchase.

              Minimum: 0. Maximum: 119. 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, maximum 119). Prefer a JSON number.

                Format: integer.

              • Request · Option 2 — integerOption

                integer

                Zero-based index in the persisted director plan. Overrides replace the complete default binding; unknown indices fail before any GPU purchase.

                Minimum: 0. Maximum: 119.

            • Request · omni.shots[].audioDeliveryOptional

              "original-song" | "generated"

              Original song is the default. Generated sound is time-fitted together with the complete picture to the MV scene window.

            • Request · omni.shots[].audioIdsOptional

              array<string>

              Ids of reference audio from audios.

              Maximum items: 3.

              1 field
              • Request · omni.shots[].audioIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

            • Request · omni.shots[].firstFrameIdOptional

              string

              Image id used as the first frame of the scene.

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

            • Request · omni.shots[].lastFrameIdOptional

              string

              Image id used as the last frame of the scene.

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

            • Request · omni.shots[].promptOptional

              string

              Scene prompt used with these materials.

              Minimum characters: 1. Maximum characters: 3000.

            • Request · omni.shots[].videoIdsOptional

              array<string>

              Ids of reference clips from videos.

              Maximum items: 3.

              1 field
              • Request · omni.shots[].videoIds[]Each item

                string

                Caller-chosen material id, unique within this task.

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

        • Request · omni.videosOptional

          array<object>

          Reference video clips available to scene bindings.

          Maximum items: 16.

          1 field
          • Request · omni.videos[]Each item

            object

            Only the listed fields are accepted in this object.

            4 fields
            • Request · omni.videos[].durationSecRequired

              number

              Clip length in seconds.

              Minimum: 0.2. Maximum: 5.

            • Request · omni.videos[].idRequired

              string

              Caller-chosen material id, unique within this task.

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

            • Request · omni.videos[].includeAudioRequired

              boolean

              Whether the clip's own sound may be used.

            • Request · omni.videos[].urlRequired

              string

              Public HTTPS URL of the material.

              Maximum characters: 8192. Format: uri.

      • Request · preflightIdOptional

        string

        Reusable MV preflight snapshot identifier.

        Minimum characters: 1. Maximum characters: 100.

      • Request · promptOptional

        string

        Primary creative or operation instruction.

        Maximum characters: 3000.

      • Request · quoteIdOptional

        string

        Short-lived quote identifier for the matching paid operation.

        Minimum characters: 1. Maximum characters: 100.

      • Request · referenceImagesOptional

        array<string>

        Public reference image URLs.

        Maximum items: 7.

        1 field
      • Request · resolutionOptional

        "480p" | "540p" | "720p" | "768p" | "1080p" | "1440p"

        Delivery resolution. Default 540p for OneClick. Omn accepts native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p and 720p to 768p. OneClick does not support 480p, 768p or 1440p.

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

        6 options
        • Request · Option 1 — "480p"Option

          "480p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 2 — "540p"Option

          "540p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 3 — "720p"Option

          "720p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 4 — "768p"Option

          "768p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 5 — "1080p"Option

          "1080p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

        • Request · Option 6 — "1440p"Option

          "1440p"

          Delivery resolution; defaults to 720p, mapped to 768p for Omn. Omn supports native 480p/768p and AI-upscaled 1080p/1440p (2K); 540p maps to 480p. Subject to capability and preflight checks.

      • Request · srtUrlOptional

        string

        Public URL of caller-supplied SRT subtitles.

        Minimum characters: 1.

      • Request · subtitleOptional

        object

        MV subtitle generation and fallback policy.

        Only the listed fields are accepted in this object.

        6 fields
        • Request · subtitle.fallbackOptional

          "fail" | "continue_without_subtitles"

          Behavior when the preferred subtitle path cannot complete.

        • Request · subtitle.languageOptional

          "auto" | "en" | "zh"

          Requested or known language code/name.

        • Request · subtitle.maxCostUsdPerMinOptional

          number

          Maximum accepted public subtitle price in USD per minute.

          Minimum: 0.001. Maximum: 1.

        • Request · subtitle.modeOptional

          "auto" | "provided" | "off"

          Operation or product mode discriminator for this schema variant.

        • Request · subtitle.qualityOptional

          "standard" | "premium"

          Requested public quality tier.

        • Request · subtitle.requiredOptional

          boolean

          Whether the selected subtitle policy must succeed.

      • Request · subtitleColorOptional

        string

        Requested subtitle foreground color.

        Maximum characters: 20.

      • Request · subtitlesOptional

        boolean

        Whether subtitles are enabled for the MV.

      • Request · titleOptional

        string

        Optional customer-facing title.

        Maximum characters: 200.

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

      array<object>

      How OneClick settings change on Omn.

      1 field
    • Response 200 · migratableRequired

      boolean

      Whether this request can be bought as Omn.

    • Response 200 · priceRequired

      object

      Both prices for the same duration.

      2 fields
      • Response 200 · price.omnCreditsRequired

        number | null

        Omn price; null when duration is unknown.

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

        2 options
      • Response 200 · price.oneClickCreditsRequired

        number | null

        OneClick price for the same request.

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

        2 options
    • Response 200 · reasonsRequired

      array<object>

      What blocks migration; empty when migratable.

      1 field
    • Response 200 · specRequired

      object | null

      Omn spec to send to POST /quotes; null when not migratable.

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

      2 options
      • Response 200 · Option 1 — requires sourceOption

        object

        Omn spec to send to POST /quotes; null when not migratable.

        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 · Option 2 — nullOption

        null
    • Response 200 · unavailableAfterMigrationRequired

      array<string>

      OneClick features an Omn video does not offer.

      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