@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.
@@ -480,6 +480,165 @@
480
480
  }
481
481
  ]
482
482
  },
483
+ "/generate": {
484
+ "post": {
485
+ "responses": {
486
+ "200": {
487
+ "description": "The generated asset was already cached and is immediately available.",
488
+ "content": {
489
+ "application/json": {
490
+ "schema": {
491
+ "description": "The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset.",
492
+ "type": "object",
493
+ "properties": {
494
+ "id": {
495
+ "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.",
496
+ "type": "string",
497
+ "example": "8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e"
498
+ },
499
+ "status": {
500
+ "description": "The status of the generation job.",
501
+ "type": "string",
502
+ "enum": [
503
+ "queued",
504
+ "processing",
505
+ "done",
506
+ "failed"
507
+ ],
508
+ "example": "done"
509
+ },
510
+ "url": {
511
+ "description": "The public URL of the generated asset. Present only when `status` is `done`.",
512
+ "type": "string",
513
+ "example": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png"
514
+ },
515
+ "error": {
516
+ "description": "A human readable error message. Present only when `status` is `failed`.",
517
+ "type": "string"
518
+ }
519
+ },
520
+ "required": [
521
+ "id",
522
+ "status"
523
+ ]
524
+ }
525
+ }
526
+ }
527
+ },
528
+ "202": {
529
+ "description": "The generation job has been queued. Poll the status endpoint.",
530
+ "headers": {
531
+ "Location": {
532
+ "description": "The relative URL to poll for job status.",
533
+ "schema": {
534
+ "type": "string"
535
+ }
536
+ },
537
+ "Retry-After": {
538
+ "description": "Suggested seconds to wait before polling.",
539
+ "schema": {
540
+ "type": "integer"
541
+ }
542
+ }
543
+ },
544
+ "content": {
545
+ "application/json": {
546
+ "schema": {
547
+ "$ref": "#/paths/~1generate/post/responses/200/content/application~1json/schema"
548
+ }
549
+ }
550
+ }
551
+ }
552
+ },
553
+ "description": "Generate a single image, video or audio asset from a text prompt without\nrendering a full edit. Submit a prompt-bearing asset; the response is\nimmediate when an identical asset has been generated before (results are\ncached by prompt, model and options), otherwise the job is queued and can\nbe polled via the status endpoint.\n\nGeneration is billed in credits per asset. Identical repeat requests\nresolve from the cache at no charge.\n\n**Base URL:** <a href=\"#\">https://api.shotstack.io/edit/{version}</a>\n",
554
+ "summary": "Generate Asset",
555
+ "operationId": "postGenerate",
556
+ "requestBody": {
557
+ "description": "A prompt-bearing image, video or audio asset to generate.",
558
+ "content": {
559
+ "application/json": {
560
+ "schema": {
561
+ "type": "object",
562
+ "properties": {
563
+ "asset": {
564
+ "oneOf": [
565
+ {
566
+ "$ref": "#/components/schemas/ImageAsset"
567
+ },
568
+ {
569
+ "$ref": "#/components/schemas/VideoAsset"
570
+ },
571
+ {
572
+ "$ref": "#/components/schemas/AudioAsset"
573
+ }
574
+ ]
575
+ }
576
+ },
577
+ "required": [
578
+ "asset"
579
+ ]
580
+ }
581
+ }
582
+ }
583
+ },
584
+ "security": [
585
+ {
586
+ "DeveloperKey": []
587
+ }
588
+ ],
589
+ "tags": [
590
+ "Edit"
591
+ ]
592
+ }
593
+ },
594
+ "/generate/{id}": {
595
+ "get": {
596
+ "responses": {
597
+ "200": {
598
+ "description": "The generation job has finished (done or failed).",
599
+ "content": {
600
+ "application/json": {
601
+ "schema": {
602
+ "$ref": "#/paths/~1generate/post/responses/200/content/application~1json/schema"
603
+ }
604
+ }
605
+ }
606
+ },
607
+ "202": {
608
+ "description": "The generation job is still processing.",
609
+ "content": {
610
+ "application/json": {
611
+ "schema": {
612
+ "$ref": "#/paths/~1generate/post/responses/200/content/application~1json/schema"
613
+ }
614
+ }
615
+ }
616
+ }
617
+ },
618
+ "description": "Get the status of an on-demand asset generation job created with the\ngenerate endpoint. Jobs are owner-scoped.\n\n**Base URL:** <a href=\"#\">https://api.shotstack.io/edit/{version}</a>\n",
619
+ "summary": "Get Generation Status",
620
+ "operationId": "getGenerate",
621
+ "security": [
622
+ {
623
+ "DeveloperKey": []
624
+ }
625
+ ],
626
+ "tags": [
627
+ "Edit"
628
+ ]
629
+ },
630
+ "parameters": [
631
+ {
632
+ "in": "path",
633
+ "name": "id",
634
+ "required": true,
635
+ "schema": {
636
+ "type": "string"
637
+ },
638
+ "description": "The generation job id returned by the generate endpoint."
639
+ }
640
+ ]
641
+ },
483
642
  "/assets/{id}": {
484
643
  "get": {
485
644
  "responses": {
@@ -1191,7 +1350,7 @@
1191
1350
  "additionalProperties": false
1192
1351
  },
1193
1352
  "VideoAsset": {
1194
- "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.\n",
1353
+ "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.\n",
1195
1354
  "type": "object",
1196
1355
  "properties": {
1197
1356
  "type": {
@@ -1203,78 +1362,32 @@
1203
1362
  "type": "string"
1204
1363
  },
1205
1364
  "src": {
1206
- "description": "The video source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
1365
+ "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.",
1207
1366
  "type": "string",
1208
1367
  "minLength": 1,
1209
1368
  "pattern": "\\S",
1210
1369
  "example": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4"
1211
1370
  },
1212
1371
  "prompt": {
1213
- "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.",
1372
+ "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).",
1214
1373
  "type": "string",
1215
1374
  "maxLength": 4000,
1216
1375
  "example": "Slowly zoom out and orbit left around the object."
1217
1376
  },
1218
- "inputSrc": {
1219
- "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.",
1220
- "type": "string",
1221
- "minLength": 1,
1222
- "example": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/input-image.jpg"
1223
- },
1224
1377
  "model": {
1225
- "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.",
1226
- "type": "string",
1227
- "example": "luma-ray-3"
1228
- },
1229
- "resolution": {
1230
- "description": "Output resolution for video generation. Only meaningful when `prompt` is set and the model supports it (e.g. `fal/seedance-2.0`).",
1231
- "enum": [
1232
- "480p",
1233
- "720p",
1234
- "1080p"
1235
- ],
1236
- "type": "string",
1237
- "example": "720p"
1238
- },
1239
- "duration": {
1240
- "description": "Target video duration in seconds for generation models that accept it. `\"auto\"` lets the model decide. Only meaningful when `prompt` is set.",
1241
- "enum": [
1242
- "auto",
1243
- "4",
1244
- "5",
1245
- "6",
1246
- "7",
1247
- "8",
1248
- "9",
1249
- "10",
1250
- "11",
1251
- "12",
1252
- "13",
1253
- "14",
1254
- "15"
1255
- ],
1378
+ "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.",
1256
1379
  "type": "string",
1257
- "default": "auto",
1258
- "example": "5"
1380
+ "example": "seedance-2.0"
1259
1381
  },
1260
- "aspectRatio": {
1261
- "description": "Aspect ratio for the generated video. Only meaningful when `prompt` is set and the model supports it.",
1262
- "enum": [
1263
- "1:1",
1264
- "16:9",
1265
- "9:16",
1266
- "4:3",
1267
- "3:4",
1268
- "21:9",
1269
- "9:21"
1270
- ],
1271
- "type": "string",
1272
- "example": "16:9"
1273
- },
1274
- "generateAudio": {
1275
- "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`).",
1276
- "type": "boolean",
1277
- "default": false
1382
+ "options": {
1383
+ "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.",
1384
+ "type": "object",
1385
+ "additionalProperties": true,
1386
+ "example": {
1387
+ "resolution": "720p",
1388
+ "duration": "8",
1389
+ "generateAudio": true
1390
+ }
1278
1391
  },
1279
1392
  "transcode": {
1280
1393
  "type": "boolean",
@@ -1337,7 +1450,7 @@
1337
1450
  ]
1338
1451
  },
1339
1452
  "ImageAsset": {
1340
- "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.\n",
1453
+ "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.\n",
1341
1454
  "type": "object",
1342
1455
  "properties": {
1343
1456
  "type": {
@@ -1349,46 +1462,31 @@
1349
1462
  "type": "string"
1350
1463
  },
1351
1464
  "src": {
1352
- "description": "The image source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
1465
+ "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.",
1353
1466
  "type": "string",
1354
1467
  "minLength": 1,
1355
1468
  "pattern": "\\S",
1356
1469
  "example": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg"
1357
1470
  },
1358
1471
  "prompt": {
1359
- "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.",
1472
+ "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.",
1360
1473
  "type": "string",
1361
1474
  "maxLength": 4000,
1362
1475
  "example": "A serene landscape with a crystal-clear mountain lake at sunrise."
1363
1476
  },
1364
1477
  "model": {
1365
- "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.",
1478
+ "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.",
1366
1479
  "type": "string",
1367
1480
  "example": "flux-schnell"
1368
1481
  },
1369
- "resolution": {
1370
- "description": "Output resolution tier for supported image generation models. `1K` (default), `2K`, or `4K`. Only meaningful when `prompt` is set.",
1371
- "enum": [
1372
- "1K",
1373
- "2K",
1374
- "4K"
1375
- ],
1376
- "type": "string",
1377
- "example": "1K"
1378
- },
1379
- "aspectRatio": {
1380
- "description": "Aspect ratio for the generated image. Only meaningful when `prompt` is set and the model supports it.",
1381
- "enum": [
1382
- "1:1",
1383
- "16:9",
1384
- "9:16",
1385
- "4:3",
1386
- "3:4",
1387
- "21:9",
1388
- "9:21"
1389
- ],
1390
- "type": "string",
1391
- "example": "1:1"
1482
+ "options": {
1483
+ "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.",
1484
+ "type": "object",
1485
+ "additionalProperties": true,
1486
+ "example": {
1487
+ "resolution": "1K",
1488
+ "aspectRatio": "16:9"
1489
+ }
1392
1490
  },
1393
1491
  "crop": {
1394
1492
  "$ref": "#/components/schemas/Crop"
@@ -1632,7 +1730,7 @@
1632
1730
  ]
1633
1731
  },
1634
1732
  "AudioAsset": {
1635
- "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.\n",
1733
+ "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.\n",
1636
1734
  "type": "object",
1637
1735
  "properties": {
1638
1736
  "type": {
@@ -1644,54 +1742,31 @@
1644
1742
  "type": "string"
1645
1743
  },
1646
1744
  "src": {
1647
- "description": "The audio source URL. The URL must be publicly accessible or include credentials. Provide either `src` or `prompt`, not both.",
1745
+ "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.",
1648
1746
  "type": "string",
1649
1747
  "minLength": 1,
1650
1748
  "pattern": "\\S",
1651
1749
  "example": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/sound.mp3"
1652
1750
  },
1653
1751
  "prompt": {
1654
- "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.",
1752
+ "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.",
1655
1753
  "type": "string",
1656
1754
  "maxLength": 4000,
1657
1755
  "example": "Welcome to today's broadcast."
1658
1756
  },
1659
- "voice": {
1660
- "description": "Voice identifier for text-to-speech generation (e.g. `Matthew`, `Joanna`). Only meaningful when `prompt` is set.",
1661
- "type": "string",
1662
- "example": "Matthew"
1663
- },
1664
- "language": {
1665
- "description": "Optional BCP-47 language code (e.g. `en-US`) for text-to-speech. Only meaningful when `prompt` and `voice` are set.",
1666
- "type": "string",
1667
- "example": "en-US"
1668
- },
1669
- "newscaster": {
1670
- "description": "Set to `true` to use the voice's newscaster mode when supported. Only meaningful when `prompt` and `voice` are set.",
1671
- "type": "boolean",
1672
- "default": false
1673
- },
1674
1757
  "model": {
1675
- "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.",
1758
+ "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.",
1676
1759
  "type": "string",
1677
1760
  "example": "polly-neural"
1678
1761
  },
1679
- "musicLengthMs": {
1680
- "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`).",
1681
- "type": "number",
1682
- "minimum": 3000,
1683
- "maximum": 600000,
1684
- "example": 30000
1685
- },
1686
- "forceInstrumental": {
1687
- "description": "Set to `true` to force instrumental music (no vocals). Only meaningful for music generation models.",
1688
- "type": "boolean",
1689
- "default": false
1690
- },
1691
- "compositionPlan": {
1692
- "description": "An optional structured composition plan for music generation. Only meaningful for music generation models (e.g. `fal/elevenlabs-music`).",
1693
- "type": "string",
1694
- "maxLength": 4000
1762
+ "options": {
1763
+ "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.",
1764
+ "type": "object",
1765
+ "additionalProperties": true,
1766
+ "example": {
1767
+ "voice": "Matthew",
1768
+ "language": "en-US"
1769
+ }
1695
1770
  },
1696
1771
  "trim": {
1697
1772
  "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.",