@shotstack/schemas 1.15.1 → 1.17.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": {
@@ -1772,6 +1728,18 @@
1772
1728
  "description": "The weight of the font. Can be a number (100-900) or a string ('normal', 'bold', etc.). 100 is lightest, 900 is heaviest (boldest).",
1773
1729
  "default": "400"
1774
1730
  },
1731
+ "style": {
1732
+ "description": "The font style.",
1733
+ "type": "string",
1734
+ "enum": [
1735
+ "normal",
1736
+ "italic"
1737
+ ],
1738
+ "default": "normal",
1739
+ "examples": [
1740
+ "italic"
1741
+ ]
1742
+ },
1775
1743
  "color": {
1776
1744
  "description": "The text color using hexadecimal color notation.",
1777
1745
  "type": "string",
@@ -2241,6 +2209,18 @@
2241
2209
  "description": "The weight of the font. Can be a number (100-900) or a string ('normal', 'bold', etc.). 100 is lightest, 900 is heaviest (boldest).",
2242
2210
  "default": "400"
2243
2211
  },
2212
+ "style": {
2213
+ "description": "The font style.",
2214
+ "type": "string",
2215
+ "enum": [
2216
+ "normal",
2217
+ "italic"
2218
+ ],
2219
+ "default": "normal",
2220
+ "examples": [
2221
+ "italic"
2222
+ ]
2223
+ },
2244
2224
  "color": {
2245
2225
  "description": "The text color using hexadecimal color notation.",
2246
2226
  "type": "string",
@@ -3695,7 +3675,7 @@
3695
3675
  "type": "object"
3696
3676
  },
3697
3677
  "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.",
3678
+ "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
3679
  "type": "object",
3700
3680
  "properties": {
3701
3681
  "type": {
@@ -3707,7 +3687,7 @@
3707
3687
  "type": "string"
3708
3688
  },
3709
3689
  "src": {
3710
- "description": "The video source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
3690
+ "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
3691
  "type": "string",
3712
3692
  "minLength": 1,
3713
3693
  "pattern": "\\S",
@@ -3716,84 +3696,32 @@
3716
3696
  ]
3717
3697
  },
3718
3698
  "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.",
3699
+ "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
3700
  "type": "string",
3721
3701
  "maxLength": 4000,
3722
3702
  "examples": [
3723
3703
  "Slowly zoom out and orbit left around the object."
3724
3704
  ]
3725
3705
  },
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
3706
  "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
- ],
3707
+ "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
3708
  "type": "string",
3749
3709
  "examples": [
3750
- "720p"
3710
+ "seedance-2.0"
3751
3711
  ]
3752
3712
  },
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",
3713
+ "options": {
3714
+ "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.",
3715
+ "type": "object",
3716
+ "additionalProperties": true,
3788
3717
  "examples": [
3789
- "16:9"
3718
+ {
3719
+ "resolution": "720p",
3720
+ "duration": "8",
3721
+ "generateAudio": true
3722
+ }
3790
3723
  ]
3791
3724
  },
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
3725
  "transcode": {
3798
3726
  "type": "boolean",
3799
3727
  "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.",