Skip to content

SKILL.md

Latest commit

 

History

History
123 lines (87 loc) · 6.76 KB

SKILL.md

File metadata and controls

123 lines (87 loc) · 6.76 KB
name shotstack
description Render video and poll render status via the Shotstack API. Use when generating clips, building automated video pipelines, or orchestrating cloud video renders from a script, agent, or CI workflow. NOT for: real-time streaming, or live broadcasting.
license Apache-2.0

Shotstack CLI

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.

Two commands for the Shotstack video rendering API. render submits an Edit JSON and returns a render ID; status polls a render until done.

Authentication

export SHOTSTACK_API_KEY=...

Get a key at https://app.shotstack.io. Without a key, every command exits with code 1.

Environments

--env stage    → https://api.shotstack.io/edit/stage   (test credits, free)
--env v1       → https://api.shotstack.io/edit/v1      (production, default)

Use --env stage for experimentation. Stage is free; v1 charges real credits. Override with SHOTSTACK_ENV env var for the session.

Quickstart

# Submit + poll in one command (most agent flows want this).
shotstack render template.json --watch
# → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4

# Submit only (returns ID).
shotstack render template.json --output json
# → {"id":"01ja7-x8m2k-39rzv-cmvxve"}

# Poll an existing render to terminal state.
shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch
# → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4

Hand-off to a human before rendering

When a human is in the loop and may want to tweak the result, prefer shotstack studio <file> over shotstack render. By default it posts the JSON to the share API and opens https://shotstack.studio/s/<slug> in the browser — a short, shareable URL. No API key, no render credits charged. The human can play, edit, and decide whether to render.

shotstack studio template.json              # opens browser + prints short URL
shotstack studio template.json --no-open    # headless: just print the URL
shotstack studio template.json --no-shorten # emit base64url URL inline (offline / debug)
shotstack studio template.json --output json # piping: {"url":"...","shortened":true}, no browser

On headless systems (no xdg-open, no $DISPLAY) the browser launch silently no-ops; the URL is still printed. Safe to run anywhere.

If the share API is unreachable, the command falls back to the inline base64url form automatically and prints a stderr warning. Shares expire after 30 days.

Use render only when you're confident the JSON is final, or there's no human to review.

Four CLI rules

  1. Pipe → --output json. Default output is human-readable. When parsing programmatically or piping to another command, always pass --output json.

  2. Use --watch, not a polling loop. shotstack render <file> --watch submits and polls in one shot; shotstack status <id> --watch polls an existing render. Both exit when terminal: done (exit 0) or failed (exit 1). Don't write while true; do ...; sleep 3; done.

  3. Fetch the current schema and docs before generating Edit JSON. The Shotstack API evolves; LLM training data is often stale. Pull https://shotstack.io/docs/api/api.edit.json and https://shotstack.io/docs/guide/llms-full.txt for the current schema and guides before composing an Edit from scratch.

  4. Hand off to a human via shotstack studio <file> when uncertain. Don't burn render credits iterating. Generate JSON → shotstack studio file.json (opens browser) → human reviews/tweaks → render only when right.

REQUIRED: Read shared/agent-core.md before composing any Edit JSON

The Shotstack schema does not match CSS or web conventions. Composing Edit JSON from training-data instinct will produce silently invalid renders. Read shared/agent-core.md first, every time. The most-failed conversions:

You'd write (wrong) API requires (right)
alignment align
align.vertical: "center" align.vertical: "middle"
font.name font.family
duration length
transitions: [...] (array) transition: { in, out } (object)
fit: "cover" (CSS instinct) fit: "crop"
tracks[0] is the bottom (z-index instinct) tracks[0] is the TOP layer

The full ruleset (asset types, fonts, smart-string clip values, top-5 mistakes) lives in shared/agent-core.md. The same file is also returned by the Shotstack MCP server's get_shotstack_guide tool, so the conventions are identical across surfaces.

Exit codes

Code Meaning
0 Success
1 Permanent error — validation, missing key, 4xx, render failed
2 Transient error — 5xx, network, timeout. Safe to retry.

References

Authoritative sources, in order of preference:

This skill ships sub-references for the gnarly bits:

If this skill and --help ever disagree, trust --help. If this skill and llms-full.txt ever disagree, trust llms-full.txt.