@shotstack/cli 0.8.4 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",
@@ -27,7 +27,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@shotstack/schemas": "^1.20.1",
+    "@shotstack/schemas": "^1.22.0",
     "commander": "^12.1.0",
     "zod": "^4.4.3"
   },

package/skills/shotstack/SKILL.md

@@ -13,11 +13,20 @@ license: Apache-2.0
 
 This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.). All operations here are shell commands. There is no embedded UI, no iframe, no inline canvas, no MCP tool surface — only `shotstack` invocations from a terminal. To hand off to a human, run `shotstack studio <file>`; this opens the user's default browser to a `shotstack.studio` URL. Tell the user to click Render *in the browser tab*, not in any UI inside the terminal.
 
+## Check versions once per session
+
+This skill is version **0.10.0** and needs `@shotstack/cli` **0.10.0** or later. Before the first `shotstack` command in a session:
+
+1. Run `shotstack --version`. If it is older than 0.10.0, tell the user: what this skill documents, such as `generate --quote`, is missing until they run `npm install -g @shotstack/cli@latest`.
+2. Run `npm view @shotstack/cli version`. If it is newer than this skill's version, tell the user an update is available and ask whether to install it. Only on a yes, run `npx skills update shotstack -y` and `npm install -g @shotstack/cli@latest`. Never update without asking. `npx skills check` is not a read-only check: it installs the update.
+
+If a check fails (no network, no npm, a sandbox), skip it and carry on.
+
 **Open-ended first render? Ask before composing.** If the ask doesn't state what the video is (subject, format or destination) — e.g. "render my first video", "make me a video", "set up Shotstack" — read [`references/onboarding.md`](references/onboarding.md) and ask its discovery questions, then WAIT for answers. Do not write an Edit first. An open-ended ask is not a specification, and a stray JSON file in the project doesn't make the user experienced. Compose without asking only when the user has stated what the video is, or explicitly says to just show anything.
 
-Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one.
+Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one. `models` lists the generation models for prompt-driven assets and whether this key can use each one; `models <id>` prints the options a model accepts. `generate <model> "<prompt>"` generates one asset on its own and prints its URL.
 
-**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
+**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
 
 ## Authentication
 
@@ -36,7 +45,7 @@ Or set an environment variable (overrides the saved key — best for CI):
 export SHOTSTACK_API_KEY=...
 ```
 
-Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
+Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
 
 ## Environments
 
@@ -85,6 +94,31 @@ The bare command (no `--watch`) returns only an `id`; the hosted `source` URL do
 
 Other ingest subcommands: `ingest fetch <url>` (host a copy of a remote URL), `ingest status <id>`, `ingest list`, `ingest delete <id>`. **Read [`references/ingest.md`](references/ingest.md) for the full upload→render workflow, status values, and supported file types.**
 
+## Generating assets
+
+An `image`, `video` or `audio` asset with a `prompt` and a `model` is generated by AI. `shotstack models` lists the models and whether this API key can use each one. `shotstack models <id>` adds the JSON Schema for that model's `options`. Read it before setting `options`, because values outside it are rejected.
+
+```sh
+shotstack models --output json
+shotstack models seedance-2.0-text-to-video --output json
+```
+
+Offer only models marked available. `unavailable: AiCapabilityNotIncluded` means the plan doesn't include that kind of generation, `AiDisabled` means AI is turned off for the account, and `AiAccessUnavailable` means access couldn't be confirmed, so try again later. "availability unknown" means the check didn't run. It is not a yes.
+
+`shotstack generate <model> "<prompt>"` generates one asset without rendering an edit and prints its URL. Use it to try a prompt, a voice or a still before building it into a timeline. Inside an edit, set `prompt` and `model` on the asset instead and it is generated at render time.
+
+```sh
+shotstack generate nano-banana-2 "A ceramic mug on a walnut desk, soft window light" \
+  --options '{"resolution":"2K","aspectRatio":"16:9"}' --watch --output json | tail -n1 | jq -r .url
+shotstack generate seedance-2.0-text-to-video "Waves break over black sand at dusk" --length 5 --watch
+```
+
+`--length` is the clip length in seconds. Models that generate to a duration use it in place of their own duration option.
+
+**Generation costs credits on stage as well as v1.** Before generating, run the same command with `--quote`, tell the user the model and the credits it prints (it says "up to" when the final charge can be lower), and wait for a yes. Identical requests share one job and its cached result: repeating a request while it runs, or after it finishes, returns the same job without charging again. That is also how to pick up a job started without `--watch`. Sending a failed generation again retries it, and that is charged.
+
+**Read [`references/generation.md`](references/generation.md) before writing a prompt.** It covers what each model responds to, when to put text in a `rich-text` layer instead of the image, and how to size and chain generations inside an edit.
+
 ## Default workflow: preview in Studio (no key, no credits)
 
 **`shotstack studio <file>` is the default way to look at an edit** — prefer it over `render` unless you specifically need a cloud-exported MP4. It posts the JSON to https://shotstack.studio and opens `https://shotstack.studio/s/<slug>` in the browser — a short, shareable URL. No API key, no render credits charged; it previews client-side, so it works with no key. The human plays, edits, and decides whether to spend credits on a render.
@@ -163,6 +197,7 @@ This skill ships sub-references for the gnarly bits:
 - [`references/html5.md`](references/html5.md) — HTML5 asset: fields, preloaded libs (gsap/d3/anime/lottie), browser harness, sizing, worked examples
 - [`references/html5-snippets.md`](references/html5-snippets.md) — copy-paste motion-graphic clips: kinetic headline, value reveal, shine sweep, pulsing CTA, film grain
 - [`references/fonts.md`](references/fonts.md) — built-in fonts, Google Fonts URL pattern, custom-font workflow
+- [`references/generation.md`](references/generation.md) — per-model prompting craft for AI-generated video, images, speech and music, and what a timeline adds to a prompt. Read before writing any `prompt`.
 - [`references/asset-library.md`](references/asset-library.md) — placeholder videos, images, music
 - [`references/troubleshooting.md`](references/troubleshooting.md) — common errors and fixes
 

package/skills/shotstack/references/caption.md

@@ -183,7 +183,7 @@ Rich-caption transcribes audio to produce word-level timing. Three ways to sourc
 
 | `src` value | Behaviour |
 |---|---|
-| `alias://<name>` | Auto-transcribe a referenced audio/video/text-to-speech clip. Set `alias: "<name>"` on the source clip. **Preferred for sync.** |
+| `alias://<name>` | Auto-transcribe a referenced audio or video clip, including generated speech. Set `alias: "<name>"` on the source clip. **Preferred for sync.** |
 | Subtitle file URL | Use existing `.srt` or `.vtt` file. No auto-transcription. |
 | Audio/video file URL | Auto-transcribe a standalone media file. Use when there's no source clip on the timeline. |
 

package/skills/shotstack/references/generation.md

@@ -0,0 +1,100 @@
+# Generating assets
+
+`shotstack models <id>` shows what a model *accepts*. This is what produces a good result.
+
+Set an asset's `prompt` and `model` and the asset is generated at render time; `options` configures the generator. Everything below is per-model craft, then a section on what the surrounding timeline can contribute.
+
+## Video — Seedance
+
+**Verbs carry the generation.** The model animates motion, so spend the words there and describe consequences rather than states: "leaves scatter on each impact", not "leaves on the ground".
+
+**Dialogue in double quotes gets lip-synced**, and picture and sound are generated in one pass rather than layered afterwards. Name the vocal tone you want.
+
+**Silence is a parameter, not a phrase.** Set `generateAudio: false`. Writing "no music" in the prompt is not the mechanism.
+
+**Cuts must be asked for**, with "cut to". Consistency holds across cuts inside a single generation — roughly three per take — and a multi-cut single generation is more consistent than the same shots generated separately.
+
+**Duration is a beat budget.** Fit the described action to the time available. Overpacking a short clip produces rushing and incoherence; it does not compress gracefully. A prompt written for fifteen seconds will not survive being asked for five.
+
+There is no prompt-length limit on the model itself. The API caps `prompt` at 4,000 characters.
+
+**Choosing a generation.** 2.5 for duration: up to 30 seconds in one take, against 2.0's 15. ByteDance also claims better prompt adherence for 2.5, which its own pages don't corroborate. **2.0 for cost**: it is cheaper per second at every resolution, and both top out at 1080p. `shotstack models` has the current rates.
+
+## Images — Nano Banana
+
+Write plain descriptive sentences, not comma-separated tags with quality boosters. Photographic and cinematographic vocabulary works and appears in the vendor's own examples: shot type, camera angle and proximity, lighting setup, lens and focal length.
+
+**There is no negative prompt.** No such field exists. Phrase exclusions as positive instructions — "an empty desk" rather than "no clutter".
+
+**Quote text that must appear**, and describe the font in plain words rather than by name:
+
+```
+the text "Grand Opening" in a clean, bold, sans-serif
+```
+
+Iterative refinement is not available on this route. Each generation is single-shot.
+
+**Which tier.** The standard tier is the right default: on general image quality, character work and stylisation it matches or beats the Pro tier at roughly half the price, and it offers a 0.5K option Pro does not. Reach for Pro for hard, multi-instruction, information-dense compositions at high resolution, where its much larger output budget tells. Not for "better images" generally.
+
+1024–1536 px on the long edge suffices for screen use.
+
+### Text inside an image, or over it
+
+Short, decorative, one line — generate it and check the result. Copy that must be spelled correctly, must run to several lines, or must survive a merge-field substitution — generate a plain background and composite a `rich-text` asset over it. A real font is spell-correct by construction, resolution-independent, and can be reworded without regenerating the image.
+
+## Speech
+
+Three providers: **ElevenLabs**, **MiniMax** and **Amazon Polly**. Run `shotstack models` for the current ids.
+
+The script is the instrument. Most bad output is a writing problem, not a settings problem.
+
+**Numbers and currency are the most common defect.** Spell out anything you care about. Dates in numeric form are read as digit runs.
+
+**ElevenLabs** is the default. Audio tags like `[laughs]` belong to a newer generation of its models and do nothing on the endpoints offered here. Stage directions written inline are read aloud rather than interpreted.
+
+**Voice choice has no evidence behind it** beyond the vendors' own descriptors, and preset lists rotate. Pick by listening, not by name.
+
+**Polly** takes a free-string voice and is the odd one out: its remedies are all SSML, which is unreachable because input is sent as plain text and escaped. Newscaster style works on four voices only — Matthew, Joanna, Lupe and Amy — and requesting it on any other fails the render.
+
+**MiniMax** publishes a far larger voice catalogue than the seventeen names listed here, and several controls it supports — speed, volume, pitch, emotion — are not exposed. Treat the listed voices as the supported set.
+
+Speech length is not knowable in advance. Set the clip's `length` to `"auto"` and let it take the produced file's duration, rather than guessing a slot and overrunning it.
+
+## Music
+
+**Eleven Music.** A prompt answers genre, mood, instrumentation, tempo and production era whether or not you intend it to. Whatever you leave out, the model chooses.
+
+**Production vocabulary does real work** — "dusty", "vinyl crackle", "sparse", "ethereal". Give a BPM when timing matters; the model holds a stated tempo precisely. Naming a key helps, less reliably.
+
+**Naming a musician or band is refused**, as is quoting copyrighted lyrics. The error includes a suggested alternative prompt. Describe the era and production style instead: "1990s trip-hop with detuned Rhodes and a heavy swung break".
+
+Add "instrumental only" to the prompt, or set `forceInstrumental` for a guarantee. That flag cannot be combined with a composition plan.
+
+**Composition plans** describe a track section by section — reach for one when you need section structure, lyric placement or a multi-vocalist arrangement, not at any particular length. Section durations are exact and sum to the track length. Keep style entries as short tags, pair every positive list with a negative one, and put what should never change in the global styles. To keep a planned section instrumental, leave its `lines` empty and add "vocals" to its negative styles.
+
+## Working inside a timeline
+
+An Edit knows things a bare prompt does not. This is the part no standalone generator can do for you.
+
+**Match the generation's aspect ratio to your output.** A 9:16 generation inside a 16:9 edit gets cropped, and you paid for the pixels thrown away. The exception is deliberate: generate oversized when a later pan, zoom or reframe needs somewhere to move.
+
+**Generate stills larger than the video that consumes them.** A 1K still feeding a 720p clip asks the video model to invent about half again as much detail as the source held. Use 2K when the target is 720p or above.
+
+**Anchor stills become frame one, so everything static is inherited.** Composition, lighting and style all come from the still; the prompt should describe only motion. There is no fixing a badly-composed anchor in the video prompt. Artefacts get worse in motion rather than better, so a still with malformed hands or heavy compression is not usable.
+
+**Chain at most two or three generated clips.** Feeding each clip's last frame into the next accumulates drift, and it degrades well before any advertised limit.
+
+**Continuity across a cut is usually not what you want.** Most cuts are meant to break continuity — a new angle, a new location, a time jump. Carry a frame forward when you specifically want the shots to feel continuous, not by default.
+
+**Keep a repeated style clause** across separately generated assets when they need to look like a set. There is no project-level style; the shared sentence is the mechanism.
+
+## What does not work
+
+- **A fixed seed does not carry a look across different prompts.** Seeds give reproducibility for an identical prompt and nothing more.
+- **Film stock names, "colour grade" and "LUT"** are not part of the documented vocabulary. Use shot type, lighting, angle and focal length instead.
+- **Repeating the aspect ratio or resolution in the prompt** does nothing. Set the option.
+- **Negative prompts** do not exist on the image models. Phrase it positively.
+
+## flux-schnell
+
+No craft guidance. Its vendor no longer documents the endpoint anywhere, so nothing about it can be stated with confidence.

package/skills/shotstack/references/troubleshooting.md

@@ -119,7 +119,7 @@ Then run `shotstack feedback` — the dossier captures the response body and the
 
 ## Render takes much longer than expected
 
-Renders containing AI-generation assets (`text-to-image`, `image-to-video`) take longer because the engine waits for the AI job to complete before rendering. Renders with very long source videos or many tracks also take longer.
+Renders containing AI-generated assets (an `image`, `video` or `audio` asset with a `prompt`) take longer because the engine waits for the AI job to complete before rendering. Renders with very long source videos or many tracks also take longer.
 
 **Fix:** if you're iterating quickly, render with `output.resolution: "preview"` first (512×288 @ 15fps) to validate the timeline shape before spending credits on full-resolution output.
 

package/skills/shotstack/shared/agent-core.md

@@ -218,17 +218,14 @@ Use only the **current** asset types; the deprecated ones still parse but should
 
 | Type | Purpose |
 |---|---|
-| `video` | Video file (mp4, mov, webm). |
-| `image` | Static image — `jpg`, `png`, `webp`, `gif`, `bmp`, `tiff`. |
-| `audio` | Audio clip placed at a specific time on the timeline. |
+| `video` | Video file (mp4, mov, webm), or AI-generated from a `prompt`. |
+| `image` | Static image — `jpg`, `png`, `webp`, `gif`, `bmp`, `tiff` — or AI-generated from a `prompt`. |
+| `audio` | Audio clip placed at a specific time on the timeline, or AI-generated speech or music from a `prompt`. |
 | `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
 | `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See `references/svg.md`. |
 | `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap/d3/anime/lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
 | `rich-caption` | Word-level animated captions sourced from audio, video, or subtitle files. See `references/caption.md`. |
 | `luma` | Luma matte for masking effects. |
-| `image-to-video` | **AI**: animate a still image into a short video clip. Billed per generation. |
-| `text-to-image` | **AI**: generate an image from a text prompt. Billed per generation. |
-| `text-to-speech` | **AI**: generate speech from a text prompt. Billed per generation. |
 
 `timeline.fonts[]` is a separate field for custom font URLs (not an asset type).
 
@@ -236,7 +233,7 @@ For background music, **use an `audio` asset on its own track** with `length: "e
 
 ### Deprecated — do not use
 
-`text`, `title`, `caption`, `html`, `shape`. They still parse but produce inferior output. Replace with:
+`text`, `title`, `caption`, `html`, `shape`. They still parse but produce inferior output. `text-to-image`, `image-to-video` and `text-to-speech` still work, rewritten internally to the generated assets below. Replace with:
 
 | If you'd use… | Use instead |
 |---|---|
@@ -245,10 +242,19 @@ For background music, **use an `audio` asset on its own track** with `length: "e
 | `html` | `html5` (for motion graphics or animated overlays) or `rich-text` (for static styled text) |
 | `shape` | `svg` with `<rect>`, `<circle>`, `<polygon>` etc. |
 | `timeline.soundtrack` | `audio` asset on its own track with `length: "end"` |
+| `text-to-image`, `image-to-video`, `text-to-speech` | `image`, `video` or `audio` with `prompt` and `model` (below) |
 
 ### AI-generated assets
 
-`image-to-video`, `text-to-speech`, and `text-to-image` are billed per generation **even when invoked through the sandbox stage endpoint** (which is otherwise free). They are async — the render submits the AI job and waits. Renders containing AI assets take longer.
+Set `prompt` and `model` on an `image`, `video` or `audio` asset and it is generated at render time. `options` configures the model, and a `src` you set is only a preview placeholder that the generated file replaces. For speech, the prompt is the words to speak.
+
+```json
+{ "asset": { "type": "video", "prompt": "Slow dolly across a rain-soaked neon street at night", "model": "seedance-2.0-text-to-video", "options": { "resolution": "720p" } }, "start": 0, "length": 5 }
+```
+
+The models endpoint (`GET /models`) lists each model, whether the account can use it, and the JSON Schema for its `options`. `POST /generate/quote` takes the same body as `POST /generate` and returns its cost in credits without charging. Options outside that schema are rejected. To animate a still, use an image-to-video model and put the image URL in `options.startSrc` (`inputSrc` on the original image-to-video models).
+
+Generation is billed per asset **even on the stage endpoint**, which is otherwise free. Renders containing AI assets take longer, because the render waits for each generation.
 
 ## The design ladder — escalate from rich-text to html5