mcpField
A
avatar-video

avatar-video

github.com/heygen-comクリエイティブ・メディア526994 回インストール15 週間前に更新
リポジトリ

avatar-video について

avatar-videoは、HeyGen APIでAIアバター動画を作成するスキルです。ライブラリーのアバターや写真のアニメーション化を選び、台本、音声、背景を指定できます。動画の内容や見た目を細かく制御したい制作者向けです。

主な機能

  1. 01HeyGenアバターまたは写真の利用
  2. 02台本、音声、背景の設定
  3. 03アバターと音声の一覧表示
  4. 04生成状況の確認と動画の取得
  5. 05字幕とテキストオーバーレイの設定

活用シーン

  1. 01指定した台本によるアバター動画の作成
  2. 02写真からのアニメーション動画作成
  3. 03動画に使う音声と背景の選択
  4. 04生成状況の確認と完成動画のダウンロード

MCP 対応

動画の状態確認、アカウント動画の一覧表示、削除にはHeyGen MCPツールを利用でき、直接APIでも実行できます。動画生成とアバター・音声の一覧取得には直接APIを使います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/heygen-com/skills --skill avatar-video

インストール後、Claude Code で/avatar-videoを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
assets.md
avatars.md
backgrounds.md
captions.md
dimensions.md
photo-avatars.md
quota.md
remotion-integration.md
scripts.md
templates.md
text-overlays.md
video-generation.md
video-status.md
voices.md
webhooks.md

詳細

アバター動画

POST /v3/videos を使用して、アバター、音声、スクリプト、背景を細かく制御しながら AI アバター動画を作成します。type の識別可能なユニオンによる 2 つの作成モードがあります。

  • "type": "avatar" + avatar_id — ライブラリから HeyGen アバターを使用します
  • "type": "image" + image（AssetInput）— Avatar IV を使って任意の写真をアニメーション化します

認証

すべてのリクエストには X-Api-Key ヘッダーが必要です。HEYGEN_API_KEY 環境変数を設定してください。

curl -X GET "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

ツールの選択

HeyGen MCP ツール（mcp__heygen__*）が利用可能な場合は、直接 HTTP API を呼び出すよりも優先して使用してください。認証とリクエスト形式の処理が自動で行われます。

タスクMCP ツールフォールバック（直接 API）
動画のステータスを確認／URL を取得mcp__heygen__get_videoGET /v3/videos/{video_id}
アカウントの動画一覧を取得mcp__heygen__list_videosGET /v3/videos
動画を削除mcp__heygen__delete_videoDELETE /v3/videos/{video_id}

動画の生成（POST /v3/videos）とアバター／音声の一覧取得は、直接 API を呼び出して行います。以下のリファレンスファイルを参照してください。

デフォルトのワークフロー

  1. アバターのルックを一覧表示する — GET /v3/avatars/looks → ルックを選び、その id（これが avatar_id です）と default_voice_id を控えます。avatars.md を参照してください
  2. 音声を一覧表示する（必要な場合）— GET /v3/voices → アバターの性別／言語に合う音声を選びます。voices.md を参照してください
  3. スクリプトを作成する — 各シーンに 1 つのコンセプトを設定します。scripts.md を参照してください
  4. 動画を生成する — avatar_id、voice_id、script、および各シーンの任意の background を指定して POST /v3/videos を呼び出します。video-generation.md を参照してください
  5. 完了するまでポーリングする — ステータスが completed になるまで GET /v3/videos/{video_id} を呼び出します。video-status.md を参照してください

使い分け：このスキルと Create Video

このスキル＝細かな制御（特定のアバター、正確なスクリプト、カスタム背景）。 create-video＝プロンプトベース（「X についての動画を作って」、残りは AI が処理）。

リファレンスファイル

必要に応じて参照してください。エンドポイントの詳細、リクエスト／レスポンスのスキーマ、コード例（curl、TypeScript、Python）が記載されています。

基本的なワークフロー：

カスタマイズ：

高度な機能：

ベストプラクティス

  1. 生成前にアバターをプレビューする — GET /v3/avatars/looks を使い、preview_image_url をダウンロードして、確定する前にユーザーがアバターを確認できるようにします
  2. アバターのデフォルト音声を使う — 多くのアバターには、自然な結果が得られるよう事前にマッチングされた default_voice_id があります
  3. フォールバック：性別を手動で合わせる — デフォルト音声がない場合は、アバターと音声の性別が一致していることを確認します
  4. 開発にはテストモードを使う — クレジットを消費しないように test: true を設定します（出力にはウォーターマークが付きます）
  5. タイムアウトを長めに設定する — 動画の生成には通常5～15分かかり、さらに時間がかかる場合もあります
  6. 入力を検証する — 生成前にアバター ID と音声 ID が存在することを確認します

コメント

Markdown 対応