![]()
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つのキーがあります。
| キー | 内容 |
|---|---|
models | heygen-avatar-6、heygen-avatar-6-turbo(同じ名前が両方で使える) |
default_voice | Warm Pro Narrator |
avatars | 1,248のルック名すべて、フラットなリスト |
avatars_by_person | 同じルックを156人ごとにグループ化 |
voices | 102のボイス名すべて |
各人物には1つ以上のルックがあり、各ルックが個別のavatar値です。Abigailには5つ(Abigail (Upper Body)、Abigail Office Front、Abigail Office Side、Abigail Sofa Front、Abigail Sofa Side)、Annieには54あり、8人はルックが1つだけです。名前はセッティング、服装、カメラアングルを表しているので、通常はプレビューせずに選べます。
| 欲しいもの | 名前に含まれる語 | 例 |
|---|---|---|
| カメラを向くプレゼンター | Front | Abigail Office Front、Bryan Suit Front |
| 斜め45度のアングル | Side | Abigail Office Side |
| 座った、くだけた雰囲気 | Sofa、Sitting、Lounge | Annie Sofa Sitting Front |
| 役割やセッティング | Doctor、Nurse、Yoga、Tech Expert | Ann 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-turbo | Abigail Office Front / Jessica Anne Bogart | 27語 | 10.16秒 | 110クレジット($0.55) | 約2.4分 |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21語 | 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のテキストリクエストはどのように課金されますか?
完成動画の長さを整数秒に切り上げ、モデルの秒単価を掛けて課金されます。クレジットは送信時に予約され、タスク終了時に精算されます。