0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

HeyGen Avatar V入門 — 15秒動画からリアルAIアバターをAPIで生成する

0
Last updated at Posted at 2026-04-15

はじめに

2026年4月8日、HeyGenはAvatar V（Avatar 5）をリリースしました。わずか15秒のウェブカメラ映像から、140言語以上・最大30分に対応するフォトリアルなAIアバターを生成できる新世代モデルです。

前世代の Avatar IV では2〜3分以上の動画が必要でしたが、Avatar VはわずかなRecordingで高精度なデジタルツインを作成します。公式ブログによれば、Face Similarity スコア0.840を達成し、業界ベンチマークで他モデルを大きく引き離しています。

この記事で学べること

  • Avatar V の技術仕様と前世代との差分
  • REST API を使ったアバター動画生成の実装方法（Python）
  • ユースケース別の活用パターン

対象読者

  • AIアバターを自社サービスに組み込みたいエンジニア
  • 動画コンテンツ生成を自動化したい開発者
  • HeyGen APIをはじめて触れるPython開発者

前提環境

TL;DR

  • Avatar VはFace Similarity 0.840 のフォトリアルなAIアバターを15秒動画から生成
  • 140言語以上対応、音素レベルのリップシンクで自然な口の動き
  • APIはPOSTリクエストで動画生成 → ポーリングで結果取得のシンプルな設計
  • エンタープライズ用途の最大30分の長尺動画も安定動作

Avatar V とは

前世代との比較

項目 Avatar IV Avatar V
入力動画長 2分以上 15秒
Face Similarity スコア — 0.840
対応言語数 — 140言語以上
最大動画長 5分 最大30分
マルチアングル生成 なし あり（広角・中距離・クローズアップ）

出典: HeyGen Avatar V Research Page

技術的な仕組み

Avatar V研究ページによると、モデルは以下の構造で動作します。

Sparse Reference Self-Attention（SRSA）アーキテクチャ

入力映像はPatch（トークン化されたフレーム断片）として処理されます。テキスト・音声とともにTransformerブロックへ入力される際、SRSAにより元の15秒クリップを「参照メモリ」として常に参照し続ける設計になっています。

一般的な動画生成モデルが圧縮された特徴量から生成するのに対し、Avatar Vは元映像を直接参照することで：

  • 長尺動画でもアイデンティティが劣化しない
  • 微細な表情（眉の動き、瞬き）を再現可能
  • 複数アングルを単一入力から生成可能

という特性を実現しています。

環境セットアップ

pip install requests python-dotenv

.env ファイルを作成します:

HEYGEN_API_KEY=your_api_key_here

API の基本フロー

HeyGen APIはシンプルな非同期設計です。動画生成はすぐには完了しないため、以下のフローで実装します。

1. POST /v2/video/generate  → video_id を取得
2. GET  /v1/video_status.get?video_id={id}  → ステータスをポーリング
3. ステータスが "completed" になったら video_url を取得

実装: Avatar V 動画の生成

ステップ1: アバターIDとボイスIDの取得

まず利用可能なアバター一覧を取得します。

import requests
import os
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("HEYGEN_API_KEY")
BASE_URL = "https://api.heygen.com"
HEADERS = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json"
}

def list_avatars() -> list[dict]:
    """利用可能なアバター一覧を取得する"""
    url = f"{BASE_URL}/v2/avatars"
    response = requests.get(url, headers=HEADERS)
    response.raise_for_status()
    data = response.json()
    return data.get("data", {}).get("avatars", [])

avatars = list_avatars()
for avatar in avatars[:5]:
    print(f"ID: {avatar['avatar_id']}, Name: {avatar['avatar_name']}")

ボイス一覧も同様に取得できます。

def list_voices(language: str = "Japanese") -> list[dict]:
    """指定言語のボイス一覧を取得する"""
    url = f"{BASE_URL}/v2/voices"
    params = {"language": language}
    response = requests.get(url, headers=HEADERS, params=params)
    response.raise_for_status()
    data = response.json()
    return data.get("data", {}).get("voices", [])

voices = list_voices("Japanese")
for voice in voices[:3]:
    print(f"ID: {voice['voice_id']}, Name: {voice['display_name']}")

ステップ2: 動画生成リクエスト

import time

def generate_avatar_video(
    avatar_id: str,
    voice_id: str,
    script: str,
    title: str = "My Avatar Video"
) -> str:
    """
    Avatar V でアバター動画を生成する。
    返り値: video_id
    """
    url = f"{BASE_URL}/v2/video/generate"
    payload = {
        "video_inputs": [
            {
                "character": {
                    "type": "avatar",
                    "avatar_id": avatar_id,
                    "avatar_style": "normal"
                },
                "voice": {
                    "type": "text",
                    "voice_id": voice_id,
                    "input_text": script
                },
                "background": {
                    "type": "color",
                    "value": "#ffffff"
                }
            }
        ],
        "title": title,
        "dimension": {
            "width": 1280,
            "height": 720
        }
    }

    response = requests.post(url, json=payload, headers=HEADERS)
    response.raise_for_status()
    data = response.json()
    return data["data"]["video_id"]

ステップ3: ポーリングで完了を待機

def wait_for_video(video_id: str, timeout: int = 300) -> str:
    """
    動画の生成完了を待ち、動画URLを返す。
    timeout: 最大待機秒数（デフォルト300秒）
    """
    url = f"{BASE_URL}/v1/video_status.get"
    params = {"video_id": video_id}
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(url, headers=HEADERS, params=params)
        response.raise_for_status()
        data = response.json()["data"]

        status = data["status"]
        print(f"Status: {status}")

        if status == "completed":
            return data["video_url"]
        elif status == "failed":
            raise RuntimeError(f"動画生成失敗: {data.get('error', 'Unknown error')}")

        time.sleep(10)

    raise TimeoutError(f"動画生成がタイムアウトしました（{timeout}秒）")

ステップ4: 統合実行

def main():
    # 設定（実際の値に置き換えてください）
    AVATAR_ID = "your_avatar_id"
    VOICE_ID = "your_voice_id"
    SCRIPT = """
    HeyGen Avatar V の解説動画へようこそ。
    このモデルは15秒の映像から、フォトリアルなAIアバターを生成します。
    140言語以上に対応し、最大30分の長尺動画にも対応しています。
    """

    print("動画生成を開始します...")
    video_id = generate_avatar_video(
        avatar_id=AVATAR_ID,
        voice_id=VOICE_ID,
        script=SCRIPT,
        title="HeyGen Avatar V Demo"
    )
    print(f"Video ID: {video_id}")

    print("完了を待機中...")
    video_url = wait_for_video(video_id)
    print(f"完了！動画URL: {video_url}")

if __name__ == "__main__":
    main()

デジタルツイン（自分のアバター）の作成

Avatar Vの真価は、自分自身のアバターを作成することにあります。APIを通じた作成フローは以下のとおりです。

1. 動画素材のアップロード

def upload_training_video(file_path: str) -> str:
    """
    アバター学習用動画をアップロードする。
    返り値: asset_id
    """
    url = f"{BASE_URL}/v1/asset"

    with open(file_path, "rb") as f:
        files = {"file": (os.path.basename(file_path), f, "video/mp4")}
        # ファイルアップロードは Content-Type を指定しない
        upload_headers = {"X-Api-Key": API_KEY}
        response = requests.post(url, files=files, headers=upload_headers)

    response.raise_for_status()
    return response.json()["data"]["id"]

2. トレーニングジョブの作成

def create_avatar_training(asset_id: str, avatar_name: str) -> str:
    """
    Avatar V のトレーニングジョブを作成する。
    返り値: avatar_id
    """
    url = f"{BASE_URL}/v2/avatar_group"
    payload = {
        "name": avatar_name,
        "video_ids": [asset_id],
        "avatar_type": "avatar_v"  # ※2026年4月時点で公式ドキュメント未確認。実際の値は公式APIリファレンスを参照
    }

    response = requests.post(url, json=payload, headers=HEADERS)
    response.raise_for_status()
    data = response.json()
    return data["data"]["avatar_group_id"]

注意: デジタルツインの学習には通常数分〜数十分かかります。/v2/avatar_group/{id} エンドポイントでステータスを確認してください。

活用パターン

パターン1: 多言語コンテンツの大量生成

Avatar Vは140言語以上に対応しているため、1つの動画スクリプトを多言語展開する自動化が可能です。

SCRIPTS = {
    "Japanese": "日本語のスクリプトです",
    "English": "This is an English script",
    "Spanish": "Este es un guión en español",
}

VOICE_MAP = {
    "Japanese": "jp_voice_id",
    "English": "en_voice_id",
    "Spanish": "es_voice_id",
}

for lang, script in SCRIPTS.items():
    video_id = generate_avatar_video(
        avatar_id=AVATAR_ID,
        voice_id=VOICE_MAP[lang],
        script=script,
        title=f"Product Demo - {lang}"
    )
    print(f"{lang}: {video_id}")

パターン2: 動的テキストからの動画バッチ生成

データベースのコンテンツや CSV から動画を自動生成するパターンです。

import csv

def batch_generate_from_csv(csv_path: str) -> list[dict]:
    """CSVのスクリプトリストから動画を一括生成する"""
    results = []
    with open(csv_path, encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for row in reader:
            video_id = generate_avatar_video(
                avatar_id=row["avatar_id"],
                voice_id=row["voice_id"],
                script=row["script"],
                title=row["title"]
            )
            results.append({"title": row["title"], "video_id": video_id})
    return results

パターン3: AI エージェントとの統合

Claude などのLLMと組み合わせ、テキスト → アバター動画を自動生成するパイプラインを構築できます。

import anthropic

def generate_script_and_video(topic: str, avatar_id: str, voice_id: str) -> str:
    """
    Claude でスクリプトを生成し、Avatar V で動画化する
    """
    client = anthropic.Anthropic()

    # Claude でスクリプト生成
    message = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=500,
        messages=[{
            "role": "user",
            "content": f"以下のトピックについて、60秒の動画説明スクリプトを書いてください: {topic}"
        }]
    )
    script = message.content[0].text

    # Avatar V で動画生成
    video_id = generate_avatar_video(
        avatar_id=avatar_id,
        voice_id=voice_id,
        script=script,
        title=f"AI Generated: {topic}"
    )

    return wait_for_video(video_id)

API 料金

HeyGen API 料金ページによると、API はクレジット制です。

コンテンツタイプ 料金
アバター動画生成 $5 から（従量課金）
デジタルツイン学習 プランにより異なる
ボイス生成 クレジット消費

詳細はプランによって異なるため、公式のAPI料金ページを参照してください。

注意点

レート制限

公式ドキュメントによると、APIには同時リクエスト数と1時間あたりのリクエスト数の制限があります。大量バッチ処理を行う場合は、リクエスト間に適切な待機を入れてください。

倫理的な利用

HeyGenの利用規約により、他者の肖像権を侵害する用途や、フェイク動画の作成は禁止されています。デジタルツインは本人の同意のもとで作成してください。

長尺動画の分割処理

最大30分の動画生成に対応していますが、APIタイムアウトを考慮し、長尺コンテンツは複数セグメントに分割して生成することが推奨されます。

まとめ

項目 内容
リリース日 2026年4月8日
入力要件 15秒のウェブカメラ映像
Face Similarity 0.840（業界トップクラス）
言語対応 140言語以上（音素レベルリップシンク）
最大動画長 最大30分
アーキテクチャ Sparse Reference Self-Attention Transformer

Avatar Vは、動画コンテンツ生成の民主化を一段と進めるモデルです。15秒という低コストな入力要件と、140言語以上のカバレッジにより、多言語展開・Eラーニング・バーチャルプレゼンターなど幅広い開発シナリオで活用できます。

HeyGen APIはシンプルなREST設計で、Pythonから扱いやすい作りになっています。まずは無料クレジットでデジタルツインを作成し、活用イメージを掴んでみてください。

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?