@shotstack/schemas 1.20.0 → 1.20.2

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
@@ -784,7 +784,7 @@ export interface components {
784
784
  prompt?: string;
785
785
  /**
786
786
  * @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.
787
- * @example flux-schnell
787
+ * @example nano-banana-2
788
788
  */
789
789
  model?: string;
790
790
  /**
@@ -2956,6 +2956,168 @@ export interface components {
2956
2956
  /** @description Specify the storage locations and hosting services to send the file to. */
2957
2957
  destinations: components["schemas"]["Destinations"][];
2958
2958
  };
2959
+ /** @description A generation model available to `prompt`-bearing image, video and audio assets, with the options it accepts and what it costs. Render a model picker and its option fields from this rather than hard coding a model list, so a newly launched model is available without a client release. */
2960
+ GenerationModel: {
2961
+ /**
2962
+ * @description The identifier to set as the asset `model`. Carries no provider name, so routing can change without a public rename.
2963
+ * @example seedance-2.0-text-to-video
2964
+ */
2965
+ model: string;
2966
+ /**
2967
+ * @description The asset type this model generates.
2968
+ * @example video
2969
+ * @enum {string}
2970
+ */
2971
+ type: "image" | "video" | "audio";
2972
+ /**
2973
+ * @description The model's display name, for a model picker.
2974
+ * @example Seedance 2.0 · Text to video
2975
+ */
2976
+ name?: string;
2977
+ /**
2978
+ * @description What the model is suited to, in a sentence or two.
2979
+ * @example Generate cinematic video with realistic motion, prompt-directed camera movement and optional synchronised audio.
2980
+ */
2981
+ description?: string;
2982
+ /** @description What one generation with this model costs. */
2983
+ pricing?: components["schemas"]["GenerationModelPricing"];
2984
+ /** @description JSON Schema for the model's `options` object. Only returned for a single model, or for a list requested with `expand=options`. Values outside this schema are rejected. */
2985
+ options?: {
2986
+ [key: string]: unknown;
2987
+ };
2988
+ /**
2989
+ * @description Whether the account behind the calling API key can generate with this model. Omitted when that cannot be determined; treat a missing value as unknown, not as available. Generation requests are checked either way.
2990
+ * @example false
2991
+ */
2992
+ available?: boolean;
2993
+ /**
2994
+ * @description Why `available` is false. `AiCapabilityNotIncluded`: the account's plan does not include this kind of generation. `AiDisabled`: AI generation is turned off for the account. `AiAccessUnavailable`: access could not be confirmed; try again later.
2995
+ * @example AiCapabilityNotIncluded
2996
+ * @enum {string}
2997
+ */
2998
+ unavailableReason?: "AiCapabilityNotIncluded" | "AiDisabled" | "AiAccessUnavailable";
2999
+ };
3000
+ /** @description What one generation costs, in credits: the rate multiplied by the units consumed. `quantity` says how to count the units, and is absent when one generation is one unit. Where a model charges differently per option value, `credits` is an object keyed by that value and `tieredBy` names the option that selects it. */
3001
+ GenerationModelPricing: {
3002
+ /**
3003
+ * @description Credits per unit. A number when the rate is flat, or an object keyed by the values of the option named in `tieredBy`.
3004
+ * @example {
3005
+ * "480p": 0.9375,
3006
+ * "720p": 1.8962,
3007
+ * "1080p": 4.2625
3008
+ * }
3009
+ */
3010
+ credits: number | {
3011
+ [key: string]: number;
3012
+ };
3013
+ /** @description The option whose value selects the rate, and the value assumed when the option is absent. Present only when `credits` is keyed. */
3014
+ tieredBy?: {
3015
+ /** @example resolution */
3016
+ option: string;
3017
+ /** @example 720p */
3018
+ default: string;
3019
+ };
3020
+ /** @description How many units a generation consumes. Take the value `measure` names, or `default` when the request carries none, hold it within `min` and `max`, divide by `per`, and round up when `round` is `up`. Absent when one generation is one unit. */
3021
+ quantity?: {
3022
+ /**
3023
+ * @description What the count is taken from, and the scale it is measured in.
3024
+ * @example clipSeconds
3025
+ * @enum {string}
3026
+ */
3027
+ measure: "clipSeconds" | "promptCharacters";
3028
+ /**
3029
+ * @description How many of `measure` make one billable unit.
3030
+ * @example 60
3031
+ */
3032
+ per: number;
3033
+ /**
3034
+ * @description Fewest accepted. A smaller request is charged at this.
3035
+ * @example 3
3036
+ */
3037
+ min?: number;
3038
+ /**
3039
+ * @description Most accepted. A larger request is charged at this.
3040
+ * @example 600
3041
+ */
3042
+ max?: number;
3043
+ /**
3044
+ * @description Assumed when the request carries no value.
3045
+ * @example 30
3046
+ */
3047
+ default?: number;
3048
+ /**
3049
+ * @description Present when a partial unit is charged as a whole one. A 61 second track on a per-minute rate is charged as two minutes.
3050
+ * @example up
3051
+ * @enum {string}
3052
+ */
3053
+ round?: "up";
3054
+ };
3055
+ /**
3056
+ * @description The date this rate took effect, or `legacy` for a rate that predates dated pricing.
3057
+ * @example 2026-08-13
3058
+ */
3059
+ effectiveFrom: string;
3060
+ };
3061
+ /** @description The generation models available to this account. */
3062
+ GenerationModelListResponse: {
3063
+ /** @description The available models. */
3064
+ models: components["schemas"]["GenerationModel"][];
3065
+ };
3066
+ /** @description The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset. */
3067
+ GenerationResponse: {
3068
+ /**
3069
+ * @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.
3070
+ * @example 8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e
3071
+ */
3072
+ id: string;
3073
+ /**
3074
+ * @description The status of the generation job.
3075
+ * @example done
3076
+ * @enum {string}
3077
+ */
3078
+ status: "queued" | "processing" | "done" | "failed";
3079
+ /**
3080
+ * @description The public URL of the generated asset. Present only when `status` is `done`.
3081
+ * @example https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png
3082
+ */
3083
+ url?: string;
3084
+ /** @description A human readable error message. Present only when `status` is `failed`. */
3085
+ error?: string;
3086
+ };
3087
+ /** @description Why a generation request was not accepted or a job could not be found. */
3088
+ GenerationErrorResponse: {
3089
+ /**
3090
+ * @description A human readable error message.
3091
+ * @example Insufficient generation credits.
3092
+ */
3093
+ error: string;
3094
+ /**
3095
+ * @description Why access to AI generation was refused. `AiCapabilityNotIncluded`: the account's plan does not include this kind of generation. `FeatureNotIncluded`: the plan does not include a feature the asset uses. `AiDisabled`: AI generation is turned off for the account. `AiAccessUnavailable`: access could not be confirmed; try again later.
3096
+ * @example AiCapabilityNotIncluded
3097
+ */
3098
+ code?: string;
3099
+ /**
3100
+ * @description The credits the account has available. Present when it has too few.
3101
+ * @example 1.5
3102
+ */
3103
+ available?: number;
3104
+ };
3105
+ /** @description Why a generation model could not be returned. */
3106
+ GenerationModelErrorResponse: {
3107
+ error: {
3108
+ /**
3109
+ * @description `UnknownGenerationModel`: no model has this identifier. `WithdrawnGenerationModel`: the model is no longer listed, but edits that already use it still validate, bill and render.
3110
+ * @example UnknownGenerationModel
3111
+ * @enum {string}
3112
+ */
3113
+ name: "UnknownGenerationModel" | "WithdrawnGenerationModel";
3114
+ /**
3115
+ * @description A human readable error message.
3116
+ * @example Unknown generation model "seedance-9".
3117
+ */
3118
+ message: string;
3119
+ };
3120
+ };
2959
3121
  /** @description The response received after a [render request](#render-asset) or [template render](#render-template) is submitted. The render task is queued for rendering and a unique render id is returned. */
2960
3122
  QueuedResponse: {
2961
3123
  /**
@@ -3137,7 +3299,94 @@ export interface components {
3137
3299
  /**
3138
3300
  * @description The [Edit](#tocs_edit) template.
3139
3301
  * @example {
3140
- * "$ref": "../../definitions/edit.yaml"
3302
+ * "timeline": {
3303
+ * "background": "#000000",
3304
+ * "fonts": [
3305
+ * {
3306
+ * "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
3307
+ * }
3308
+ * ],
3309
+ * "tracks": [
3310
+ * {
3311
+ * "clips": [
3312
+ * {
3313
+ * "asset": {
3314
+ * "type": "rich-text",
3315
+ * "text": "Hello World",
3316
+ * "font": {
3317
+ * "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
3318
+ * "size": 64,
3319
+ * "weight": "700",
3320
+ * "color": "#ffffff"
3321
+ * },
3322
+ * "align": {
3323
+ * "horizontal": "center",
3324
+ * "vertical": "middle"
3325
+ * }
3326
+ * },
3327
+ * "start": 0,
3328
+ * "length": 4,
3329
+ * "transition": {
3330
+ * "in": "fade",
3331
+ * "out": "fade"
3332
+ * }
3333
+ * },
3334
+ * {
3335
+ * "asset": {
3336
+ * "type": "image",
3337
+ * "src": "https://shotstack-assets.s3.amazonaws.com/images/earth.jpg"
3338
+ * },
3339
+ * "start": 4,
3340
+ * "length": 3,
3341
+ * "effect": "zoomIn",
3342
+ * "filter": "greyscale"
3343
+ * }
3344
+ * ]
3345
+ * },
3346
+ * {
3347
+ * "clips": [
3348
+ * {
3349
+ * "asset": {
3350
+ * "type": "video",
3351
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4",
3352
+ * "transcode": true
3353
+ * },
3354
+ * "start": 7,
3355
+ * "length": 4.5
3356
+ * },
3357
+ * {
3358
+ * "asset": {
3359
+ * "type": "video",
3360
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4",
3361
+ * "volume": 0.5
3362
+ * },
3363
+ * "start": 11.5,
3364
+ * "length": 5,
3365
+ * "transition": {
3366
+ * "out": "wipeLeft"
3367
+ * }
3368
+ * }
3369
+ * ]
3370
+ * },
3371
+ * {
3372
+ * "clips": [
3373
+ * {
3374
+ * "asset": {
3375
+ * "type": "audio",
3376
+ * "src": "https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3",
3377
+ * "effect": "fadeInFadeOut"
3378
+ * },
3379
+ * "start": 0,
3380
+ * "length": "end"
3381
+ * }
3382
+ * ]
3383
+ * }
3384
+ * ]
3385
+ * },
3386
+ * "output": {
3387
+ * "format": "mp4",
3388
+ * "resolution": "sd"
3389
+ * }
3141
3390
  * }
3142
3391
  */
3143
3392
  template: components["schemas"]["Edit"];
@@ -3582,35 +3831,44 @@ export interface operations {
3582
3831
  /**
3583
3832
  * @example {
3584
3833
  * "timeline": {
3585
- * "soundtrack": {
3586
- * "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
3587
- * "effect": "fadeInFadeOut"
3588
- * },
3589
3834
  * "background": "#000000",
3835
+ * "fonts": [
3836
+ * {
3837
+ * "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
3838
+ * }
3839
+ * ],
3590
3840
  * "tracks": [
3591
3841
  * {
3592
3842
  * "clips": [
3593
3843
  * {
3594
3844
  * "asset": {
3595
- * "type": "title",
3845
+ * "type": "rich-text",
3596
3846
  * "text": "Hello World",
3597
- * "style": "minimal"
3847
+ * "font": {
3848
+ * "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
3849
+ * "size": 64,
3850
+ * "weight": "700",
3851
+ * "color": "#ffffff"
3852
+ * },
3853
+ * "align": {
3854
+ * "horizontal": "center",
3855
+ * "vertical": "middle"
3856
+ * }
3598
3857
  * },
3599
3858
  * "start": 0,
3600
3859
  * "length": 4,
3601
3860
  * "transition": {
3602
3861
  * "in": "fade",
3603
3862
  * "out": "fade"
3604
- * },
3605
- * "effect": "slideRight"
3863
+ * }
3606
3864
  * },
3607
3865
  * {
3608
3866
  * "asset": {
3609
3867
  * "type": "image",
3610
- * "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-image.jpg"
3868
+ * "src": "https://shotstack-assets.s3.amazonaws.com/images/earth.jpg"
3611
3869
  * },
3612
- * "start": 3,
3613
- * "length": 4,
3870
+ * "start": 4,
3871
+ * "length": 3,
3614
3872
  * "effect": "zoomIn",
3615
3873
  * "filter": "greyscale"
3616
3874
  * }
@@ -3621,8 +3879,7 @@ export interface operations {
3621
3879
  * {
3622
3880
  * "asset": {
3623
3881
  * "type": "video",
3624
- * "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-1.mp4",
3625
- * "trim": 10.5,
3882
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4",
3626
3883
  * "transcode": true
3627
3884
  * },
3628
3885
  * "start": 7,
@@ -3631,7 +3888,7 @@ export interface operations {
3631
3888
  * {
3632
3889
  * "asset": {
3633
3890
  * "type": "video",
3634
- * "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-2.mp4",
3891
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4",
3635
3892
  * "volume": 0.5
3636
3893
  * },
3637
3894
  * "start": 11.5,
@@ -3641,6 +3898,19 @@ export interface operations {
3641
3898
  * }
3642
3899
  * }
3643
3900
  * ]
3901
+ * },
3902
+ * {
3903
+ * "clips": [
3904
+ * {
3905
+ * "asset": {
3906
+ * "type": "audio",
3907
+ * "src": "https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3",
3908
+ * "effect": "fadeInFadeOut"
3909
+ * },
3910
+ * "start": 0,
3911
+ * "length": "end"
3912
+ * }
3913
+ * ]
3644
3914
  * }
3645
3915
  * ]
3646
3916
  * },
@@ -3704,7 +3974,94 @@ export interface operations {
3704
3974
  * "owner": "5ca6hu7s9k",
3705
3975
  * "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
3706
3976
  * "data": {
3707
- * "$ref": "#/paths/~1render/post/requestBody/content/application~1json/example"
3977
+ * "timeline": {
3978
+ * "background": "#000000",
3979
+ * "fonts": [
3980
+ * {
3981
+ * "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
3982
+ * }
3983
+ * ],
3984
+ * "tracks": [
3985
+ * {
3986
+ * "clips": [
3987
+ * {
3988
+ * "asset": {
3989
+ * "type": "rich-text",
3990
+ * "text": "Hello World",
3991
+ * "font": {
3992
+ * "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
3993
+ * "size": 64,
3994
+ * "weight": "700",
3995
+ * "color": "#ffffff"
3996
+ * },
3997
+ * "align": {
3998
+ * "horizontal": "center",
3999
+ * "vertical": "middle"
4000
+ * }
4001
+ * },
4002
+ * "start": 0,
4003
+ * "length": 4,
4004
+ * "transition": {
4005
+ * "in": "fade",
4006
+ * "out": "fade"
4007
+ * }
4008
+ * },
4009
+ * {
4010
+ * "asset": {
4011
+ * "type": "image",
4012
+ * "src": "https://shotstack-assets.s3.amazonaws.com/images/earth.jpg"
4013
+ * },
4014
+ * "start": 4,
4015
+ * "length": 3,
4016
+ * "effect": "zoomIn",
4017
+ * "filter": "greyscale"
4018
+ * }
4019
+ * ]
4020
+ * },
4021
+ * {
4022
+ * "clips": [
4023
+ * {
4024
+ * "asset": {
4025
+ * "type": "video",
4026
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4",
4027
+ * "transcode": true
4028
+ * },
4029
+ * "start": 7,
4030
+ * "length": 4.5
4031
+ * },
4032
+ * {
4033
+ * "asset": {
4034
+ * "type": "video",
4035
+ * "src": "https://shotstack-assets.s3.amazonaws.com/footage/city-timelapse.mp4",
4036
+ * "volume": 0.5
4037
+ * },
4038
+ * "start": 11.5,
4039
+ * "length": 5,
4040
+ * "transition": {
4041
+ * "out": "wipeLeft"
4042
+ * }
4043
+ * }
4044
+ * ]
4045
+ * },
4046
+ * {
4047
+ * "clips": [
4048
+ * {
4049
+ * "asset": {
4050
+ * "type": "audio",
4051
+ * "src": "https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3",
4052
+ * "effect": "fadeInFadeOut"
4053
+ * },
4054
+ * "start": 0,
4055
+ * "length": "end"
4056
+ * }
4057
+ * ]
4058
+ * }
4059
+ * ]
4060
+ * },
4061
+ * "output": {
4062
+ * "format": "mp4",
4063
+ * "resolution": "sd"
4064
+ * }
3708
4065
  * },
3709
4066
  * "created": "2020-10-30T09:42:29.446Z",
3710
4067
  * "updated": "2020-10-30T09:42:39.168Z"
@@ -3746,6 +4103,57 @@ export interface operations {
3746
4103
  /** @description Create a template with a name and [Edit](#tocs_edit). */
3747
4104
  requestBody: {
3748
4105
  content: {
4106
+ /**
4107
+ * @example {
4108
+ * "name": "Jane's welcome video",
4109
+ * "template": {
4110
+ * "timeline": {
4111
+ * "fonts": [
4112
+ * {
4113
+ * "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
4114
+ * }
4115
+ * ],
4116
+ * "tracks": [
4117
+ * {
4118
+ * "clips": [
4119
+ * {
4120
+ * "asset": {
4121
+ * "type": "rich-text",
4122
+ * "text": "HELLO {{NAME}}",
4123
+ * "font": {
4124
+ * "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
4125
+ * "size": 72,
4126
+ * "weight": "800",
4127
+ * "color": "#ffffff"
4128
+ * },
4129
+ * "align": {
4130
+ * "horizontal": "center",
4131
+ * "vertical": "middle"
4132
+ * }
4133
+ * },
4134
+ * "start": 0,
4135
+ * "length": 5
4136
+ * }
4137
+ * ]
4138
+ * }
4139
+ * ]
4140
+ * },
4141
+ * "output": {
4142
+ * "format": "mp4",
4143
+ * "size": {
4144
+ * "width": 1024,
4145
+ * "height": 576
4146
+ * }
4147
+ * },
4148
+ * "merge": [
4149
+ * {
4150
+ * "find": "NAME",
4151
+ * "replace": "World"
4152
+ * }
4153
+ * ]
4154
+ * }
4155
+ * }
4156
+ */
3749
4157
  "application/json": components["schemas"]["Template"];
3750
4158
  };
3751
4159
  };
@@ -3797,6 +4205,57 @@ export interface operations {
3797
4205
  /** @description Update an individual templates name and [Edit](#tocs_edit). Both template name and template must be provided. If the template parameter is omitted a blank template will be saved. */
3798
4206
  requestBody: {
3799
4207
  content: {
4208
+ /**
4209
+ * @example {
4210
+ * "name": "Jane's welcome video",
4211
+ * "template": {
4212
+ * "timeline": {
4213
+ * "fonts": [
4214
+ * {
4215
+ * "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf"
4216
+ * }
4217
+ * ],
4218
+ * "tracks": [
4219
+ * {
4220
+ * "clips": [
4221
+ * {
4222
+ * "asset": {
4223
+ * "type": "rich-text",
4224
+ * "text": "HELLO {{NAME}}",
4225
+ * "font": {
4226
+ * "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
4227
+ * "size": 72,
4228
+ * "weight": "800",
4229
+ * "color": "#ffffff"
4230
+ * },
4231
+ * "align": {
4232
+ * "horizontal": "center",
4233
+ * "vertical": "middle"
4234
+ * }
4235
+ * },
4236
+ * "start": 0,
4237
+ * "length": 5
4238
+ * }
4239
+ * ]
4240
+ * }
4241
+ * ]
4242
+ * },
4243
+ * "output": {
4244
+ * "format": "mp4",
4245
+ * "size": {
4246
+ * "width": 1024,
4247
+ * "height": 576
4248
+ * }
4249
+ * },
4250
+ * "merge": [
4251
+ * {
4252
+ * "find": "NAME",
4253
+ * "replace": "World"
4254
+ * }
4255
+ * ]
4256
+ * }
4257
+ * }
4258
+ */
3800
4259
  "application/json": components["schemas"]["Template"];
3801
4260
  };
3802
4261
  };
@@ -3853,6 +4312,17 @@ export interface operations {
3853
4312
  /** @description Render a template by template id. */
3854
4313
  requestBody: {
3855
4314
  content: {
4315
+ /**
4316
+ * @example {
4317
+ * "id": "f5493c17-d01f-445c-bb49-535fae65f219",
4318
+ * "merge": [
4319
+ * {
4320
+ * "find": "NAME",
4321
+ * "replace": "Jane"
4322
+ * }
4323
+ * ]
4324
+ * }
4325
+ */
3856
4326
  "application/json": components["schemas"]["TemplateRender"];
3857
4327
  };
3858
4328
  };
@@ -3894,45 +4364,43 @@ export interface operations {
3894
4364
  postGenerate: {
3895
4365
  parameters: {
3896
4366
  query?: never;
3897
- header?: never;
4367
+ header?: {
4368
+ /** @description A key that makes this request its own generation. Retrying with the same key returns the job it first created instead of generating and billing again, and a new key generates afresh even when the asset matches an earlier one. Without a key, identical assets share one cached result. For 24 hours a key reused for a different asset is rejected; after that it returns its first result. */
4369
+ "Idempotency-Key"?: string;
4370
+ };
3898
4371
  path?: never;
3899
4372
  cookie?: never;
3900
4373
  };
3901
4374
  /** @description A prompt-bearing image, video or audio asset to generate. */
3902
4375
  requestBody?: {
3903
4376
  content: {
4377
+ /**
4378
+ * @example {
4379
+ * "asset": {
4380
+ * "type": "image",
4381
+ * "prompt": "A lighthouse on a rocky coast at sunset, cinematic lighting",
4382
+ * "model": "nano-banana-2"
4383
+ * }
4384
+ * }
4385
+ */
3904
4386
  "application/json": {
3905
4387
  asset: components["schemas"]["ImageAsset"] | components["schemas"]["VideoAsset"] | components["schemas"]["AudioAsset"];
4388
+ /**
4389
+ * @description The length, in seconds, of the clip the asset fills. A model that generates to a duration takes it from this value in place of its own duration option. Other models ignore it.
4390
+ * @example 5
4391
+ */
4392
+ length?: number;
3906
4393
  };
3907
4394
  };
3908
4395
  };
3909
4396
  responses: {
3910
- /** @description The generated asset was already cached and is immediately available. */
4397
+ /** @description The asset was generated before: `done` with its URL, or `failed` with the error that ended it. */
3911
4398
  200: {
3912
4399
  headers: {
3913
4400
  [name: string]: unknown;
3914
4401
  };
3915
4402
  content: {
3916
- "application/json": {
3917
- /**
3918
- * @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.
3919
- * @example 8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e
3920
- */
3921
- id: string;
3922
- /**
3923
- * @description The status of the generation job.
3924
- * @example done
3925
- * @enum {string}
3926
- */
3927
- status: "queued" | "processing" | "done" | "failed";
3928
- /**
3929
- * @description The public URL of the generated asset. Present only when `status` is `done`.
3930
- * @example https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png
3931
- */
3932
- url?: string;
3933
- /** @description A human readable error message. Present only when `status` is `failed`. */
3934
- error?: string;
3935
- };
4403
+ "application/json": components["schemas"]["GenerationResponse"];
3936
4404
  };
3937
4405
  };
3938
4406
  /** @description The generation job has been queued. Poll the status endpoint. */
@@ -3945,7 +4413,63 @@ export interface operations {
3945
4413
  [name: string]: unknown;
3946
4414
  };
3947
4415
  content: {
3948
- "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
4416
+ "application/json": components["schemas"]["GenerationResponse"];
4417
+ };
4418
+ };
4419
+ /** @description The request is invalid, for example a missing asset or prompt, a disallowed URL or a `length` that is not positive. */
4420
+ 400: {
4421
+ headers: {
4422
+ [name: string]: unknown;
4423
+ };
4424
+ content: {
4425
+ "application/json": components["schemas"]["GenerationErrorResponse"];
4426
+ };
4427
+ };
4428
+ /** @description The account has too few credits for this generation. `available` holds how many it has. */
4429
+ 402: {
4430
+ headers: {
4431
+ [name: string]: unknown;
4432
+ };
4433
+ content: {
4434
+ "application/json": components["schemas"]["GenerationErrorResponse"];
4435
+ };
4436
+ };
4437
+ /** @description The account cannot use this generation. `code` says why. */
4438
+ 403: {
4439
+ headers: {
4440
+ [name: string]: unknown;
4441
+ };
4442
+ content: {
4443
+ "application/json": components["schemas"]["GenerationErrorResponse"];
4444
+ };
4445
+ };
4446
+ /** @description The `Idempotency-Key` was already used for a different asset. */
4447
+ 409: {
4448
+ headers: {
4449
+ [name: string]: unknown;
4450
+ };
4451
+ content: {
4452
+ "application/json": components["schemas"]["GenerationErrorResponse"];
4453
+ };
4454
+ };
4455
+ /** @description The account has reached its generation quota. */
4456
+ 429: {
4457
+ headers: {
4458
+ [name: string]: unknown;
4459
+ };
4460
+ content: {
4461
+ "application/json": components["schemas"]["GenerationErrorResponse"];
4462
+ };
4463
+ };
4464
+ /** @description A service the request depends on is temporarily unavailable. `code` is `AiAccessUnavailable` when access to AI generation could not be confirmed. */
4465
+ 503: {
4466
+ headers: {
4467
+ /** @description Suggested seconds to wait before retrying. */
4468
+ "Retry-After"?: number;
4469
+ [name: string]: unknown;
4470
+ };
4471
+ content: {
4472
+ "application/json": components["schemas"]["GenerationErrorResponse"];
3949
4473
  };
3950
4474
  };
3951
4475
  };
@@ -3968,16 +4492,27 @@ export interface operations {
3968
4492
  [name: string]: unknown;
3969
4493
  };
3970
4494
  content: {
3971
- "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
4495
+ "application/json": components["schemas"]["GenerationResponse"];
3972
4496
  };
3973
4497
  };
3974
4498
  /** @description The generation job is still processing. */
3975
4499
  202: {
4500
+ headers: {
4501
+ /** @description Suggested seconds to wait before polling again. */
4502
+ "Retry-After"?: number;
4503
+ [name: string]: unknown;
4504
+ };
4505
+ content: {
4506
+ "application/json": components["schemas"]["GenerationResponse"];
4507
+ };
4508
+ };
4509
+ /** @description No generation job with this id exists for the calling account. */
4510
+ 404: {
3976
4511
  headers: {
3977
4512
  [name: string]: unknown;
3978
4513
  };
3979
4514
  content: {
3980
- "application/json": paths["/generate"]["post"]["responses"]["200"]["content"]["application/json"]["schema"];
4515
+ "application/json": components["schemas"]["GenerationErrorResponse"];
3981
4516
  };
3982
4517
  };
3983
4518
  };
@@ -4003,10 +4538,7 @@ export interface operations {
4003
4538
  [name: string]: unknown;
4004
4539
  };
4005
4540
  content: {
4006
- "application/json": {
4007
- /** @description The available models. */
4008
- models: paths["/models/{id}"]["get"]["responses"]["200"]["content"]["application/json"]["schema"][];
4009
- };
4541
+ "application/json": components["schemas"]["GenerationModelListResponse"];
4010
4542
  };
4011
4543
  };
4012
4544
  };
@@ -4032,113 +4564,17 @@ export interface operations {
4032
4564
  [name: string]: unknown;
4033
4565
  };
4034
4566
  content: {
4035
- "application/json": {
4036
- /**
4037
- * @description The identifier to set as the asset `model`. Carries no provider name, so routing can change without a public rename.
4038
- * @example seedance-2.0-text-to-video
4039
- */
4040
- model: string;
4041
- /**
4042
- * @description The asset type this model generates.
4043
- * @example video
4044
- * @enum {string}
4045
- */
4046
- type: "image" | "video" | "audio";
4047
- /**
4048
- * @description The model's display name, for a model picker.
4049
- * @example Seedance 2.0 · Text to video
4050
- */
4051
- name?: string;
4052
- /**
4053
- * @description What the model is suited to, in a sentence or two.
4054
- * @example Generate cinematic video with realistic motion, prompt-directed camera movement and optional synchronised audio.
4055
- */
4056
- description?: string;
4057
- /** @description What one generation with this model costs. */
4058
- pricing?: {
4059
- /**
4060
- * @description Credits per unit. A number when the rate is flat, or an object keyed by the values of the option named in `tieredBy`.
4061
- * @example {
4062
- * "480p": 0.9375,
4063
- * "720p": 1.8962,
4064
- * "1080p": 4.2625
4065
- * }
4066
- */
4067
- credits: number | {
4068
- [key: string]: unknown;
4069
- };
4070
- /** @description The option whose value selects the rate, and the value assumed when the option is absent. Present only when `credits` is keyed. */
4071
- tieredBy?: {
4072
- /** @example resolution */
4073
- option: string;
4074
- /** @example 720p */
4075
- default: string;
4076
- };
4077
- /** @description How many units a generation consumes. Take the value `measure` names, or `default` when the request carries none, hold it within `min` and `max`, divide by `per`, and round up when `round` is `up`. Absent when one generation is one unit. */
4078
- quantity?: {
4079
- /**
4080
- * @description What the count is taken from, and the scale it is measured in.
4081
- * @example clipSeconds
4082
- * @enum {string}
4083
- */
4084
- measure: "clipSeconds" | "promptCharacters";
4085
- /**
4086
- * @description How many of `measure` make one billable unit.
4087
- * @example 60
4088
- */
4089
- per: number;
4090
- /**
4091
- * @description Fewest accepted. A smaller request is charged at this.
4092
- * @example 3
4093
- */
4094
- min?: number;
4095
- /**
4096
- * @description Most accepted. A larger request is charged at this.
4097
- * @example 600
4098
- */
4099
- max?: number;
4100
- /**
4101
- * @description Assumed when the request carries no value.
4102
- * @example 30
4103
- */
4104
- default?: number;
4105
- /**
4106
- * @description Present when a partial unit is charged as a whole one. A 61 second track on a per-minute rate is charged as two minutes.
4107
- * @example up
4108
- * @enum {string}
4109
- */
4110
- round?: "up";
4111
- };
4112
- /**
4113
- * @description The date this rate took effect, or `legacy` for a rate that predates dated pricing.
4114
- * @example 2026-08-13
4115
- */
4116
- effectiveFrom: string;
4117
- };
4118
- /** @description JSON Schema for the model's `options` object. Only returned for a single model, or for a list requested with `expand=options`. Values outside this schema are rejected. */
4119
- options?: {
4120
- [key: string]: unknown;
4121
- };
4122
- /**
4123
- * @description Whether the account behind the calling API key can generate with this model. Omitted when that cannot be determined; treat a missing value as unknown, not as available. Generation requests are checked either way.
4124
- * @example false
4125
- */
4126
- available?: boolean;
4127
- /**
4128
- * @description Why `available` is false. `AiCapabilityNotIncluded`: the account's plan does not include this kind of generation. `AiDisabled`: AI generation is turned off for the account. `AiAccessUnavailable`: access could not be confirmed; try again later.
4129
- * @example AiCapabilityNotIncluded
4130
- * @enum {string}
4131
- */
4132
- unavailableReason?: "AiCapabilityNotIncluded" | "AiDisabled" | "AiAccessUnavailable";
4133
- };
4567
+ "application/json": components["schemas"]["GenerationModel"];
4134
4568
  };
4135
4569
  };
4136
- /** @description No model exists with that identifier. */
4570
+ /** @description No listed model has that identifier. `error.name` tells an unknown model from one that has been withdrawn. */
4137
4571
  404: {
4138
4572
  headers: {
4139
4573
  [name: string]: unknown;
4140
4574
  };
4141
- content?: never;
4575
+ content: {
4576
+ "application/json": components["schemas"]["GenerationModelErrorResponse"];
4577
+ };
4142
4578
  };
4143
4579
  };
4144
4580
  };
@@ -4219,6 +4655,17 @@ export interface operations {
4219
4655
  /** @description Fetch an asset from a URL and send it to one or more destinations. */
4220
4656
  requestBody: {
4221
4657
  content: {
4658
+ /**
4659
+ * @example {
4660
+ * "url": "https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/moment.mp3",
4661
+ * "id": "018e8937-5015-75ee-aab6-03f214981133",
4662
+ * "destinations": [
4663
+ * {
4664
+ * "provider": "shotstack"
4665
+ * }
4666
+ * ]
4667
+ * }
4668
+ */
4222
4669
  "application/json": components["schemas"]["Transfer"];
4223
4670
  };
4224
4671
  };