how-tos

HeyGen Avatar 6 APIのテキストからアバター:音声ファイルなしでスクリプトからプレゼンター動画

Poyo.ai Team
4 min read
Share:

HeyGen Avatar 6 APIのテキストからアバター:スクリプトから作るプレゼンター動画

HeyGen Avatar 6 APIは、スクリプトだけからプレゼンター動画を作れます。パブリックアバターモードでは、HeyGenの1,248種類のストックルックから1つを指定し、最大1,000文字のtextを送り、102種類のボイスから1つを選ぶと、heygen-avatar-6(またはheygen-avatar-6-turbo)がリップシンクしたMP4を返します。写真も録音も、自分の側でのテキスト読み上げの処理も不要です。このウォークスルーでは、カタログからルックとボイスを選ぶ方法、promptでジェスチャーを指示する方法、フレームの形の選び方、そしてテキストリクエストの費用を説明します。HeyGen Avatar 6モデルページでもルックを閲覧できます。

テキストからアバターへのリクエスト

以下は、テキストを使うパブリックアバターモードのドキュメント記載の本文です。

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "avatar": "Abigail Office Front",
    "text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
    "voice": "Warm Pro Narrator",
    "prompt": "Speak with calm confidence and nod slightly at the end.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}
フィールド必須ルール
avatarはい1,248のルック名のいずれか
textはい(audio_urlの代わり)1〜1,000文字
voiceいいえ102の名前のいずれか。デフォルトはWarm Pro Narrator
promptいいえ最大1,200文字の演出指示
aspect_ratioいいえ16:9(デフォルト)、9:16、1:1、4:5、5:4
resolutionいいえ1080p(デフォルト)または 2K

このモードを選択するのはavatarの存在です。image_urlsやvideo_urlを一緒に送らないでください。1リクエストには1つのモードの入力を使います。POST https://api.poyo.ai/api/generate/submitに送信し、HeyGen Avatar 6 APIガイドと同様に/api/generate/status/{task_id}をポーリングします。

カタログからアバタールックを選ぶ

PoYoはすべての名前をAvatars and VoicesページとJSONカタログで公開しています。カタログには5つのキーがあります。

キー内容
modelsheygen-avatar-6、heygen-avatar-6-turbo(同じ名前が両方で使える)
default_voiceWarm Pro Narrator
avatars1,248のルック名すべて、フラットなリスト
avatars_by_person同じルックを156人ごとにグループ化
voices102のボイス名すべて

各人物には1つ以上のルックがあり、各ルックが個別のavatar値です。Abigailには5つ(Abigail (Upper Body)、Abigail Office Front、Abigail Office Side、Abigail Sofa Front、Abigail Sofa Side)、Annieには54あり、8人はルックが1つだけです。名前はセッティング、服装、カメラアングルを表しているので、通常はプレビューせずに選べます。

欲しいもの名前に含まれる語例
カメラを向くプレゼンターFrontAbigail Office Front、Bryan Suit Front
斜め45度のアングルSideAbigail Office Side
座った、くだけた雰囲気Sofa、Sitting、LoungeAnnie Sofa Sitting Front
役割やセッティングDoctor、Nurse、Yoga、Tech ExpertAnn Doctor Standing、Adriana Nurse Front、Amelia Yoga Front、Bryan Tech Expert

約480の名前にFrontが、約430の名前にSideが含まれています。解説動画のシリーズでは、1人の人物を選んでそのFrontルックに統一すると、動画間でプレゼンターが変わりません。カットアウェイには対応するSideルックを使いましょう。

名前は大文字小文字や余分なスペースに関係なく一致するので、abigail office frontでAbigail Office Frontが選ばれます。PoYoは送信時にavatarをリストと照合するため、タイプミスはタスク失敗ではなく即座の400として返ります。まず自分のコードで検証しましょう。

import requests

catalog = requests.get(
    "https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()

def norm(name: str) -> str:
    return " ".join(name.split()).lower()

AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])

def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
    if norm(avatar) not in AVATARS:
        raise ValueError(f"unknown avatar: {avatar!r}")
    if not 1 <= len(text) <= 1000:
        raise ValueError("text must be 1-1,000 characters")
    if voice is not None and voice not in VOICES:
        raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
    if prompt is not None and len(prompt) > 1200:
        raise ValueError("prompt must be at most 1,200 characters")
    body = {"avatar": AVATARS[norm(avatar)], "text": text,
            "aspect_ratio": aspect_ratio, "resolution": resolution}
    if voice:
        body["voice"] = voice
    if prompt:
        body["prompt"] = prompt
    return {"model": model, "input": body}

ボイスのチェックはあえて完全一致の名前を使っています。理由は次のセクションで説明します。

ボイスを選ぶ

voiceは誰がtextを読み上げるかを決めます。省略するとWarm Pro Narratorになります。102のボイスには、シンプルな名前(Andrew、Ivy、Jessica Anne Bogart)、説明的な名前(Calm Chloe、Professor Dean、Radio Rick、Chill Brian)、名前にスタイルのタグが付いたものがあります。

つまずきやすい点が3つあります。

  • 末尾のスペースが意味を持つことがある。 ドキュメントでは、HopeとHope (末尾にスペース)が別々のボイスであることが明記されています。Archer 、Cassidy 、Adam Stone 、Spuds Oxley 、Andrew Rizz もカタログ上で末尾がスペースです。名前は打ち直さず、JSONからコピーしてください。
  • 一部の名前には絵文字やファイル名のような接尾辞が含まれる。 たとえばCute Chloe - Friendly 😊やBrenda - UGC - 1.mp4です。これらの文字も名前の一部です。リクエスト本文をUTF-8のJSONで送れば、名前はそのまま渡ります。
  • ボイスはアバターに紐づいていない。 102のボイスのどれでも、1,248のルックのどれにでも読み上げさせられます。画面上の人物に合うボイスを選んでください。ローンチ当日のテストでは、Bryan Tech ExpertにAndrewを、Abigail Office FrontにJessica Anne Bogartを組み合わせました。

voiceはtextを送るときだけ適用されます。代わりにaudio_urlを送ると、アバターはあなたの録音を話し、voiceは使われません。

promptでジェスチャーを指示する

promptは、ジェスチャー、表情、姿勢についての最大1,200文字の演出指示を受け付けます。HeyGenのテクニカルレポートはこの手法を「動作をセリフの横に書くだけ。Avatar 6がその瞬間に正確に演じる」と説明しています。その例は「親しみやすい薬剤師。'Hello'でサムズアップ。'the counter on the left'で人差し指で横を指す」です。

この形式に従ったパターン:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Bryan Tech Expert",
    "text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
    "voice": "Andrew",
    "prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}

プロンプトを役立つものにするコツ:

  • 各動作を合わせたいtext内の正確な言葉を引用し、きっかけを明確にする。
  • まず役割や雰囲気を1つ書き(「Friendly product expert」)、その後にきっかけを書く。
  • 具体的なきっかけがないときはpromptを省略する。HeyGenのAvatar 6ローンチページによれば、モデルは「ジェスチャー、感情、表情をスクリプトに合わせる」ことを自動で行います。

配置先に合わせてアスペクト比を選ぶ

aspect_ratioはパブリックアバターモードにのみ存在します。写真モードと参照動画モードは入力の形を維持します。

配置先aspect_ratio
Webサイト、YouTube、LMSのレッスン16:9(デフォルト)
ショート、リール、TikTok、ストーリーズ9:16
正方形のフィード投稿、アプリ内カード1:1
縦長のフィード投稿4:5
横長のフィード投稿5:4

resolutionは別の設定で、どの比率でも1080pまたは2Kです。2Kは1秒あたりの料金が高いので、下書きは1080pでレンダリングしましょう。

動画の長さと費用

テキストの場合、動画の長さはアバターが最大1,000文字を読み上げるのにかかる時間になります。課金は完成動画の長さを整数秒に切り上げたものです。クレジットは送信時に予約され、タスク完了時に実際の秒数で精算されます。

2026年11月19日の本番APIでのローンチ当日テスト(16:9、1080p):

モデルアバター / ボイススクリプト出力現行料金での費用所要時間
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27語10.16秒110クレジット($0.55)約2.4分
heygen-avatar-6Bryan Tech Expert / Andrew21語6.88秒140クレジット($0.70)約2分

この2回の実行では、1秒あたり約2.7語と3.1語でした。おおまかな予算の目安には使えますが、ペースはボイスやスクリプトによって変わるので保証ではありません。1秒あたりの料金は、Turboが1080pで10クレジット($0.05)、2Kで18($0.09)、Avatar 6が20クレジット($0.10)または29($0.145)です。詳しくはHeyGen Avatar 6 API料金をご覧ください。

テキストタスクは実行中に予約を確保するため、一度に多数を送信すると、HTTP 200で本文code 402(insufficient_credits_error)が返ることがあります。私たちのテストでは、3つ目のリクエストが「this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks.」というメッセージで拒否されました。テキストジョブをキューに入れるか、実行中の予約分をカバーできる残高を維持してください。試行錯誤の間はTurboを使いましょう。切り替えのタイミングはAvatar 6 vs Turboの比較で説明しています。

よくある質問

HeyGen Avatar 6 APIはテキストをトーキングアバター動画に変換できますか?

はい。パブリックアバターモードで、avatar、最大1,000文字のtext、任意でvoiceを送ります。音声ファイルは不要です。

HeyGen Avatar 6 APIのアバターとボイスの一覧はどこにありますか?

PoYoドキュメントのAvatars and Voicesページと、avatars、avatars_by_person、voicesのキーを持つダウンロード可能なJSONカタログにあります。

HeyGen Avatar 6 APIのデフォルトのボイスは何ですか?

Warm Pro Narratorで、voiceを省略したときに使われます。

ストックアバターの代わりに自分の写真とテキストを使えますか?

できません。textはパブリックアバターモードでのみ使えます。自分の写真には、image_urlsとaudio_urlを使う写真モードを使ってください。必要であれば、先にTTSモデルで音声を生成します。

HeyGen Avatar 6のテキストからアバターはどのアスペクト比に対応していますか?

16:9、9:16、1:1、4:5、5:4で、1080pまたは2Kです。

HeyGen Avatar 6 APIのテキストリクエストはどのように課金されますか?

完成動画の長さを整数秒に切り上げ、モデルの秒単価を掛けて課金されます。クレジットは送信時に予約され、タスク終了時に精算されます。

Share: