「AIアバターが喋る動画を作りたいけど、毎回HeyGenのWeb画面を開いてスクリプトを貼って…という手作業が地味に面倒」——この作業は、HeyGen公式が配布しているAI Agent Skillsを使えばClaude Codeの中で完結する。リサーチからスクリプト作成、動画生成までを1つのプロンプトで自動化できる、公式が用意した連携方法を実装コード付きで解説する。
📌 この記事でわかること
- HeyGen公式のAI Agent Skillsとは何か、何ができるか
- インストールから認証（MCP／CLI）までの具体的な手順
- 「AIニュースをリサーチして動画5本を自動生成する」実例
- Web版サブスクとAPI従量課金、コスト構造の違い
- よくあるつまずきポイントと注意点
1. HeyGen公式Agent Skillsとは何か
HeyGenは自社のGitHubでheygen-com/skillsという公式リポジトリを公開しており、Claude Code・Cursor・Codex・OpenClawなど主要なAIコーディングエージェントに対応したスキルセットを提供している。これはHeyGenのv3 Video Agent APIをベースにした、アバター作成と動画生成のための公式連携だ。
提供されているスキルは主に2つ。
| スキル名 | 役割 |
|---|---|
| heygen-avatar | 自分やエージェント自身のアバターを作成する |
| heygen-video | 台本・アバターをもとに動画を生成する（v3 Video Agentパイプライン） |
2. 導入手順
2-1 インストール（エージェントに指示するだけ）
特別な環境構築は不要で、Claude Codeに以下の指示文を貼り付けるだけでエージェント自身がインストール作業を行う。
Claude Codeに貼り付けるインストール指示
and follow it. Ask me for any API keys you need.
これだけで、Claude Codeがリポジトリを正しいパスにクローンし、HeyGenのAPIキーを質問し、最適な通信方式を選び、動作確認まで完了させてくれる。
2-2 認証——MCP（OAuth）とCLI（APIキー）の2方式
認証には2つのルートがあり、ここがコスト構造にも直結する重要な分岐点だ。
| 方式 | 認証方法 | 課金の対象 |
|---|---|---|
| MCP経由 | OAuthでHeyGenアカウントにサインイン | Web版のサブスクリプション（プラン内のクレジット） |
| CLI（APIキー）経由 | HEYGEN_API_KEY環境変数、またはheygen auth login |
API従量課金（APIバランスを消費） |
export HEYGEN_API_KEY=”your_api_key_here”
# または
heygen auth login
3. 実例：AIニュースを自動でリサーチし、動画を量産する
公式ブログで紹介されている代表的な使い方が、Web検索とHeyGenの動画生成を組み合わせた自動ワークフローだ。以下のようなプロンプトをClaude Codeに渡すだけで、リサーチから動画生成までが自動的に進む。
Claude Codeに渡すプロンプト例
興味深いものを5件見つけて。それぞれ見出し・2文の要約・出典URLをまとめて。
2. GENERATE VIDEOS: 5件それぞれについて、HeyGenのskillsとvideo agentを使って
短い動画を作って。スクリプト作成と動画生成はHeyGen側に任せる。
3. SAVE OUTPUT: news_videos.json というログファイルに、5件の見出し・出典URL・
完成した動画URLを保存して。
今すぐ開始して、各ステップの進捗を報告して。
このプロンプト1つで、Claude Codeが最新ニュースを調べ、5本分の台本を書き、それぞれをHeyGenに渡して動画化し、結果をログファイルに記録するまでを自動的に実行する。作業時間の目安は5本で約10分、人間はエディタを一度も開かない。
4. 主なCLIコマンド
| コマンド | 用途 |
|---|---|
| heygen video-agent create | v3 Video Agentで動画を生成する（推奨コマンド） |
| heygen avatar list | 利用可能なアバター一覧を取得 |
| heygen voice list | 利用可能な音声一覧を取得 |
POST /v1/video.generate等）を使おうとする問題が指摘されている。必ずMCPかCLI経由でv3のVideo Agentを使うこと。生のv1/v2 URLを直接叩く実装は避けるべきとされている。5. 動画生成の精度を上げるコツ
- avatar_idを指定する：プロンプトでアバターの外見を説明するより、あらかじめ用意したavatar_idを指定した方が動画の尺の精度が上がるとされている（プロンプトのみの説明に比べて誤差が少ないという報告がある）
- 台本はシーンごとにラベル付けして渡す：台本全体をシーン単位で構造化してプロンプトに渡すと、Video Agent側でペース配分の精度が上がる
- Dry-runモードを活用する：「dry run」「preview」と伝えると、実際にAPIを呼ばずにプレビューを生成できる。本番実行前の確認に使うとクレジットの無駄打ちを防げる
6. よくあるつまずきポイント
| 症状 | 原因 | 対処法 |
|---|---|---|
| APIコールが返ってこない | タイムアウト設定なし。3分以内に応答がない場合は異常 | スキル側のタイムアウト挙動を確認し、リトライまたは中断する |
| 古いエンドポイントでエラーになる | エージェントが学習データ由来の古いv1/v2 APIを使おうとしている | v3のVideo Agent（MCPまたはCLI経由）を明示的に使うよう指示する |
| 想定より課金が発生した | CLI（APIキー）経由でAPI従量課金になっていた | Web版のサブスクリプション内で収めたい場合はMCP（OAuth）経由に切り替える |
| 並列実行で失敗が増える | 同時に大量のサブエージェントを走らせている | 公式スキルは同時実行数を2〜4程度に抑える設計を推奨している |
まとめ
HeyGen×Claude Codeの連携は、HeyGen自身が公式に配布・保守しているスキルであるため、他の非公式連携に比べて安定性が高い。まずはMCP（OAuth）経由でWeb版のプラン内に収まる形で試し、自動化の範囲を広げたくなったらCLI・API経由への移行を検討する、という順番が現実的だ。
よくある質問
Q. Cursor・Codexでも同じように使えますか？
A. 使える。公式スキルはClaude Code・OpenClaw・Codex・Cursorなど複数のAIコーディングエージェントに対応している。インストール手順は各エージェントへの指示文を変えるだけで基本的に同じ流れになる。
Q. プログラミング未経験でも使えますか？
A. インストール自体はエージェントへの指示文をコピー＆ペーストするだけで完結する。API キーの取得だけは事前にHeyGenアカウントで行っておく必要がある。
Q. 料金体系はどうなっていますか？
A. MCP（OAuth）経由ならWeb版のプランに含まれるクレジットの範囲で利用でき、CLI（APIキー）経由だとAPI従量課金になる。HeyGen自体の料金プランについてはHeyGenとは？使い方・料金・クレジットの隠れコストを解説で詳しく解説している。
Q. 生成した動画は商用利用できますか？
A. HeyGenアカウント側のプラン・利用規約が適用される。商用利用の可否は契約プランによって異なるため、事前にHeyGen公式の最新情報を確認してほしい。
本記事の情報は2026年7月時点のものです。HeyGenのAgent Skills・APIの仕様は予告なく変更される場合があります。実装前に公式GitHubリポジトリ（heygen-com/skills）および公式ドキュメントで最新の仕様をご確認ください。
