@shotstack/shotstack-studio 2.16.3 → 2.18.0

package/package.json

@@ -6,7 +6,7 @@
 		"dazzatron",
 		"kratos2k7"
 	],
-	"version": "2.16.3",
+	"version": "2.18.0",
 	"description": "A video editing library for creating and editing videos with Shotstack",
 	"type": "module",
 	"main": "dist/shotstack-studio.umd.js",
@@ -99,7 +99,7 @@
 		"vite-plugin-dts": "^4.5.4"
 	},
 	"dependencies": {
-		"@shotstack/schemas": "1.14.1",
+		"@shotstack/schemas": "1.18.0",
 		"@shotstack/shotstack-canvas": "^2.10.2",
 		"howler": "^2.2.4",
 		"mediabunny": "^1.11.2",

package/readme.md

@@ -190,6 +190,41 @@ Available event names:
 | Output | `output:resized`, `output:resolutionChanged`, `output:aspectRatioChanged`, `output:fpsChanged`, `output:formatChanged`, `output:destinationsChanged` |
 | Merge fields | `mergefield:changed` |
 
+### Generating assets from prompts
+
+An image, video or audio asset can carry a `prompt`. Rendering generates from the prompt;
+`src`, when present, is the editor preview. Register a generator and the editor offers a
+generate action in the toolbar's generate pane:
+
+```typescript
+edit.registerAssetGenerator(async ({ clipId, asset, signal }) => {
+	const url = await myBackend.generate(asset, { signal });
+	return { url };
+});
+```
+
+Pass a model catalogue as the registration's `catalogue` option to show model and option
+controls. Entries must include their option schema; those without one are ignored. The
+[Edit API](https://shotstack.io/docs/api/#shotstack-edit) returns this shape from
+`GET /models?expand=options`. The SDK stores a snapshot; fetching and refreshing it remain
+the host's responsibility.
+
+The SDK writes the returned URL to the clip, so the change is undoable and autosaves
+like any other edit. It tracks whether a clip is generating or has failed, and renders
+those states; a rejection's message is shown as-is next to a retry action. Everything
+else — which models exist, what they cost, what an error means — stays with the host.
+
+Generation state is transient: it is never saved to the edit, never part of undo, and
+gone on reload. Deleting a clip mid-generation aborts its request via the `signal`.
+
+A prompt is the only thing that makes a clip generate. Add one to a plain `image`, `video`
+or `audio` asset to make it generative; clear it and the clip keeps its current `src` and
+stops generating, which is how you hold on to a result you want.
+
+Generation is content-addressed, so the same prompt, model and options resolve to the same
+asset on every render. A generator that does not go through Shotstack's own generation
+hands back a preview that the render replaces.
+
 ### Canvas
 
 `Canvas` renders the current edit.