@shotstack/schemas 1.15.1 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -105,7 +105,7 @@
105
105
  ]
106
106
  },
107
107
  "AudioAsset": {
108
- "description": "The AudioAsset adds audio to a Clip. The audio can be sourced from a URL\n(`src`) or generated from a text prompt (`prompt`). Exactly one of `src` or\n`prompt` must be provided.\n\n- **Source URL:** set `src` to a publicly accessible audio URL (e.g. mp3).\n- **Generated speech:** set `prompt` to the spoken text and `voice` to a voice\n identifier (text-to-speech). Optionally set `language`/`newscaster`.\n- **Generated music or SFX:** set `prompt` describing the sound; omit `voice`.\n- Use `model` to choose the generator. The generated `src` is filled in\n automatically.",
108
+ "description": "The AudioAsset adds audio to a Clip. The audio can be sourced from a URL\n(`src`), generated from a text prompt (`prompt`), or both. At least one of\n`src` or `prompt` must be provided.\n\n- **Source URL:** set `src` to a publicly accessible audio URL (e.g. mp3).\n- **Generated speech:** set `prompt` to the spoken text and choose a\n text-to-speech `model`; set the voice via `options`.\n- **Generated music or SFX:** set `prompt` describing the sound and choose\n a music generation `model`.\n- **Both:** `src` acts as a preview placeholder while `prompt` drives\n generation — the audio is regenerated from the prompt at render time.\n Unchanged prompts and options resolve from the generation cache.\n- Use `model` to choose the generator and `options` to configure it. The\n generated `src` is filled in automatically.",
109
109
  "type": "object",
110
110
  "properties": {
111
111
  "type": {
@@ -117,7 +117,7 @@
117
117
  "type": "string"
118
118
  },
119
119
  "src": {
120
- "description": "The audio source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
120
+ "description": "The audio source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the audio is regenerated from the prompt at render time.",
121
121
  "type": "string",
122
122
  "minLength": 1,
123
123
  "pattern": "\\S",
@@ -126,58 +126,31 @@
126
126
  ]
127
127
  },
128
128
  "prompt": {
129
- "description": "A text prompt. When `voice` is set, the prompt is the spoken text (text-to-speech). Without `voice`, the prompt describes generated music or sound effects. The generated `src` is filled in automatically.",
129
+ "description": "A text prompt. For text-to-speech models the prompt is the spoken text; for music models it describes the sound to generate. The generated `src` is filled in automatically; an existing `src` is treated as a preview placeholder and replaced.",
130
130
  "type": "string",
131
131
  "maxLength": 4000,
132
132
  "examples": [
133
133
  "Welcome to today's broadcast."
134
134
  ]
135
135
  },
136
- "voice": {
137
- "description": "Voice identifier for text-to-speech generation (e.g. `Matthew`, `Joanna`). Only meaningful when `prompt` is set.",
138
- "type": "string",
139
- "examples": [
140
- "Matthew"
141
- ]
142
- },
143
- "language": {
144
- "description": "Optional BCP-47 language code (e.g. `en-US`) for text-to-speech. Only meaningful when `prompt` and `voice` are set.",
145
- "type": "string",
146
- "examples": [
147
- "en-US"
148
- ]
149
- },
150
- "newscaster": {
151
- "description": "Set to `true` to use the voice's newscaster mode when supported. Only meaningful when `prompt` and `voice` are set.",
152
- "type": "boolean",
153
- "default": false
154
- },
155
136
  "model": {
156
- "description": "The generation model to use when `prompt` is set (e.g. `polly-neural`, `fal/elevenlabs-tts`, `fal/minimax-speech`, `fal/elevenlabs-music`). Defaults to the platform's preferred generator if omitted.",
137
+ "description": "The generation model to use when `prompt` is set (e.g. `polly-neural`, `elevenlabs-tts`, `elevenlabs-music`). Defaults to `elevenlabs-tts` (with a default voice) if omitted. Each model's available options are defined by the model registry.",
157
138
  "type": "string",
158
139
  "examples": [
159
140
  "polly-neural"
160
141
  ]
161
142
  },
162
- "musicLengthMs": {
163
- "description": "Target duration in milliseconds for generated music (3,000–600,000). Only meaningful when `prompt` is set and the model is a music generator (e.g. `fal/elevenlabs-music`).",
164
- "type": "number",
165
- "minimum": 3000,
166
- "maximum": 600000,
143
+ "options": {
144
+ "description": "Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.",
145
+ "type": "object",
146
+ "additionalProperties": true,
167
147
  "examples": [
168
- 30000
148
+ {
149
+ "voice": "Matthew",
150
+ "language": "en-US"
151
+ }
169
152
  ]
170
153
  },
171
- "forceInstrumental": {
172
- "description": "Set to `true` to force instrumental music (no vocals). Only meaningful for music generation models.",
173
- "type": "boolean",
174
- "default": false
175
- },
176
- "compositionPlan": {
177
- "description": "An optional structured composition plan for music generation. Only meaningful for music generation models (e.g. `fal/elevenlabs-music`).",
178
- "type": "string",
179
- "maxLength": 4000
180
- },
181
154
  "trim": {
182
155
  "description": "The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the in trim point. The audio will play until the file ends or the Clip length is reached.",
183
156
  "type": "number"
@@ -1122,7 +1095,7 @@
1122
1095
  ]
1123
1096
  },
1124
1097
  "ImageAsset": {
1125
- "description": "The ImageAsset adds an image to a Clip. The image can be sourced from a URL\n(`src`) or generated from a text prompt (`prompt`). Exactly one of `src` or\n`prompt` must be provided.\n\n- **Source URL:** set `src` to the publicly accessible URL of a jpg or png file.\n- **Generated:** set `prompt` to describe the image; the engine generates it\n using the provider chosen by `model` and fills `src` in automatically.",
1098
+ "description": "The ImageAsset adds an image to a Clip. The image can be sourced from a URL\n(`src`), generated from a text prompt (`prompt`), or both. At least one of\n`src` or `prompt` must be provided.\n\n- **Source URL:** set `src` to the publicly accessible URL of a jpg or png file.\n- **Generated:** set `prompt` to describe the image. Choose a generator with\n `model` and configure it with model-specific `options`; the engine fills\n `src` in automatically.\n- **Both:** `src` acts as a preview placeholder while `prompt` drives\n generation — the image is regenerated from the prompt at render time.\n Unchanged prompts and options resolve from the generation cache.",
1126
1099
  "type": "object",
1127
1100
  "properties": {
1128
1101
  "type": {
@@ -1134,7 +1107,7 @@
1134
1107
  "type": "string"
1135
1108
  },
1136
1109
  "src": {
1137
- "description": "The image source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
1110
+ "description": "The image source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the image is regenerated from the prompt at render time.",
1138
1111
  "type": "string",
1139
1112
  "minLength": 1,
1140
1113
  "pattern": "\\S",
@@ -1143,7 +1116,7 @@
1143
1116
  ]
1144
1117
  },
1145
1118
  "prompt": {
1146
- "description": "A text prompt to generate the image from. When set without `src`, the engine generates an image and fills `src` automatically. Use `model` to choose the generator.",
1119
+ "description": "A text prompt to generate the image from. The engine generates an image at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it.",
1147
1120
  "type": "string",
1148
1121
  "maxLength": 4000,
1149
1122
  "examples": [
@@ -1151,38 +1124,21 @@
1151
1124
  ]
1152
1125
  },
1153
1126
  "model": {
1154
- "description": "The generation model to use when `prompt` is set (e.g. `flux-schnell`, `fal/flux-schnell`, `fal/nano-banana-2`). Defaults to the platform's preferred generator if omitted.",
1127
+ "description": "The generation model to use when `prompt` is set (e.g. `flux-schnell`, `nano-banana-2`). Defaults to `nano-banana-2` if omitted. Each model's available options are defined by the model registry.",
1155
1128
  "type": "string",
1156
1129
  "examples": [
1157
1130
  "flux-schnell"
1158
1131
  ]
1159
1132
  },
1160
- "resolution": {
1161
- "description": "Output resolution tier for supported image generation models. `1K` (default), `2K`, or `4K`. Only meaningful when `prompt` is set.",
1162
- "enum": [
1163
- "1K",
1164
- "2K",
1165
- "4K"
1166
- ],
1167
- "type": "string",
1168
- "examples": [
1169
- "1K"
1170
- ]
1171
- },
1172
- "aspectRatio": {
1173
- "description": "Aspect ratio for the generated image. Only meaningful when `prompt` is set and the model supports it.",
1174
- "enum": [
1175
- "1:1",
1176
- "16:9",
1177
- "9:16",
1178
- "4:3",
1179
- "3:4",
1180
- "21:9",
1181
- "9:21"
1182
- ],
1183
- "type": "string",
1133
+ "options": {
1134
+ "description": "Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.",
1135
+ "type": "object",
1136
+ "additionalProperties": true,
1184
1137
  "examples": [
1185
- "1:1"
1138
+ {
1139
+ "resolution": "1K",
1140
+ "aspectRatio": "16:9"
1141
+ }
1186
1142
  ]
1187
1143
  },
1188
1144
  "crop": {
@@ -3695,7 +3651,7 @@
3695
3651
  "type": "object"
3696
3652
  },
3697
3653
  "VideoAsset": {
3698
- "description": "The VideoAsset adds a video to a Clip. The video can be sourced from a URL\n(`src`) or generated from a text prompt (`prompt`), optionally from a\nstarting image (`inputSrc`). Exactly one of `src` or `prompt` must be provided.\n\n- **Source URL:** set `src` to the URL of an mp4 (or compatible) video file.\n- **Generated:** set `prompt` to describe the motion. Optionally set `inputSrc`\n to a starting image URL (image-to-video). Use `model` to choose the generator\n (e.g. `luma-ray-3`, `runpod-itv-mini`). The generated `src` is filled in\n automatically.",
3654
+ "description": "The VideoAsset adds a video to a Clip. The video can be sourced from a URL\n(`src`), generated from a text prompt (`prompt`), or both. At least one of\n`src` or `prompt` must be provided.\n\n- **Source URL:** set `src` to the URL of an mp4 (or compatible) video file.\n- **Generated:** set `prompt` to describe the motion. Choose a generator\n with `model` and configure it with model-specific `options` (including a\n starting image for image-to-video). The generated `src` is filled in\n automatically.\n- **Both:** `src` acts as a preview placeholder while `prompt` drives\n generation — the video is regenerated from the prompt at render time.\n Unchanged prompts and options resolve from the generation cache.",
3699
3655
  "type": "object",
3700
3656
  "properties": {
3701
3657
  "type": {
@@ -3707,7 +3663,7 @@
3707
3663
  "type": "string"
3708
3664
  },
3709
3665
  "src": {
3710
- "description": "The video source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
3666
+ "description": "The video source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the video is regenerated from the prompt at render time.",
3711
3667
  "type": "string",
3712
3668
  "minLength": 1,
3713
3669
  "pattern": "\\S",
@@ -3716,84 +3672,32 @@
3716
3672
  ]
3717
3673
  },
3718
3674
  "prompt": {
3719
- "description": "A text prompt to generate the video from. When set without `src`, the engine generates a video and fills `src` automatically. Optionally pair with `inputSrc` for image-to-video. Use `model` to choose the generator.",
3675
+ "description": "A text prompt to generate the video from. The engine generates a video at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it (including a starting image for image-to-video).",
3720
3676
  "type": "string",
3721
3677
  "maxLength": 4000,
3722
3678
  "examples": [
3723
3679
  "Slowly zoom out and orbit left around the object."
3724
3680
  ]
3725
3681
  },
3726
- "inputSrc": {
3727
- "description": "Input image URL for image-to-video generation. The image is used as the starting frame; `prompt` describes the motion. Has no effect unless `prompt` is set.",
3728
- "type": "string",
3729
- "minLength": 1,
3730
- "examples": [
3731
- "https://s3-ap-northeast-1.amazonaws.com/my-bucket/input-image.jpg"
3732
- ]
3733
- },
3734
3682
  "model": {
3735
- "description": "The generation model to use when `prompt` is set (e.g. `luma-ray-3`, `runpod-itv-mini`, `fal/seedance-2.0`). Defaults to the platform's preferred generator if omitted.",
3736
- "type": "string",
3737
- "examples": [
3738
- "luma-ray-3"
3739
- ]
3740
- },
3741
- "resolution": {
3742
- "description": "Output resolution for video generation. Only meaningful when `prompt` is set and the model supports it (e.g. `fal/seedance-2.0`).",
3743
- "enum": [
3744
- "480p",
3745
- "720p",
3746
- "1080p"
3747
- ],
3683
+ "description": "The generation model to use when `prompt` is set (e.g. `shotstack-itv-mini`, `ray-flash-2`, `seedance-2.0`). Defaults to `seedance-2.0` if omitted. Each model's available options are defined by the model registry.",
3748
3684
  "type": "string",
3749
3685
  "examples": [
3750
- "720p"
3686
+ "seedance-2.0"
3751
3687
  ]
3752
3688
  },
3753
- "duration": {
3754
- "description": "Target video duration in seconds for generation models that accept it. `\"auto\"` lets the model decide. Only meaningful when `prompt` is set.",
3755
- "enum": [
3756
- "auto",
3757
- "4",
3758
- "5",
3759
- "6",
3760
- "7",
3761
- "8",
3762
- "9",
3763
- "10",
3764
- "11",
3765
- "12",
3766
- "13",
3767
- "14",
3768
- "15"
3769
- ],
3770
- "type": "string",
3771
- "default": "auto",
3772
- "examples": [
3773
- "5"
3774
- ]
3775
- },
3776
- "aspectRatio": {
3777
- "description": "Aspect ratio for the generated video. Only meaningful when `prompt` is set and the model supports it.",
3778
- "enum": [
3779
- "1:1",
3780
- "16:9",
3781
- "9:16",
3782
- "4:3",
3783
- "3:4",
3784
- "21:9",
3785
- "9:21"
3786
- ],
3787
- "type": "string",
3689
+ "options": {
3690
+ "description": "Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.",
3691
+ "type": "object",
3692
+ "additionalProperties": true,
3788
3693
  "examples": [
3789
- "16:9"
3694
+ {
3695
+ "resolution": "720p",
3696
+ "duration": "8",
3697
+ "generateAudio": true
3698
+ }
3790
3699
  ]
3791
3700
  },
3792
- "generateAudio": {
3793
- "description": "Set to `true` to request audio generation alongside the video. Only meaningful for video generation models that support it (e.g. `fal/seedance-2.0`).",
3794
- "type": "boolean",
3795
- "default": false
3796
- },
3797
3701
  "transcode": {
3798
3702
  "type": "boolean",
3799
3703
  "description": "Set to `true` to force re-encoding of the video during preprocessing. This can help resolve compatibility issues, fix rotation problems, synchronize audio, or convert formats. The video will be processed to ensure optimal compatibility with the rendering engine.",