Check a OneClick V1 request for Omn
/api/v2/mv/migrations/v1-checkAuthentication · 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 rulesOmn 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"OptionobjectOnly the listed fields are accepted in this object.
20 fields
-
Request ·
modeRequired"fast"Operation or product mode discriminator for this schema variant.
-
Request ·
sourceRequiredobjectChoose 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"OptionobjectOnly the listed fields are accepted in this object.
4 fields
-
Request ·
source.clipIdRequiredstringSource clip identifier.
Minimum characters: 1.
-
Request ·
source.typeRequired"suno"Source or product type discriminator.
-
Request ·
source.lyricsOptionalstringLyrics or lyric context supplied to the operation.
Maximum characters: 5000.
-
Request ·
source.rangeOptionalobjectOptional source-media range.
2 fields
-
Request ·
source.range.endSecOptionalnumberEnd offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
Request ·
source.range.startSecOptionalnumberStart offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
-
-
Request ·
Option 2 — type = "audio"OptionobjectOnly the listed fields are accepted in this object.
7 fields
-
Request ·
source.audioUrlRequiredstringPublic HTTP(S) audio URL.
Format: uri.
-
Request ·
source.typeRequired"audio"Source or product type discriminator.
-
Request ·
source.durationSecOptionalnumberOptional 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.lyricsOptionalstringLyrics or lyric context supplied to the operation.
Maximum characters: 5000.
-
Request ·
source.musicStyleOptionalstringOptional song genre, mood or musical style used to guide automatic visual planning.
Maximum characters: 500.
-
Request ·
source.rangeOptionalobjectOptional source-media range.
2 fields
-
Request ·
source.range.endSecOptionalnumberEnd offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
Request ·
source.range.startSecOptionalnumberStart offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
-
Request ·
source.titleOptionalstringOptional 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 ·
characterImageOptionalstringPublic character reference image URL.
Minimum characters: 1.
-
Request ·
configOptionalobjectStandard task configuration: priority, tags, metadata, and webhookUrl.
4 fields
-
Request ·
config.metadataOptionalobjectFree-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
1 field
-
Request ·
config.metadata[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
Request ·
config.priorityOptionalnumberTask priority 1-10 (higher = sooner). Default 5.
Minimum: 1. Maximum: 10. Default: 5.
-
Request ·
config.webhookUrlOptionalstringURL to receive task.* lifecycle events via the central webhook service.
Format: uri.
-
-
Request ·
generationOptionalobjectAPI 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.lipReferenceImagesOptionalarray<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.lipReferenceImages[]Each itemstringMinimum characters: 1.
-
-
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.motionReferenceVideoOptionalstringOmn 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.motionRightsConfirmedOptionaltrueRequired 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.styleOptionalstringRequested creative style direction.
Maximum characters: 200.
-
Request ·
generation.subtitleModeOptional"vidu" | "custom"Fast MV subtitle rendering mode.
-
Request ·
generation.visualBoardOptionalobjectFast MV Visual Board configuration.
Only the listed fields are accepted in this object.
2 fields
-
Request ·
generation.visualBoard.imageProviderOptional"gpt-image-2" | "p-image" | "viduq2"Public image-generation option code.
-
Request ·
generation.visualBoard.presetOptional"auto" | "speed" | "detail" | "off"Visual Board speed/detail policy.
-
-
-
Request ·
languageOptional"auto" | "en" | "zh"Requested or known language code/name.
-
Request ·
lipSyncOptionalbooleanWhether the MV should use the supported lip-sync workflow.
-
Request ·
maxCreditsOptionalnumberMaximum OmnAPI credits authorized for this paid request.
Minimum: 1.
-
Request ·
omniOptionalobjectDirect 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.defaultsRequiredobjectMaterials and prompt used by every scene without an override.
Only the listed fields are accepted in this object.
7 fields
-
Request ·
omni.defaults.imageIdsRequiredarray<string>Ids of reference images from
images.Maximum items: 9.
1 field
-
Request ·
omni.defaults.imageIds[]Each itemstringCaller-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.audioIdsOptionalarray<string>Ids of reference audio from
audios.Maximum items: 3.
1 field
-
Request ·
omni.defaults.audioIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.defaults.firstFrameIdOptionalstringImage id used as the first frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.defaults.lastFrameIdOptionalstringImage id used as the last frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.defaults.promptOptionalstringScene prompt used with these materials.
Minimum characters: 1. Maximum characters: 3000.
-
Request ·
omni.defaults.videoIdsOptionalarray<string>Ids of reference clips from
videos.Maximum items: 3.
1 field
-
Request ·
omni.defaults.videoIds[]Each itemstringCaller-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.audiosOptionalarray<object>Reference audio available to scene bindings.
Maximum items: 16.
1 field
-
Request ·
omni.audios[]Each itemobjectOnly the listed fields are accepted in this object.
3 fields
-
Request ·
omni.audios[].durationSecRequirednumberAudio length in seconds.
Minimum: 0.2. Maximum: 15.
-
Request ·
omni.audios[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.audios[].urlRequiredstringPublic HTTPS URL of the material.
Maximum characters: 8192. Format: uri.
-
-
-
Request ·
omni.imagesOptionalarray<object>Reference images available to scene bindings.
Maximum items: 32.
1 field
-
Request ·
omni.images[]Each itemobjectOnly the listed fields are accepted in this object.
2 fields
-
Request ·
omni.images[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.images[].urlRequiredstringPublic 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.shotDurationSecOptional5 | 10Direct planning only; default 5. The effective song selection must be a multiple of this window.
-
Request ·
omni.shotsOptionalarray<object>Per-scene overrides of the default binding.
Maximum items: 120.
1 field
-
Request ·
omni.shots[]Each itemobjectOnly the listed fields are accepted in this object.
8 fields
-
Request ·
omni.shots[].imageIdsRequiredarray<string>Ids of reference images from
images.Maximum items: 9.
1 field
-
Request ·
omni.shots[].imageIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.shots[].sceneIndexRequiredstring | integerZero-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 — stringOptionstringNumeric 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 — integerOptionintegerZero-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[].audioIdsOptionalarray<string>Ids of reference audio from
audios.Maximum items: 3.
1 field
-
Request ·
omni.shots[].audioIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.shots[].firstFrameIdOptionalstringImage id used as the first frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.shots[].lastFrameIdOptionalstringImage id used as the last frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.shots[].promptOptionalstringScene prompt used with these materials.
Minimum characters: 1. Maximum characters: 3000.
-
Request ·
omni.shots[].videoIdsOptionalarray<string>Ids of reference clips from
videos.Maximum items: 3.
1 field
-
Request ·
omni.shots[].videoIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
-
-
Request ·
omni.videosOptionalarray<object>Reference video clips available to scene bindings.
Maximum items: 16.
1 field
-
Request ·
omni.videos[]Each itemobjectOnly the listed fields are accepted in this object.
4 fields
-
Request ·
omni.videos[].durationSecRequirednumberClip length in seconds.
Minimum: 0.2. Maximum: 5.
-
Request ·
omni.videos[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.videos[].includeAudioRequiredbooleanWhether the clip's own sound may be used.
-
Request ·
omni.videos[].urlRequiredstringPublic HTTPS URL of the material.
Maximum characters: 8192. Format: uri.
-
-
-
-
Request ·
preflightIdOptionalstringReusable MV preflight snapshot identifier.
Minimum characters: 1. Maximum characters: 100.
-
Request ·
promptOptionalstringPrimary creative or operation instruction.
Maximum characters: 3000.
-
Request ·
quoteIdOptionalstringShort-lived quote identifier for the matching paid operation.
Minimum characters: 1. Maximum characters: 100.
-
Request ·
referenceImagesOptionalarray<string>Public reference image URLs.
Maximum items: 7.
1 field
-
Request ·
referenceImages[]Each itemstringMinimum characters: 1.
-
-
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 ·
srtUrlOptionalstringPublic URL of caller-supplied SRT subtitles.
Minimum characters: 1.
-
Request ·
subtitleOptionalobjectMV 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.maxCostUsdPerMinOptionalnumberMaximum 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.requiredOptionalbooleanWhether the selected subtitle policy must succeed.
-
-
Request ·
subtitleColorOptionalstringRequested subtitle foreground color.
Maximum characters: 20.
-
Request ·
subtitlesOptionalbooleanWhether subtitles are enabled for the MV.
-
Request ·
titleOptionalstringOptional customer-facing title.
Maximum characters: 200.
-
-
Request ·
Option 2 — mode = "studio"OptionobjectOnly the listed fields are accepted in this object.
20 fields
-
Request ·
modeRequired"studio"Operation or product mode discriminator for this schema variant.
-
Request ·
sourceRequiredobjectChoose 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"OptionobjectOnly the listed fields are accepted in this object.
4 fields
-
Request ·
source.clipIdRequiredstringSource clip identifier.
Minimum characters: 1.
-
Request ·
source.typeRequired"suno"Source or product type discriminator.
-
Request ·
source.lyricsOptionalstringLyrics or lyric context supplied to the operation.
Maximum characters: 5000.
-
Request ·
source.rangeOptionalobjectOptional source-media range.
2 fields
-
Request ·
source.range.endSecOptionalnumberEnd offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
Request ·
source.range.startSecOptionalnumberStart offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
-
-
Request ·
Option 2 — type = "audio"OptionobjectOnly the listed fields are accepted in this object.
7 fields
-
Request ·
source.audioUrlRequiredstringPublic HTTP(S) audio URL.
Format: uri.
-
Request ·
source.typeRequired"audio"Source or product type discriminator.
-
Request ·
source.durationSecOptionalnumberOptional 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.lyricsOptionalstringLyrics or lyric context supplied to the operation.
Maximum characters: 5000.
-
Request ·
source.musicStyleOptionalstringOptional song genre, mood or musical style used to guide automatic visual planning.
Maximum characters: 500.
-
Request ·
source.rangeOptionalobjectOptional source-media range.
2 fields
-
Request ·
source.range.endSecOptionalnumberEnd offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
Request ·
source.range.startSecOptionalnumberStart offset in seconds in the containing timeline or selected source range.
Minimum: 0.
-
-
Request ·
source.titleOptionalstringOptional 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 ·
characterImageOptionalstringPublic character reference image URL.
Minimum characters: 1.
-
Request ·
configOptionalobjectStandard task configuration: priority, tags, metadata, and webhookUrl.
4 fields
-
Request ·
config.metadataOptionalobjectFree-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
1 field
-
Request ·
config.metadata[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
Request ·
config.priorityOptionalnumberTask priority 1-10 (higher = sooner). Default 5.
Minimum: 1. Maximum: 10. Default: 5.
-
Request ·
config.webhookUrlOptionalstringURL to receive task.* lifecycle events via the central webhook service.
Format: uri.
-
-
Request ·
generationOptionalobjectProduct-specific generation controls.
Only the listed fields are accepted in this object.
3 fields
-
Request ·
generation.imageProviderOptional"p-image" | "gpt-image-2" | "viduq2"Public image-generation option code.
-
Request ·
generation.videoModelOptionalstringPublic scene-video model code.
Maximum characters: 100.
-
Request ·
generation.videoProviderOptional"p-video" | "hailuo" | "minimax-h3" | "vidu"Public scene-video option code.
-
-
Request ·
languageOptional"auto" | "en" | "zh"Requested or known language code/name.
-
Request ·
lipSyncOptionalbooleanWhether the MV should use the supported lip-sync workflow.
-
Request ·
maxCreditsOptionalnumberMaximum OmnAPI credits authorized for this paid request.
Minimum: 1.
-
Request ·
omniOptionalobjectDirect 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.defaultsRequiredobjectMaterials and prompt used by every scene without an override.
Only the listed fields are accepted in this object.
7 fields
-
Request ·
omni.defaults.imageIdsRequiredarray<string>Ids of reference images from
images.Maximum items: 9.
1 field
-
Request ·
omni.defaults.imageIds[]Each itemstringCaller-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.audioIdsOptionalarray<string>Ids of reference audio from
audios.Maximum items: 3.
1 field
-
Request ·
omni.defaults.audioIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.defaults.firstFrameIdOptionalstringImage id used as the first frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.defaults.lastFrameIdOptionalstringImage id used as the last frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.defaults.promptOptionalstringScene prompt used with these materials.
Minimum characters: 1. Maximum characters: 3000.
-
Request ·
omni.defaults.videoIdsOptionalarray<string>Ids of reference clips from
videos.Maximum items: 3.
1 field
-
Request ·
omni.defaults.videoIds[]Each itemstringCaller-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.audiosOptionalarray<object>Reference audio available to scene bindings.
Maximum items: 16.
1 field
-
Request ·
omni.audios[]Each itemobjectOnly the listed fields are accepted in this object.
3 fields
-
Request ·
omni.audios[].durationSecRequirednumberAudio length in seconds.
Minimum: 0.2. Maximum: 15.
-
Request ·
omni.audios[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.audios[].urlRequiredstringPublic HTTPS URL of the material.
Maximum characters: 8192. Format: uri.
-
-
-
Request ·
omni.imagesOptionalarray<object>Reference images available to scene bindings.
Maximum items: 32.
1 field
-
Request ·
omni.images[]Each itemobjectOnly the listed fields are accepted in this object.
2 fields
-
Request ·
omni.images[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.images[].urlRequiredstringPublic 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.shotDurationSecOptional5 | 10Direct planning only; default 5. The effective song selection must be a multiple of this window.
-
Request ·
omni.shotsOptionalarray<object>Per-scene overrides of the default binding.
Maximum items: 120.
1 field
-
Request ·
omni.shots[]Each itemobjectOnly the listed fields are accepted in this object.
8 fields
-
Request ·
omni.shots[].imageIdsRequiredarray<string>Ids of reference images from
images.Maximum items: 9.
1 field
-
Request ·
omni.shots[].imageIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.shots[].sceneIndexRequiredstring | integerZero-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 — stringOptionstringNumeric 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 — integerOptionintegerZero-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[].audioIdsOptionalarray<string>Ids of reference audio from
audios.Maximum items: 3.
1 field
-
Request ·
omni.shots[].audioIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
Request ·
omni.shots[].firstFrameIdOptionalstringImage id used as the first frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.shots[].lastFrameIdOptionalstringImage id used as the last frame of the scene.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.shots[].promptOptionalstringScene prompt used with these materials.
Minimum characters: 1. Maximum characters: 3000.
-
Request ·
omni.shots[].videoIdsOptionalarray<string>Ids of reference clips from
videos.Maximum items: 3.
1 field
-
Request ·
omni.shots[].videoIds[]Each itemstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
-
-
-
Request ·
omni.videosOptionalarray<object>Reference video clips available to scene bindings.
Maximum items: 16.
1 field
-
Request ·
omni.videos[]Each itemobjectOnly the listed fields are accepted in this object.
4 fields
-
Request ·
omni.videos[].durationSecRequirednumberClip length in seconds.
Minimum: 0.2. Maximum: 5.
-
Request ·
omni.videos[].idRequiredstringCaller-chosen material id, unique within this task.
Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$.
-
Request ·
omni.videos[].includeAudioRequiredbooleanWhether the clip's own sound may be used.
-
Request ·
omni.videos[].urlRequiredstringPublic HTTPS URL of the material.
Maximum characters: 8192. Format: uri.
-
-
-
-
Request ·
preflightIdOptionalstringReusable MV preflight snapshot identifier.
Minimum characters: 1. Maximum characters: 100.
-
Request ·
promptOptionalstringPrimary creative or operation instruction.
Maximum characters: 3000.
-
Request ·
quoteIdOptionalstringShort-lived quote identifier for the matching paid operation.
Minimum characters: 1. Maximum characters: 100.
-
Request ·
referenceImagesOptionalarray<string>Public reference image URLs.
Maximum items: 7.
1 field
-
Request ·
referenceImages[]Each itemstringMinimum characters: 1.
-
-
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 ·
srtUrlOptionalstringPublic URL of caller-supplied SRT subtitles.
Minimum characters: 1.
-
Request ·
subtitleOptionalobjectMV 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.maxCostUsdPerMinOptionalnumberMaximum 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.requiredOptionalbooleanWhether the selected subtitle policy must succeed.
-
-
Request ·
subtitleColorOptionalstringRequested subtitle foreground color.
Maximum characters: 20.
-
Request ·
subtitlesOptionalbooleanWhether subtitles are enabled for the MV.
-
Request ·
titleOptionalstringOptional 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 ·
mappingsRequiredarray<object>How OneClick settings change on Omn.
1 field
-
Response 200 ·
mappings[]Each itemobject3 fields
-
Response 200 ·
mappings[].fieldRequiredstringOneClick field.
-
Response 200 ·
mappings[].fromRequiredstringOneClick value.
-
Response 200 ·
mappings[].toRequiredstringOmn value.
-
-
-
Response 200 ·
migratableRequiredbooleanWhether this request can be bought as Omn.
-
Response 200 ·
priceRequiredobjectBoth prices for the same duration.
2 fields
-
Response 200 ·
price.omnCreditsRequirednumber | nullOmn 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 ·
Option 1 — numberOptionnumberOmn price; null when duration is unknown.
-
Response 200 ·
Option 2 — nullOptionnull
-
-
Response 200 ·
price.oneClickCreditsRequirednumber | nullOneClick 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 ·
Option 1 — numberOptionnumberOneClick price for the same request.
-
Response 200 ·
Option 2 — nullOptionnull
-
-
-
Response 200 ·
reasonsRequiredarray<object>What blocks migration; empty when migratable.
1 field
-
Response 200 ·
reasons[]Each itemobject3 fields
-
Response 200 ·
reasons[].codeRequiredstringMachine-readable reason.
-
Response 200 ·
reasons[].fieldRequiredstringRequest field that blocks migration.
-
Response 200 ·
reasons[].messageRequiredstringExplanation.
-
-
-
Response 200 ·
specRequiredobject | nullOmn 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 sourceOptionobjectOmn spec to send to POST /quotes; null when not migratable.
Only the listed fields are accepted in this object.
6 fields
-
Response 200 ·
spec.sourceRequiredobjectThe song.
Use a complete option below; the value must satisfy at least one option.
2 options
-
Response 200 ·
Option 1 — type = "audio_url"OptionobjectOnly 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.urlRequiredstringPublic HTTPS audio URL (MP3, WAV, AAC, M4A; ≤ 128 MB).
Maximum characters: 4096. Format: uri.
-
Response 200 ·
spec.source.lyricsOptionalstringSong lyrics, one line per line; improve story and captions.
Maximum characters: 5000.
-
Response 200 ·
spec.source.rangeOptionalobjectUse only this part of the song (10–600 s).
Only the listed fields are accepted in this object.
2 fields
-
Response 200 ·
spec.source.range.endSecRequirednumberEnd of the used audio, seconds.
Exclusive lower bound: 0.
-
Response 200 ·
spec.source.range.startSecRequirednumberStart of the used audio, seconds.
Minimum: 0.
-
-
-
Response 200 ·
Option 2 — type = "suno_clip"OptionobjectOnly the listed fields are accepted in this object.
4 fields
-
Response 200 ·
spec.source.clipIdRequiredstringSuno 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.lyricsOptionalstringSong lyrics, one line per line; improve story and captions.
Maximum characters: 5000.
-
Response 200 ·
spec.source.rangeOptionalobjectUse only this part of the song (10–600 s).
Only the listed fields are accepted in this object.
2 fields
-
Response 200 ·
spec.source.range.endSecRequirednumberEnd of the used audio, seconds.
Exclusive lower bound: 0.
-
Response 200 ·
spec.source.range.startSecRequirednumberStart of the used audio, seconds.
Minimum: 0.
-
-
-
-
Response 200 ·
spec.captionsOptionalobjectBurned-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.requiredOptionalbooleanFail instead of delivering without captions.
-
Response 200 ·
spec.captions.srtUrlOptionalstringPublic SRT URL (≤ 4 MB), times relative to the used range.
Maximum characters: 4096. Format: uri.
-
-
Response 200 ·
spec.creativeOptionalobjectWhat the video shows.
Only the listed fields are accepted in this object.
5 fields
-
Response 200 ·
spec.creative.briefOptionalstringWhat 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.styleOptionalstringVisual treatment: look, palette, camera feel.
Maximum characters: 1000.
-
-
Response 200 ·
spec.outputOptionalobjectResolution 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.referencesOptionalobjectReference images.
Only the listed fields are accepted in this object.
3 fields
-
Response 200 ·
spec.references.locationsOptionalarray<string>Up to three images of places to show.
Maximum items: 3.
1 field
-
Response 200 ·
spec.references.locations[]Each itemstringPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
-
-
Response 200 ·
spec.references.performerOptionalobjectThe 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.performer.imageUrlRequiredstringPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
-
Response 200 ·
spec.references.performer.descriptionOptionalstringWho this is; helps keep the identity consistent.
Maximum characters: 500.
-
-
Response 200 ·
spec.references.stylesOptionalarray<string>Up to three images that set the visual style, not identity.
Maximum items: 3.
1 field
-
Response 200 ·
spec.references.styles[]Each itemstringPublic HTTPS URL.
Maximum characters: 4096. Format: uri.
-
-
-
Response 200 ·
spec.titleOptionalstringVideo title.
Maximum characters: 200.
-
-
Response 200 ·
Option 2 — nullOptionnull
-
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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 400 ·
error.messageRequiredstringHuman readable error message
-
Response 400 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 400 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 401 ·
error.messageRequiredstringHuman readable error message
-
Response 401 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 401 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 402 ·
error.messageRequiredstringHuman readable error message
-
Response 402 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 402 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 403 ·
error.messageRequiredstringHuman readable error message
-
Response 403 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 403 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 404 ·
error.messageRequiredstringHuman readable error message
-
Response 404 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 404 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 409 ·
error.messageRequiredstringHuman readable error message
-
Response 409 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 409 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 413 ·
error.messageRequiredstringHuman readable error message
-
Response 413 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 413 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 422 ·
error.messageRequiredstringHuman readable error message
-
Response 422 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 422 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringRATE_LIMITED for request and task admission rejections.
-
Response 429 ·
error.messageRequiredstringHuman-readable explanation. Wording may change; use the machine-readable code for programmatic decisions.
-
Response 429 ·
error.detailsOptionalobjectOptional 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.currentOptionalintegerCurrent count for the rate-limit window identified by policy and scope.
Minimum: 0.
-
Response 429 ·
error.details.inFlightOptionalintegerCurrent accepted tasks counted against the relevant account or API-key admission limit.
Minimum: 0.
-
Response 429 ·
error.details.limitOptionalintegerMaximum 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.retryAfterSecOptionalintegerSuggested 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 valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 429 ·
successRequiredfalseWhether 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 500 ·
error.messageRequiredstringHuman readable error message
-
Response 500 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 500 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 502 ·
error.messageRequiredstringHuman readable error message
-
Response 502 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 502 ·
successRequiredfalseAlways 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 ·
errorRequiredobjectStructured 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.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 503 ·
error.messageRequiredstringHuman readable error message
-
Response 503 ·
error.detailsOptionalobjectOptional 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 ·
error.details[key]Each valueany JSON valueKey pattern: ^(.*)$.
-
-
-
Response 503 ·
successRequiredfalseAlways false for error responses