@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.
package/dist/schema.d.ts CHANGED
@@ -191,6 +191,61 @@ export interface paths {
191
191
  patch?: never;
192
192
  trace?: never;
193
193
  };
194
+ "/generate": {
195
+ parameters: {
196
+ query?: never;
197
+ header?: never;
198
+ path?: never;
199
+ cookie?: never;
200
+ };
201
+ get?: never;
202
+ put?: never;
203
+ /**
204
+ * Generate Asset
205
+ * @description Generate a single image, video or audio asset from a text prompt without
206
+ * rendering a full edit. Submit a prompt-bearing asset; the response is
207
+ * immediate when an identical asset has been generated before (results are
208
+ * cached by prompt, model and options), otherwise the job is queued and can
209
+ * be polled via the status endpoint.
210
+ *
211
+ * Generation is billed in credits per asset. Identical repeat requests
212
+ * resolve from the cache at no charge.
213
+ *
214
+ * **Base URL:** <a href="#">https://api.shotstack.io/edit/{version}</a>
215
+ */
216
+ post: operations["postGenerate"];
217
+ delete?: never;
218
+ options?: never;
219
+ head?: never;
220
+ patch?: never;
221
+ trace?: never;
222
+ };
223
+ "/generate/{id}": {
224
+ parameters: {
225
+ query?: never;
226
+ header?: never;
227
+ path: {
228
+ /** @description The generation job id returned by the generate endpoint. */
229
+ id: string;
230
+ };
231
+ cookie?: never;
232
+ };
233
+ /**
234
+ * Get Generation Status
235
+ * @description Get the status of an on-demand asset generation job created with the
236
+ * generate endpoint. Jobs are owner-scoped.
237
+ *
238
+ * **Base URL:** <a href="#">https://api.shotstack.io/edit/{version}</a>
239
+ */
240
+ get: operations["getGenerate"];
241
+ put?: never;
242
+ post?: never;
243
+ delete?: never;
244
+ options?: never;
245
+ head?: never;
246
+ patch?: never;
247
+ trace?: never;
248
+ };
194
249
  "/assets/{id}": {
195
250
  parameters: {
196
251
  query?: never;
@@ -559,14 +614,17 @@ export interface components {
559
614
  Asset: components["schemas"]["VideoAsset"] | components["schemas"]["ImageAsset"] | components["schemas"]["TextAsset"] | components["schemas"]["RichTextAsset"] | components["schemas"]["AudioAsset"] | components["schemas"]["LumaAsset"] | components["schemas"]["CaptionAsset"] | components["schemas"]["RichCaptionAsset"] | components["schemas"]["HtmlAsset"] | components["schemas"]["Html5Asset"] | components["schemas"]["TitleAsset"] | components["schemas"]["ShapeAsset"] | components["schemas"]["SvgAsset"] | components["schemas"]["TextToImageAsset"] | components["schemas"]["ImageToVideoAsset"] | components["schemas"]["TextToSpeechAsset"];
560
615
  /**
561
616
  * @description The VideoAsset adds a video to a Clip. The video can be sourced from a URL
562
- * (`src`) or generated from a text prompt (`prompt`), optionally from a
563
- * starting image (`inputSrc`). Exactly one of `src` or `prompt` must be provided.
617
+ * (`src`), generated from a text prompt (`prompt`), or both. At least one of
618
+ * `src` or `prompt` must be provided.
564
619
  *
565
620
  * - **Source URL:** set `src` to the URL of an mp4 (or compatible) video file.
566
- * - **Generated:** set `prompt` to describe the motion. Optionally set `inputSrc`
567
- * to a starting image URL (image-to-video). Use `model` to choose the generator
568
- * (e.g. `luma-ray-3`, `runpod-itv-mini`). The generated `src` is filled in
621
+ * - **Generated:** set `prompt` to describe the motion. Choose a generator
622
+ * with `model` and configure it with model-specific `options` (including a
623
+ * starting image for image-to-video). The generated `src` is filled in
569
624
  * automatically.
625
+ * - **Both:** `src` acts as a preview placeholder while `prompt` drives
626
+ * generation — the video is regenerated from the prompt at render time.
627
+ * Unchanged prompts and options resolve from the generation cache.
570
628
  */
571
629
  VideoAsset: {
572
630
  /**
@@ -575,49 +633,31 @@ export interface components {
575
633
  */
576
634
  type: "video";
577
635
  /**
578
- * @description The video source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.
636
+ * @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.
579
637
  * @example https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4
580
638
  */
581
639
  src?: string;
582
640
  /**
583
- * @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.
641
+ * @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).
584
642
  * @example Slowly zoom out and orbit left around the object.
585
643
  */
586
644
  prompt?: string;
587
645
  /**
588
- * @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.
589
- * @example https://s3-ap-northeast-1.amazonaws.com/my-bucket/input-image.jpg
590
- */
591
- inputSrc?: string;
592
- /**
593
- * @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.
594
- * @example luma-ray-3
646
+ * @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.
647
+ * @example seedance-2.0
595
648
  */
596
649
  model?: string;
597
650
  /**
598
- * @description Output resolution for video generation. Only meaningful when `prompt` is set and the model supports it (e.g. `fal/seedance-2.0`).
599
- * @example 720p
600
- * @enum {string}
601
- */
602
- resolution?: "480p" | "720p" | "1080p";
603
- /**
604
- * @description Target video duration in seconds for generation models that accept it. `"auto"` lets the model decide. Only meaningful when `prompt` is set.
605
- * @default auto
606
- * @example 5
607
- * @enum {string}
608
- */
609
- duration?: "auto" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "13" | "14" | "15";
610
- /**
611
- * @description Aspect ratio for the generated video. Only meaningful when `prompt` is set and the model supports it.
612
- * @example 16:9
613
- * @enum {string}
614
- */
615
- aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "21:9" | "9:21";
616
- /**
617
- * @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`).
618
- * @default false
651
+ * @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.
652
+ * @example {
653
+ * "resolution": "720p",
654
+ * "duration": "8",
655
+ * "generateAudio": true
656
+ * }
619
657
  */
620
- generateAudio?: boolean;
658
+ options?: {
659
+ [key: string]: unknown;
660
+ };
621
661
  /**
622
662
  * @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.
623
663
  * @example false
@@ -650,12 +690,16 @@ export interface components {
650
690
  };
651
691
  /**
652
692
  * @description The ImageAsset adds an image to a Clip. The image can be sourced from a URL
653
- * (`src`) or generated from a text prompt (`prompt`). Exactly one of `src` or
654
- * `prompt` must be provided.
693
+ * (`src`), generated from a text prompt (`prompt`), or both. At least one of
694
+ * `src` or `prompt` must be provided.
655
695
  *
656
696
  * - **Source URL:** set `src` to the publicly accessible URL of a jpg or png file.
657
- * - **Generated:** set `prompt` to describe the image; the engine generates it
658
- * using the provider chosen by `model` and fills `src` in automatically.
697
+ * - **Generated:** set `prompt` to describe the image. Choose a generator with
698
+ * `model` and configure it with model-specific `options`; the engine fills
699
+ * `src` in automatically.
700
+ * - **Both:** `src` acts as a preview placeholder while `prompt` drives
701
+ * generation — the image is regenerated from the prompt at render time.
702
+ * Unchanged prompts and options resolve from the generation cache.
659
703
  */
660
704
  ImageAsset: {
661
705
  /**
@@ -664,32 +708,30 @@ export interface components {
664
708
  */
665
709
  type: "image";
666
710
  /**
667
- * @description The image source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.
711
+ * @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.
668
712
  * @example https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg
669
713
  */
670
714
  src?: string;
671
715
  /**
672
- * @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.
716
+ * @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.
673
717
  * @example A serene landscape with a crystal-clear mountain lake at sunrise.
674
718
  */
675
719
  prompt?: string;
676
720
  /**
677
- * @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.
721
+ * @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.
678
722
  * @example flux-schnell
679
723
  */
680
724
  model?: string;
681
725
  /**
682
- * @description Output resolution tier for supported image generation models. `1K` (default), `2K`, or `4K`. Only meaningful when `prompt` is set.
683
- * @example 1K
684
- * @enum {string}
685
- */
686
- resolution?: "1K" | "2K" | "4K";
687
- /**
688
- * @description Aspect ratio for the generated image. Only meaningful when `prompt` is set and the model supports it.
689
- * @example 1:1
690
- * @enum {string}
726
+ * @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.
727
+ * @example {
728
+ * "resolution": "1K",
729
+ * "aspectRatio": "16:9"
730
+ * }
691
731
  */
692
- aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "21:9" | "9:21";
732
+ options?: {
733
+ [key: string]: unknown;
734
+ };
693
735
  crop?: components["schemas"]["Crop"];
694
736
  };
695
737
  /**
@@ -848,15 +890,19 @@ export interface components {
848
890
  };
849
891
  /**
850
892
  * @description The AudioAsset adds audio to a Clip. The audio can be sourced from a URL
851
- * (`src`) or generated from a text prompt (`prompt`). Exactly one of `src` or
852
- * `prompt` must be provided.
893
+ * (`src`), generated from a text prompt (`prompt`), or both. At least one of
894
+ * `src` or `prompt` must be provided.
853
895
  *
854
896
  * - **Source URL:** set `src` to a publicly accessible audio URL (e.g. mp3).
855
- * - **Generated speech:** set `prompt` to the spoken text and `voice` to a voice
856
- * identifier (text-to-speech). Optionally set `language`/`newscaster`.
857
- * - **Generated music or SFX:** set `prompt` describing the sound; omit `voice`.
858
- * - Use `model` to choose the generator. The generated `src` is filled in
859
- * automatically.
897
+ * - **Generated speech:** set `prompt` to the spoken text and choose a
898
+ * text-to-speech `model`; set the voice via `options`.
899
+ * - **Generated music or SFX:** set `prompt` describing the sound and choose
900
+ * a music generation `model`.
901
+ * - **Both:** `src` acts as a preview placeholder while `prompt` drives
902
+ * generation — the audio is regenerated from the prompt at render time.
903
+ * Unchanged prompts and options resolve from the generation cache.
904
+ * - Use `model` to choose the generator and `options` to configure it. The
905
+ * generated `src` is filled in automatically.
860
906
  */
861
907
  AudioAsset: {
862
908
  /**
@@ -865,47 +911,30 @@ export interface components {
865
911
  */
866
912
  type: "audio";
867
913
  /**
868
- * @description The audio source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.
914
+ * @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.
869
915
  * @example https://s3-ap-northeast-1.amazonaws.com/my-bucket/sound.mp3
870
916
  */
871
917
  src?: string;
872
918
  /**
873
- * @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.
919
+ * @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.
874
920
  * @example Welcome to today's broadcast.
875
921
  */
876
922
  prompt?: string;
877
923
  /**
878
- * @description Voice identifier for text-to-speech generation (e.g. `Matthew`, `Joanna`). Only meaningful when `prompt` is set.
879
- * @example Matthew
880
- */
881
- voice?: string;
882
- /**
883
- * @description Optional BCP-47 language code (e.g. `en-US`) for text-to-speech. Only meaningful when `prompt` and `voice` are set.
884
- * @example en-US
885
- */
886
- language?: string;
887
- /**
888
- * @description Set to `true` to use the voice's newscaster mode when supported. Only meaningful when `prompt` and `voice` are set.
889
- * @default false
890
- */
891
- newscaster?: boolean;
892
- /**
893
- * @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.
924
+ * @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.
894
925
  * @example polly-neural
895
926
  */
896
927
  model?: string;
897
928
  /**
898
- * @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`).
899
- * @example 30000
900
- */
901
- musicLengthMs?: number;
902
- /**
903
- * @description Set to `true` to force instrumental music (no vocals). Only meaningful for music generation models.
904
- * @default false
929
+ * @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.
930
+ * @example {
931
+ * "voice": "Matthew",
932
+ * "language": "en-US"
933
+ * }
905
934
  */
906
- forceInstrumental?: boolean;
907
- /** @description An optional structured composition plan for music generation. Only meaningful for music generation models (e.g. `fal/elevenlabs-music`). */
908
- compositionPlan?: string;
935
+ options?: {
936
+ [key: string]: unknown;
937
+ };
909
938
  /** @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. */
910
939
  trim?: number;
911
940
  /** @description Set the volume of the audio clip. Use a number or an array of [Tween](./#tocs_tween) objects to create custom volume transitions. */
@@ -1108,6 +1137,13 @@ export interface components {
1108
1137
  * @default 400
1109
1138
  */
1110
1139
  weight?: unknown;
1140
+ /**
1141
+ * @description The font style.
1142
+ * @default normal
1143
+ * @example italic
1144
+ * @enum {string}
1145
+ */
1146
+ style?: "normal" | "italic";
1111
1147
  /**
1112
1148
  * @description The text color using hexadecimal color notation.
1113
1149
  * @default #ffffff
@@ -1788,6 +1824,13 @@ export interface components {
1788
1824
  * @default 400
1789
1825
  */
1790
1826
  weight?: unknown;
1827
+ /**
1828
+ * @description The font style.
1829
+ * @default normal
1830
+ * @example italic
1831
+ * @enum {string}
1832
+ */
1833
+ style?: "normal" | "italic";
1791
1834
  /**
1792
1835
  * @description The text color using hexadecimal color notation.
1793
1836
  * @default #000000
@@ -3778,6 +3821,97 @@ export interface operations {
3778
3821
  };
3779
3822
  };
3780
3823
  };
3824
+ postGenerate: {
3825
+ parameters: {
3826
+ query?: never;
3827
+ header?: never;
3828
+ path?: never;
3829
+ cookie?: never;
3830
+ };
3831
+ /** @description A prompt-bearing image, video or audio asset to generate. */
3832
+ requestBody?: {
3833
+ content: {
3834
+ "application/json": {
3835
+ asset: components["schemas"]["ImageAsset"] | components["schemas"]["VideoAsset"] | components["schemas"]["AudioAsset"];
3836
+ };
3837
+ };
3838
+ };
3839
+ responses: {
3840
+ /** @description The generated asset was already cached and is immediately available. */
3841
+ 200: {
3842
+ headers: {
3843
+ [name: string]: unknown;
3844
+ };
3845
+ content: {
3846
+ "application/json": {
3847
+ /**
3848
+ * @description The generation job id. Deterministic for a given owner and asset payload (or idempotency key), so identical requests return the same job and cached result.
3849
+ * @example 8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e
3850
+ */
3851
+ id: string;
3852
+ /**
3853
+ * @description The status of the generation job.
3854
+ * @example done
3855
+ * @enum {string}
3856
+ */
3857
+ status: "queued" | "processing" | "done" | "failed";
3858
+ /**
3859
+ * @description The public URL of the generated asset. Present only when `status` is `done`.
3860
+ * @example https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png
3861
+ */
3862
+ url?: string;
3863
+ /** @description A human readable error message. Present only when `status` is `failed`. */
3864
+ error?: string;
3865
+ };
3866
+ };
3867
+ };
3868
+ /** @description The generation job has been queued. Poll the status endpoint. */
3869
+ 202: {
3870
+ headers: {
3871
+ /** @description The relative URL to poll for job status. */
3872
+ Location?: string;
3873
+ /** @description Suggested seconds to wait before polling. */
3874
+ "Retry-After"?: number;
3875
+ [name: string]: unknown;
3876
+ };
3877
+ content: {
3878
+ "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
3879
+ };
3880
+ };
3881
+ };
3882
+ };
3883
+ getGenerate: {
3884
+ parameters: {
3885
+ query?: never;
3886
+ header?: never;
3887
+ path: {
3888
+ /** @description The generation job id returned by the generate endpoint. */
3889
+ id: string;
3890
+ };
3891
+ cookie?: never;
3892
+ };
3893
+ requestBody?: never;
3894
+ responses: {
3895
+ /** @description The generation job has finished (done or failed). */
3896
+ 200: {
3897
+ headers: {
3898
+ [name: string]: unknown;
3899
+ };
3900
+ content: {
3901
+ "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
3902
+ };
3903
+ };
3904
+ /** @description The generation job is still processing. */
3905
+ 202: {
3906
+ headers: {
3907
+ [name: string]: unknown;
3908
+ };
3909
+ content: {
3910
+ "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
3911
+ };
3912
+ };
3913
+ };
3914
+ };
3781
3915
  getAsset: {
3782
3916
  parameters: {
3783
3917
  query?: never;