shotstack

Shotstack CLI

此技能适用于基于终端的 AI Agent（Claude Code、Cursor、Codex CLI、Gemini CLI 等）。此处的所有操作都是 Shell 命令。没有内嵌 UI、没有 iframe、没有内联画布，也没有 MCP 工具界面——只有在终端中调用 shotstack。如需交由人工处理，请运行 shotstack studio <file>；这会在用户的默认浏览器中打开 shotstack.studio URL。请告诉用户在浏览器标签页中点击 Render，而不是点击终端内的任何 UI。

每个会话检查一次版本

此技能的版本为 0.16.1，需要 @shotstack/cli 0.16.0 或更高版本。在会话中首次运行 shotstack 命令之前：

1. 运行 shotstack --version。如果版本低于 0.16.0，请告诉用户，此技能文档中介绍的功能（例如 inspect）尚不可用，直至运行 npm install -g @shotstack/cli@latest。
2. 运行 npm view @shotstack/cli version。如果此版本比技能版本更新，请告诉用户有可用更新，并询问是否安装。只有用户同意后，才运行 npx skills update shotstack -y 和 npm install -g @shotstack/cli@latest。未经询问，绝不更新。npx skills check 并非只读检查：它会安装更新。

如果检查失败（无网络、没有 npm 或处于沙盒环境），请跳过并继续。

首次渲染的需求不明确？先询问，再开始制作。 如果用户没有说明视频内容（主题、格式或目标位置）——例如“渲染我的第一条视频”“给我做一条视频”“设置 Shotstack”——请阅读 references/onboarding.md，并询问其中的需求了解问题，然后等待回答。不要先编写 Edit。需求不明确的请求不构成规格说明，项目中的一个 JSON 文件也不能证明用户有经验。只有在用户已说明视频内容，或明确表示随便做一个给他看时，才能不经询问直接制作。

这些命令用于 Shotstack 视频渲染 API。render 会提交 Edit JSON 并返回渲染 ID；status 会轮询渲染状态，直到完成。ingest 会上传你自己的本地文件（或获取远程 URL），并托管这些文件，以便在 Edit 中引用。validate 会检查 Edit；每次渲染前都要运行。studio 会在浏览器编辑器中打开一个 edit，供人工预览、调整和渲染。inspect 会在无头 Chrome 中，按你指定的时间点绘制 edit、渲染结果或视频的画面，并放入一张联系表中，让你无需渲染即可查看自己的作品。template list|get|create|update|delete 用于读取和写入保存到账号中的模板：list 会显示已保存模板（id + name）；get <id> 会获取已保存模板的 Edit JSON（例如用户在 Studio 中设计的模板），以便渲染或改编；create <file> --name <name> 会将一个 edit 保存为新模板；update <id> <file> 会覆盖模板；delete <id> 会删除模板。models 会列出用于提示词驱动素材的生成模型，以及此密钥能否使用各模型；models <id> 会打印模型接受的选项。generate <model> "<prompt>" 会单独生成一个素材并打印其 URL。analyze <url> 会免费分析音乐曲目的速度、节拍、小节、高潮段落和分段，但需要 API 密钥。

**默认流程——无需 API 密钥：**制作 → validate（离线检查）→ inspect（自行查看画面）→ studio（供人工预览的浏览器编辑器）。只有依赖 API 的命令（render、status、ingest、models、generate、analyze）需要密钥。只有在明确需要导出最终 MP4 到云端时才使用 render；其他情况都使用 studio——这是查看 edit 成本最低的方式，也是任何需要人工审核的创作任务的首选方式。

身份验证

使用 shotstack login 保存一次 API 密钥 — 密钥会按环境存储在 ~/.shotstack/credentials.json（chmod 600）中，因此无需每次会话都重新输入：

shotstack login                  # prompts (hidden input); saves the v1 (production) key
shotstack login --env stage      # save the stage key (Shotstack keys are env-specific)
echo "$KEY" | shotstack login    # non-interactive (CI / agents): read the key from stdin
shotstack logout --env stage     # forget one env;  shotstack logout --all  forgets all

或者设置环境变量（会覆盖已保存的密钥 — 最适合 CI）：

export SHOTSTACK_API_KEY=...

解析优先级：SHOTSTACK_API_KEY 环境变量 → 目标 --env 对应的已保存密钥 → 错误。 在 https://app.shotstack.io 获取密钥。validate 和 studio 无需密钥 — 只有由 API 支持的命令（render、status、ingest、models、generate、analyze）需要密钥；没有密钥时，这些命令会以状态码 1 退出，而 compose → validate → studio 仍可正常运行。

环境

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

成本最低的迭代方式是 studio — 而不是 stage。 studio 可在浏览器中进行客户端预览，无需密钥，也不消耗点数（见下方 Studio 章节）；请在此处迭代。需要渲染视频以供审阅时，--env stage 可免费进行云端渲染（带水印）；v1 会消耗实际点数。可通过 SHOTSTACK_ENV 环境变量为当前会话指定目标环境。ingest 命令会自动使用相同的密钥，访问并行的 …/ingest/{env} 基础路径。

快速入门

# 1 — Validate offline. Schema + same-track overlaps + fonts + URLs. No key, no credits.
shotstack validate template.json

# 2 — Preview in the browser. The DEFAULT next step: no key, no credits; a human hits Render.
shotstack studio template.json
# → opens https://shotstack.studio/s/<slug> and prints the short URL

# 3 — Export to MP4. Needs an API key and charges credits. Submit + poll in one command.
shotstack render template.json --watch
# → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4

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

上传本地文件以用于 Edit

Edit 只能通过 URL 引用媒体 — asset.src 中的本地路径无法渲染。要使用本地文件，请先通过 shotstack ingest upload 托管该文件，然后将返回的 URL 放入 Edit。

# Upload a local file and poll until it's hosted. --watch prints the URL.
shotstack ingest upload ./clip.mp4 --watch --output json
# → {"id":"zzytey4v-...","status":"importing"}
# → {"id":"zzytey4v-...","status":"ready","source":"https://shotstack-ingest-api-v1-sources.s3...amazonaws.com/.../source.mp4",...}

# Capture the hosted URL straight into a variable:
SRC=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -r .source)
# …then reference "$SRC" as an asset.src in your Edit JSON and run `shotstack render`.

这也适用于 html5 页面所用的图像和字体：将 URL 放入其 html 或 css 中。

不带 --watch 的命令只会返回一个 id；托管的 source URL 要等到摄取状态变为 ready 后才会生成。需要 URL 时，务必使用 --watch（或随后运行 shotstack ingest status <id> --watch）。

其他 ingest 子命令：ingest fetch <url>（托管远程 URL 的副本）、ingest status <id>、ingest list、ingest delete <id>。完整的上传→渲染工作流、状态值和支持的文件类型，请参阅 references/ingest.md。

生成素材

带有 prompt 和 model 的 image、video 或 audio 素材由 AI 生成。shotstack models 会列出各个模型，以及此 API 密钥能否使用这些模型。shotstack models <id> 会添加该模型 options 的 JSON Schema。设置 options 前请先阅读，因为不符合 Schema 的值会被拒绝。

shotstack models --output json
shotstack models seedance-2.0-text-to-video --output json

仅提供标记为可用的模型。unavailable: AiCapabilityNotIncluded 表示当前套餐不包含此类生成，AiDisabled 表示账户已关闭 AI，AiAccessUnavailable 表示无法确认访问权限，请稍后重试。“availability unknown”表示检查未运行，并不代表可用。

shotstack generate <model> "<prompt>" 无需渲染剪辑即可生成一项素材，并打印其 URL。可用它试验提示词、语音或静帧，再将其加入时间线。在剪辑中，应改为在素材上设置 prompt 和 model，这样素材会在渲染时生成。

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 是片段时长，单位为秒。对于按时长生成的模型，该参数会取代模型自身的时长选项。

在 stage 和 v1 上，生成都会消耗点数。 生成前，使用 --quote 运行同一命令，告知用户模型及命令显示的点数（若最终费用可能更低，命令会注明“最高”），并等待用户确认。相同请求会共用一个任务及其缓存结果：任务运行期间或完成后重复请求，都会返回同一个任务，不会再次扣费。对于不带 --watch 启动的任务，也可通过这种方式继续获取结果。再次发送失败的生成请求会重试，并会扣费。

要按音乐节拍剪辑或制作动画？ 使用 shotstack analyze <url> --output json 测量音轨，并遵循 references/beat-sync.md：根据节拍映射中的小节编写每处剪切和关键帧，绝不能根据你要求的 BPM 编写。

编写提示词前，请阅读 references/generation.md。 其中介绍了各个模型的响应方式、何时应将文本放入 rich-text 图层而不是图像中，以及如何在剪辑内调整生成素材的大小并串联生成。

默认工作流：在 Studio 中预览（无需密钥，无需点数）

查看剪辑时，默认使用 shotstack studio <file>——除非你明确需要导出到云端的 MP4，否则优先使用它，而不是 render。它会将 JSON 发送到 https://shotstack.studio，并在浏览器中打开 https://shotstack.studio/s/<slug>，这是一个简短且便于分享的 URL。不会扣除渲染点数；它在客户端预览，因此无需密钥即可使用（密钥仅用于永久保留短链接）。用户可以播放、编辑，并决定是否花费点数进行渲染。

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 --env stage  # share with the saved stage key
shotstack studio template.json --output json # piping: {"url":"...","shortened":true}, no browser

在无头系统上（没有 xdg-open 或 $DISPLAY），浏览器启动会静默地不执行任何操作；URL 仍会打印出来。可在任何环境中安全运行。

CLI 配置了 API 密钥时，短链接会永久有效（SHOTSTACK_API_KEY，或为 --env/SHOTSTACK_ENV 保存的密钥）。未配置密钥时，链接有效期为 30 天，命令会在 stderr 中说明；如果用户希望链接长期有效，建议使用 shotstack login。超时、429 或 5xx 错误会重试一次，之后命令会退回到内联 base64url 格式，并在 stderr 中打印原因。如果分享 API 拒绝该剪辑（超过 1 MB、缺少 timeline 或 output，或密钥无效），命令会以状态码 1 退出并说明原因：修复问题，或使用 --no-shorten。

任何复杂内容都默认使用 studio——多场景、多轨道，或任何会由感兴趣的用户审阅的创作内容。它在客户端预览、无需花费，并允许用户在满意时点击 Render。仅在单镜头/简单剪辑、自动化管道，或用户明确说“直接渲染”时，才直接使用 render。

使用 inspect 检查帧（无需密钥，无需积分）

shotstack inspect 会在无头 Chrome 中将编辑内容载入 Studio，并将指定时间点的帧写入同一张图像，每个图块都会标注对应时间。打开图像查看即可。此功能需要 Google Chrome，或在 macOS 和 Linux 上使用 Edge 或 Brave；CHROME_PATH 可用于指定其他基于 Chromium 的浏览器。编辑内容或视频 URL 均无需密钥。

shotstack inspect edit.json --at 0.5,4,8.05          # one sheet, written to inspect.jpg
shotstack inspect edit.json --bars map.json          # a tile at every bar line from `analyze --output json`
shotstack inspect edit.json --at 3 --grid            # one still with a grid labelled in output pixels
shotstack inspect <render-id> --at 1.2 --env stage   # frames of a finished render
shotstack inspect https://…/clip.mp4 --at 0.5,1.8    # frames of a generated or uploaded video

每张图表包含六帧；时间点更多时，会依次写入 inspect-1.jpg、inspect-2.jpg 等文件。超出编辑内容时长的时间点会被跳过，并列在 stderr 中。这些帧是 Studio 的画布。如果之后渲染的结果与图表不一致，请告知用户，并使用 shotstack feedback 报告。

CLI 五条规则

1. 管道传输 → --output json。 默认输出为人类可读格式。以编程方式解析或将输出管道传给另一个命令时，务必传入 --output json。

2. 使用 --watch，不要编写轮询循环。 shotstack render <file> --watch 会一次性提交并轮询；shotstack status <id> --watch 会轮询已有的渲染任务。任务进入终态时，两者都会退出：done（退出码为 0）或 failed（退出码为 1）。不要编写 while true; do ...; sleep 3; done。

3. 根据 shared/agent-core.md 进行创作，然后运行 shotstack validate。 其中的速查表列出了所需的属性名称、枚举值（transition/effect/position/fit）和富文本字段——无需下载架构。随后，shotstack validate <file> 会离线根据实时架构检查 JSON，并在消耗积分前标记同一轨道上的重叠、未加载的字体和非公开 URL。（如需处理边缘情况，完整架构见 https://shotstack.io/docs/api/api.edit.json，指南见 https://shotstack.io/docs/guide/llms-full.txt。）

4. 渲染 v1 之前先查看帧。 运行 shotstack inspect，在每个剪辑点、强调点和文字命中点都指定时间，然后打开图表：文字太小、某个元素始终未出现、场景为空，或字幕只换行出一个词，这些问题都只有查看帧才能发现。在将时间点与生成片段中的事件对齐之前，先检查片段的 URL，确认事件发生的时间。如果 inspect 找不到浏览器，请告知用户此处无法检查帧，并改用 shotstack studio <file> 交接，而不是直接渲染未经检查的内容。

5. 不确定时，通过 shotstack studio <file> 交由人工处理。 不要在反复尝试中浪费渲染积分。生成 JSON → shotstack studio file.json（打开浏览器）→ 人工审查和调整 → 确认无误后再渲染。

必须：创作任何 Edit JSON 之前，先阅读 shared/agent-core.md

Edit JSON 不遵循 CSS 或 Web 约定，尤其是 rich-text 资源的样式字段（html5 资源的 css 才是普通 CSS）。凭训练数据中的经验创作 Edit JSON，会导致渲染无声无息地出错。每次都要先阅读 shared/agent-core.md。最常见的错误转换：

你会写的内容（错误）	API 要求的内容（正确）
alignment	align
align.vertical: "center"	align.vertical: "middle"
font.name	font.family
duration	length
transitions: [...]（数组）	transition: { in, out }（对象）
fit: "cover"（受 CSS 经验影响）	fit: "crop"
tracks[0] 是底层（受 z-index 经验影响）	tracks[0] 是顶层

完整规则集（资源类型、字体、智能字符串片段值、最常见的 5 个错误）见 shared/agent-core.md。

动作效果由你设计。 内置动作效果（transitions、effects、keyframes、rich-text 动画）使用架构中规定的固定选项；html5 可使用任何可定位的动画。references/motion.md 介绍了各层可使用的动画（transitions、effects、keyframes、rich-text 动画、html5）、可用的缓动方式和配方；agent-core.md 的 Motion 部分对此进行了概述。

退出码

代码	含义
0	成功
1	永久错误 — 验证失败、缺少密钥、4xx、渲染 failed
2	暂时性错误 — 5xx、网络错误、超时。可以安全重试。

参考资料

权威来源，按优先级排序：

• shotstack --help 和 shotstack <command> --help — 当前 CLI 标志列表
• shared/agent-core.md — Edit JSON 编写规范（与 MCP 服务共用）
• https://shotstack.io/docs/api/api.edit.json — 渲染 API 的 OpenAPI Schema（可通过机器验证）
• https://shotstack.io/docs/guide/llms-full.txt — 适合大模型阅读的完整 API 文档单文件
• https://github.com/shotstack/oas-api-definition/tree/main/schemas — 原始 OpenAPI YAML，是属性名称和枚举值的权威来源
• https://shotstack.io/docs/guide/ — 交互式 HTML 文档和指南
• https://shotstack.io/docs/api/ — 交互式 HTML API 参考
• https://github.com/shotstack/shotstack-cli — 此技能的代码库，也是 shotstack feedback 提交问题的地方

此技能为复杂内容提供了子参考文档：

• references/onboarding.md — 面向新用户的首次渲染探索访谈：要问什么，以及回答如何对应到第一个 Edit
• references/ingest.md — 上传本地文件（以及获取 URL），以便在 Edit 中使用：上传→渲染工作流、--watch、状态值和支持的类型
• references/timeline.md — 轨道分层、转场、通过音频素材添加背景音乐
• references/positioning.md — 坐标模型、position/offset（画面比例，+y 向上）、片段边界框和 fit、文本大小、变换顺序
• references/caption.md — 各分辨率下的尺寸、默认样式、5 种命名预设、别名模式（素材类型：rich-caption）
• references/svg.md — 必需属性、支持的元素
• references/motion.md — 每个图层上可动的内容（转场、效果、关键帧、富文本动画、html5）、可用的缓动效果、GSAP/CSS 配方，以及通过合并字段使用品牌套件
• references/html5.md — HTML5 素材：字段、预加载的库（GSAP 及其插件、d3、anime、lottie）、浏览器测试框架和 seek 规则、3D、尺寸及实例
• references/html5-effects.md — 创意效果库：html5 片段可实现的所有效果，按常见动效设计名称分类（逐字符文本、描边书写动画、遮罩、混合模式、噪声位移、速度渐变、2.5D 摄像机、粒子），并附单行配方和应避免的做法。设计 html5 片段前请先阅读。
• references/html5-snippets.md — 可复制粘贴的动态图形片段：动感标题、数值揭示、光泽扫过、脉冲式 CTA、胶片颗粒
• references/fonts.md — 内置字体、Google Fonts URL 模式、自定义字体工作流
• references/generation.md — 针对各模型生成 AI 视频、图像、语音和音乐的提示词技巧，以及时间线如何丰富提示词。编写任何 prompt 前请先阅读。
• references/beat-sync.md — 按音乐节拍剪辑和制作动画：先获取曲目，再进行分析，按小节编写每个提示，通过映射驱动 html5，并在小节线检查帧
• references/asset-library.md — 占位视频、图像和音乐
• references/troubleshooting.md — 常见错误及修复方法

如果此技能与 --help 有任何冲突，请以 --help 为准。如果此技能与 llms-full.txt 有任何冲突，请以 llms-full.txt 为准。