heygen-avatar-v と hiapi の API でスクリプトを口播ショート動画に変換する

ショート動画の口播コンテンツ——創業者の近況アップデート、製品デモ、UGC 風の広告口播——は通常、出演者の手配、マイクの準備、そしてさらにもう一度の編集を意味します。hiapi 上の heygen-avatar-v はこれらすべてを 1 回の API 呼び出しに圧縮します：スクリプトまたは音声ファイルを送信するだけで、自然なアイドリング動作と字幕トラックを備えたリップシンク済みのバーチャル形象動画が返り、ショート動画フィードにそのまま投入できます。本記事では実際の /v1/tasks ワークフロー、実際に生成された動画クリップ、パイプラインを構築する前に知っておくべき制約、そして hiapi の /api/pricing からリアルタイムに取得した価格を順に説明します。バーチャル形象自体のプロンプトレベルのスタイル技法をお探しなら、heygen-avatar-v prompt recipes で扱っています——本記事はこのモデルを再利用可能なショート動画パイプラインに組み込む方法を解説します。

heygen-avatar-v が実際に出力するもの

heygen-avatar-v はデジタルヒューマン動画モデルであり、Sora/Kling 的な意味でのテキストto動画生成器ではありません——テキストスクリプトまたはアップロードした音声ファイルでプリセットの HeyGen バーチャル形象を駆動し、バーチャル形象の口元が音声とリップシンクし、微妙で持続的な動き（まばたき、わずかな頭の動き、肩の揺れ）を伴う動画を返すため、静止した肖像画のようには見えません。この「アイドリング時でも動いている」挙動こそが、使えるショート動画クリップと一目で偽物とわかる喋る写真との分かれ目です。

モデルは 2 種類の入力で駆動され、両者は排他的です——どちらか一方を送信します：

• prompt——テキストスクリプト。hiapi の TTS が読み上げ、リップシンクを駆動します
• audio_url——事前収録した音声トラック（自分のナレーション、クローン音声など何でも）への公開 URL。これがリップシンクを駆動します

duration フィールドはありません。クリップの長さはスクリプトや音声が再生される時間に完全に依存します——40 語の一行は 200 語の一行よりも短いクリップを生成します。これはコスト計画において重要で、後述します。

オプションフィールドでスタイルを整えます：avatar（HeyGen プリセットライブラリから選択）、voice（prompt とのみ併用、audio_url と併用時は無視）、aspect_ratio（9:16 は Reels/TikTok/Shorts 向け、16:9、1:1）、resolution、background（単色またはシーン——ただし後述の落とし穴を参照）、caption（字幕トラックを生成）、output_format（mp4 または webm。後者は透明背景付きで、自分のシーンに合成しやすい）。

実際のクリップ：スクリプトを入力し、字幕付きバーチャル形象動画を出力

以下は実際の heygen-avatar-v 出力です——バーチャル形象が一行のスクリプトを読み上げ、フレーズ間に目に見えるアイドリング動作があり、同期した字幕トラックが付いています：

何が起きていないかに注目してください：バーチャル形象は文と文の間で固まらず、字幕は音声に追従しており、後付けで貼られたものではありません。この組み合わせ——継続的な動きとタイミング同期した字幕——こそが、エディタで静止したバーチャル形象画像にナレーションを付けるのではなく、このモデルを選ぶ理由のすべてです。

落とし穴：初版パイプラインを噛む 2 つの問題

caption は字幕の付属ファイルを返すのであって、ハード字幕ではありません。 caption: true を設定すると、動画出力とは別に同期した .srt ファイルが返ります——テキストを動画フレームに焼き込むわけではありません。画面上に字幕テキストを表示したい場合（ほとんどのショート動画プラットフォームの見た目）は、この .srt ファイルを別途使って焼き込み処理を行う必要があります（ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4、またはお使いのプラットフォームのネイティブ字幕インポート機能）。API の「字幕」はデータとして扱い、レンダリング済みの映像と考えないでください。

background はイラスト風バーチャル形象にのみ有効で、実写風には無効です。 HeyGen のバーチャル形象ライブラリは写真級の実写バーチャル形象とイラスト/アニメ風バーチャル形象が混在しています。background パラメータはイラスト風バーチャル形象の背後のシーンを正常に置き換えられますが、実写風バーチャル形象は何を渡しても元の収録背景を保持します——モデルはそれを切り抜きません。パイプラインがすべてのバーチャル形象が背景の上書きを受け付けると仮定しているなら、使用する具体的な avatar ID をまずテストし、期待通りに合成されるか確認してください。自分の背景上に置きたい実写風バーチャル形象には、output_format: webm（透明）が確実な方法です。

コスト：呼び出し回数ではなく出力秒数で課金

hiapi のリアルタイム /api/pricing によれば、heygen-avatar-v は出力秒あたり $0.15 で課金されます——解像度やアスペクト比に関係なく一律料金です。時間入力がないため、実際のコストはスクリプトや音声が再生される時間に依存します：

スクリプト長（約）	出力時間	コスト
短いフック文	約 5 秒	$0.75
ショート動画 1 ビート分	約 10 秒	$1.50
複数文のセールストーク	約 20 秒	$3.00
フル 30 秒の広告口播	約 30 秒	$4.50

コストは事前に設定するパラメータではなく音声の長さに応じて変動するため、実用的な方法はタスクを送信する前にスクリプトの時間を計ることです（読み上げてみる、または TTS 長さ推定器で実行する）。クリップのレンダリングが終わってから請求額に気づくのでは遅すぎます。

パイプライン：送信、ポーリング、期限切れ前にダウンロード

heygen-avatar-v は hiapi の非同期 /v1/tasks エンドポイントで動作します——プラットフォーム上の他のすべてのタスクベースモデルと同様、「作成してからポーリング」する形です。このワークフロー特有の詳細：タスクは handling と success の間に archiving フェーズを経ます。このときプラットフォームが動画と字幕付属ファイルの仕上げを行っているため、ポーリングループで archiving を終了状態として扱わないでください。

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

大規模に使用する際に省略できない 2 つの運用上の注意：

• すぐにダウンロードすること。 hiapi のすべてのタスク出力と同様、返される URL には expireAt があり、長期リンクには適していません——タスクが成功したらすぐにバイト（動画と .srt）を自分のストレージに取得してください。
• 「スキーマを確認する」ために最小フィールドだけのペイロードを送らないこと。 厳密には prompt または audio_url のみが必須で、他のフィールドは暗黙にデフォルト値が使われるため、{"prompt": "test"} だけのペイロードは 400 を返しません——実際の課金対象レンダリングをディスパッチしてしまいます。フィールド名を検証するには、ドキュメントと照合するか、故意に無効な値を渡して 4xx レスポンスを得る方法を使い、実際のエンドポイントに対してフィールドを省略しないでください。

FAQ

hiapi の TTS の代わりに自分の声を使えますか？ はい——prompt ではなく audio_url を渡し、録音した音声の公開 URL を指定すれば、バーチャル形象はテキストから音声を合成するのではなく、その音声トラックに合わせてリップシンクします。

caption オプションは字幕を動画に焼き込みますか？ いいえ。caption: true は出力動画の音声に同期した別の .srt ファイルを返します。画面上に字幕テキストを表示したい場合は、後処理ステップとして自分で焼き込んでください。

クリップの長さを制御できますか？ 直接的にはできません——duration パラメータはありません。出力の長さはスクリプトの長さ（prompt 使用時）または音声ファイルの長さ（audio_url 使用時）で決まります。

指定した背景が表示されないのはなぜですか？ background は HeyGen ライブラリのイラスト/アニメ風バーチャル形象にのみ有効です。実写・写真級バーチャル形象は元の収録背景を保持します。その場合は output_format: webm で透明出力を得て、自分で合成してください。

どの解像度とアスペクト比に対応していますか？ 最大 4K まで対応し、9:16、16:9、1:1 のアスペクト比オプションがあります——縦型ショート動画フィードから横長・正方形の配信までカバーします。

要点

hiapi 上でのショート動画バーチャル形象パイプライン構築は、推測ではなくいくつかの具体的な事実に集約されます：コストは出力秒あたり $0.15（つまり送信前にスクリプトの時間を計るべきで、送信後では遅い）、字幕出力は自分で焼き込む必要のある .srt 付属ファイル、背景置換はイラスト風バーチャル形象にのみ有効、ポーリングループは archiving を handling と同様に非終了状態として扱う必要があります。予算をハードコードする前に、hiapi の料金ページで現在の数値を確認し、完全なフィールドリファレンスはモデルページを参照してください。始める準備ができたら、ダッシュボードから API キーを取得し、短いスクリプトから始めてください——5 秒の出力でバーチャル形象、アスペクト比、字幕処理が正常に動作することを確認でき、その後で一括処理に拡大できます。