vivideo

Vivideo ツールチェーン

Vivideo API の開発者とエージェントをつなぐ統合レイヤーです。共有クライアント、MCP サーバー、CLI、Skills を提供します。エージェントは主要なユーザーであり、後回しにされる存在ではありません。

すべては公開 API（信頼できる唯一の情報源）の上に構築されています。バックエンドのビジネスロジックは一切複製せず、ツールチェーンが追加するのはクライアント側の使いやすさとガードレールのみです。

vivideo-toolchain/            npm workspaces monorepo (TypeScript)
├── packages/core   @vivideo/core   one typed API client + guardrails (shared)
├── packages/mcp    @vivideo/mcp    MCP server (stdio) — 13 agent tools
├── packages/cli    @vivideo/cli    `vivideo` CLI — humans, scripts, CI, agents
├── skills/                          reusable agent Skills (SKILL.md)
└── docs/                            installation, configuration, workflows

アーキテクチャ

packages/core/openapi.yaml から導出された、1 つのクライアントと 1 組の型を使用します。MCP サーバーと CLI はどちらも @vivideo/core を呼び出します。各リクエスト／レスポンスの表現は1 つだけなので、ツール、CLI、ドキュメント、OpenAPI の一貫性が保たれます。

@vivideo/core が追加するのはクライアント側の機能のみであり、ビジネスロジックは追加しません。

ガードレール	内容
レート制限	トークンバケット方式でリクエストレートを制限します（デフォルトは 8/s）。クライアントがリクエストの洪水を引き起こすことはありません。
同時実行数の上限	セマフォで処理中のリクエスト数を制限します（デフォルトは 4）。
回数を制限した再試行	retryable な失敗のみを、フルジッター方式のバックオフと上限付きの試行回数で再試行します。
Retry-After を尊重	429 の場合、再試行の前に API が指定した時間だけ待機します。
冪等性	動画作成リクエストにはすべて Idempotency-Key を送信します。再試行時も同じキーを再利用するため、二重請求は発生しません。
タイムアウト	リクエストごとに AbortController のタイムアウトを設定します（デフォルトは 30s）。
安全な待機	waitForVideo は API が推奨する間隔でポーリングし、確実にタイムアウトします。while(true) は使用しません。
シークレットの秘匿化	API キー／署名シークレットは、すべてのログ、エラー、出力から除去されます。

これらは API 独自の認証、レート制限、冪等性、クレジット確認、プレミアム機能の制限、所有権、エラーモデルを補完するものであり、それらを迂回することはありません。

クイックスタート

# from the repo (until packages are published to npm)
npm install
npm run build

# authenticate (stored 0600 in ~/.vivideo/config.json), or use VIVIDEO_API_KEY
export VIVIDEO_API_KEY="vv_live_..."   # from https://app.vivideo.ai/account/api-keys

# CLI
node packages/cli/dist/index.js account
node packages/cli/dist/index.js create auto --prompt "A 20s product teaser" --wait

# MCP server (stdio) — point an MCP client at this command
node packages/mcp/dist/index.js

公開後は、npm i -g @vivideo/cli を実行すると vivideo を利用でき、サーバーには npx @vivideo/mcp を実行します。

ドキュメント

• MCP サーバー — インストール、設定、クライアントへの接続、ツールリファレンス
• CLI — インストール、認証、コマンドリファレンス、JSON と非対話型の使用方法、終了コード
• Skills — インストールと使用方法
• ワークフロー — 人間とエージェント向け、エンドツーエンド
• セキュリティ、レート制限、冪等性、クレジットとプレミアム機能、トラブルシューティング

認証とセキュリティ

• キーは次の順に読み込まれます。明示的なオプション → VIVIDEO_API_KEY 環境変数 → ~/.vivideo/config.json（所有者のみ読み書き可能な 0600 で書き込み）。
• キーが表示されることはありません。すべての出力でシークレットが秘匿化され、configure はキーをエコーせずに保存します。
• キーはアカウント単位のシークレットです。サーバー側で保管し、漏えい時に個別に失効できるよう、統合ごとに 1 つ使用してください。

含まれない機能（対応範囲について）

• キャンセル — 公開 API にキャンセル用エンドポイントがないため、キャンセル用ツール／コマンドは提供しません。失敗したレンダリングや停止したレンダリングは、API によって自動返金されます。
• エージェント／チャットモード — 公開 API では提供されていないため、ツールチェーンにも含まれません。
• npm への公開、DNS の設定、デプロイはここでは行いません。これらは外部で実施する手順です（docs/mcp.md の最後のセクションを参照）。

開発

npm run build       # build all three packages (tsc -b)
npm run typecheck   # type-check the whole workspace
npm test            # vitest

Node ≥ 18.17 が必要です。