shotstack

Shotstack CLI

このスキルはターミナルベースの AI エージェント（Claude Code、Cursor、Codex CLI、Gemini CLI など）で読み込まれます。ここでの操作はすべてシェルコマンドです。埋め込み UI、iframe、インラインキャンバス、MCP ツールのインターフェースはなく、ターミナルから shotstack を実行するだけです。人間に引き継ぐには、shotstack studio <file> を実行します。ユーザーの既定のブラウザーで shotstack.studio の URL が開きます。ユーザーには、ターミナル内の UI ではなく、ブラウザーのタブで Render をクリックするよう伝えてください。

セッションごとに一度、バージョンを確認する

このスキルのバージョンは 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、レンダリング、または動画のフレームを描画し、1 枚のコンタクトシートにまとめます。レンダリングせずに自分の作業を確認できます。template list|get|create|update|delete は、アカウントに保存されたテンプレートを読み書きします。list は保存済みテンプレート（ID + 名前）を表示します。get <id> は保存済みテンプレートの Edit JSON（例：ユーザーが Studio でデザインしたもの）を取得し、レンダリングやリミックスに使えるようにします。create <file> --name <name> は Edit を新しいテンプレートとして保存します。update <id> <file> はテンプレートを上書きします。delete <id> はテンプレートを削除します。models はプロンプトで生成するアセットに使える生成モデルと、このキーで各モデルを利用できるかどうかを一覧表示します。models <id> はモデルが受け付けるオプションを表示します。generate <model> "<prompt>" は単独でアセットを 1 つ生成し、その 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)

最も低コストで反復できる方法は stage ではなく studio です。 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 を設定する前に必ず確認してください。スキーマにない値は拒否されます。

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>" を実行すると、編集をレンダリングせずにアセットを 1 つ生成し、その 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 はクリップの長さを秒で指定します。指定した長さに合わせて生成するモデルでは、モデル独自の長さオプションの代わりに使用されます。

ステージ環境と 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 日間有効で、その旨が標準エラー出力に表示されます。ユーザーが有効期間の長いリンクを希望する場合は、shotstack login を提案してください。タイムアウト、429、または 5xx が発生した場合は 1 回再試行し、その後インラインの base64url 形式に切り替えて、原因を標準エラー出力に表示します。共有 API が編集内容を拒否した場合（1 MB を超える、timeline または output がない、無効なキーなど）、コマンドは理由を示して終了コード 1 で終了します。原因を修正するか、--no-shorten を使用してください。

複雑な内容には、デフォルトで studio を使用してください。複数シーン、複数トラック、または関心のあるユーザーが確認するクリエイティブな内容が該当します。クライアント側でプレビューでき、費用もかからず、問題なければユーザー自身が Render を実行できます。render を直接使うのは、単一ショットやシンプルな編集、自動化されたパイプラインの場合、または「そのままレンダリングして」と指示された場合に限ります。

inspect でフレームを確認する（キー不要、クレジット不要）

shotstack inspect はヘッドレス Chrome で編集データを Studio に読み込み、指定した時刻のフレームを、それぞれの時刻をラベルとして付けた1枚の画像に書き出します。画像を開いて確認してください。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

1枚のシートには6フレームが表示されます。時刻を追加すると、inspect-1.jpg、inspect-2.jpg のように書き出されます。編集データの終了時刻を過ぎた時刻はスキップされ、stderr に一覧表示されます。フレームは Studio のキャンバスです。後のレンダリング結果がシートと異なる場合は、ユーザーに伝え、shotstack feedback で報告してください。

CLI の5つのルール

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 を実行し、シートを開いてください。テキストが小さすぎる、要素が表示されない、シーンが空である、キャプションが1語だけで改行されるといった問題は、フレームを確認しないとわかりません。生成されたクリップ内のイベントに合わせてタイミングを設定する前に、クリップの 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] は最上層

完全なルール一式（アセットの種類、フォント、smart-string のクリップ値、特に多い5つの間違い）は shared/agent-core.md に記載されています。

モーションは自由に設計できます。 組み込みのモーション（トランジション、エフェクト、キーフレーム、リッチテキストアニメーション）はスキーマで指定された固定のオプションを使います。html5 ではシーク可能なアニメーションを自由に使用できます。references/motion.md では、各レイヤーでアニメーションできる要素（トランジション、エフェクト、キーフレーム、リッチテキストアニメーション、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 スキーマ（機械による検証が可能）
• https://shotstack.io/docs/guide/llms-full.txt — LLM 向けに最適化された、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 — トラックの重ね合わせ、トランジション、オーディオアセットを使った BGM
• 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）、ブラウザハーネスとシークのルール、3D、サイズ設定、実例
• references/html5-effects.md — クリエイティブな表現の一覧：html5 クリップで実現できるあらゆるエフェクトを、一般的なモーションデザイン名別に紹介します（文字単位のテキスト、線の描画、マット、ブレンドモード、ノイズ変位、速度ランプ、2.5D カメラ、パーティクル）。1 行のレシピと避けるべきことも記載しています。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 を優先してください。