![]()
このHeyGen Avatar 6 APIガイドでは、APIキーの取得からPoYoでトーキング動画を完成させるまでを説明します。モデルIDheygen-avatar-6(またはheygen-avatar-6-turbo)を指定したJSONリクエストを1つ送信し、返されたタスクIDを保存して、MP4が準備できるまでポーリングします。以下のリクエスト本文はすべてPoYoドキュメントの形式に従っています。先に入力を確認したい場合は、HeyGen Avatar 6モデルページにPlaygroundがあります。
始める前に
poyo.ai/dashboard/api-keyでキーを作成し、POYO_API_KEYとしてexportします。キーはサーバー側に置いてください。- すべての入力ファイルを、公開されていて直接ダウンロードできるHTTPまたはHTTPSのURLでホストします。PoYoがメディアを自ら取得するため、リクエスト内でのアップロードは受け付けません。
- ティアを選びます。両方のIDは同じフィールドを受け付けます。Turboは1080pで1秒あたり10クレジット($0.05)、Avatar 6は20クレジット($0.10)です。Avatar 6 vs Turboを参照してください。
cURLで送る最初のHeyGen Avatar 6 APIリクエスト
最も手早い最初のリクエストにはメディアがまったく不要です。HeyGenのパブリックアバターがテキストを読み上げます。
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'
成功したレスポンスには"code": 200とdata.task_idが含まれ、statusはnot_startedです。これはキューに入ったジョブであり、動画ではありません。ポーリングします。
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
ステータスはnot_started、running、finished、failedです。finishedになると、MP4はfile_typeがvideoのdata.files[]に入り、data.credits_amountに課金額が表示されます。failedの場合はdata.error_messageを読んでください。
上限付きのPythonポーリングループ
2026年11月19日のローンチ当日のテストでは、短いテキストクリップは送信から結果まで約2〜2.4分かかりました。このループは5秒ごとにポーリングし(ステータスのドキュメントでは2〜5秒を推奨)、15分で停止します。タイムアウト時に再送信は決してしません。2回目の送信は2つ目の課金対象タスクになるからです。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
return body["data"]
def generate(payload, timeout_s=900):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
print("task", task_id, flush=True)
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
return videos[0], task.get("credits_amount")
raise TimeoutError("still running; poll this task again later: " + task_id)
url, credits = generate({
"model": "heygen-avatar-6",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p",
},
})
print(url, credits)
本番環境では、ポーリングの代わりにトップレベルのcallback_urlを追加してください。タスクがfinishedまたはfailedになると、PoYoは同じタスクオブジェクト(code / dataのラッパーなし)を、X-Webhook-SignatureにHMAC-SHA256の署名を付けてPOSTします。署名のルールはWebhookドキュメントにあります。
HeyGen Avatar 6 APIの3つの入力モード
モードの切り替えスイッチはありません。avatarがあればパブリックアバターモード、なければvideo_urlがあれば参照動画モード、どちらもなければ写真モードで実行されます。1リクエストには1つのモードの入力を使ってください。
テキストを使うパブリックアバターモード
上で示したとおりです。avatarは1,248の公開ルックのいずれか、textは最大1,000文字、voiceは102種類のボイスのいずれか(デフォルトはWarm Pro Narrator)です。カタログからルックとボイスを選ぶ方法はテキストからアバターへのウォークスルーで説明しています。
自分の音声を使うパブリックアバターモード
textとvoiceをaudio_urlに置き換えます。aspect_ratioは引き続き有効です。
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
写真モード
実在の人物の写真1枚と音声です。動画は写真のアスペクト比を維持するので、送信前に写真を目的のフレームにトリミングしてください。callback_urlはinputの中ではなく、modelと同じ階層に置きます。
{
"model": "heygen-avatar-6",
"callback_url": "https://your-domain.com/callback",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p"
}
}
参照動画モード
アニメやイラストのキャラクター向けです。video_urlはキャラクターのクリップで、image_urlsで同じキャラクターの静止画を1枚任意で追加できます。出力はクリップのアスペクト比を維持します。
{
"model": "heygen-avatar-6-turbo",
"input": {
"video_url": "https://example.com/cartoon-character.mp4",
"image_urls": ["https://example.com/cartoon-character.png"],
"audio_url": "https://example.com/speech.mp3",
"resolution": "2K"
}
}
HeyGen Avatar 6 APIのフィールド検証ルール
送信前に自分のコードでこれらを確認してください。ドキュメントに記載された制限です。
| フィールド | モード | ルール |
|---|---|---|
model | すべて | heygen-avatar-6 または heygen-avatar-6-turbo |
image_urls | 写真(必須)、参照動画(任意) | URLちょうど1つの配列 |
video_url | 参照動画 | 2秒以上、最大50 MB |
avatar | パブリックアバター | 掲載されている1,248の名前のいずれか |
audio_url | 写真、参照動画、またはパブリックアバターでtextの代わり | 2〜60秒、最大15 MB |
text | パブリックアバター | 1〜1,000文字 |
voice | textを使うパブリックアバター | 102の名前のいずれか |
prompt | すべて | 最大1,200文字 |
aspect_ratio | パブリックアバター | 16:9、9:16、1:1、4:5、5:4 |
resolution | すべて | 1080p(デフォルト)または 2K |
アバター名とボイス名は大文字小文字や余分なスペースに関係なく一致しますが、ドキュメントに記載された例外が1つあります。HopeとHope (末尾にスペース)は別々のボイスです。入力スキーマは追加フィールドを許可しないため、HeyGen自身のAPIにあるmotion_expressivenessやmotion_promptなどのHeyGenネイティブのオプションは送らないでください。PoYoでは、動きの指示はpromptに書きます。
対処すべきエラー
レスポンス本文のcodeを必ず読んでください。一部の検証エラーはHTTP 200で"code": 400として返るため、HTTPステータスだけを確認するのでは不十分です。
本文のcode | error.type | 対処 |
|---|---|---|
| 400 | validation_error など | 入力を修正する:2〜60秒の範囲外の音声、不明なアバター名、別モードのフィールド。そのまま再試行しない |
| 401 | authentication_error | Authorization: Bearerヘッダーを確認する |
| 402 | insufficient_credits_error | チャージするか、実行中のテキストタスクの精算を待つ(後述) |
| 429 | rate_limit_error | 間隔を空けて再試行する |
| 500 / 502 / 503 | internal_error、upstream_error、service_error | 指数バックオフで再試行する |
音声の長さ、参照動画の長さ、アバター名は送信時にチェックされるため、これらのミスは数分後のタスク失敗ではなく、即座の400として表面化します。
402には、HeyGen特有のひねりがあります。ローンチ当日のテストで、2つのテキストタスクを送信した後、3つ目のリクエスト(Turbo、2K、22語)がHTTP 200、本文code 402、タイプinsufficient_credits_errorで返ってきました。メッセージは「this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks.」でした。テキストタスクは実行中にクレジットを確保するため、最終的な料金が残高に収まる場合でも、テキストの連続送信で402になることがあります。テキストジョブをキューに入れるか、エラーメッセージにすでに両方の数値が含まれているので、それをユーザーに表示してください。
最初のHeyGen Avatar 6 API請求の計算方法
PoYoは出力1秒単位で課金し、整数秒に切り上げます(1クレジット = $0.005)。
| モデル | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10クレジット($0.05)/ 秒 | 18クレジット($0.09)/ 秒 |
heygen-avatar-6 | 20クレジット($0.10)/ 秒 | 29クレジット($0.145)/ 秒 |
audio_urlの場合(全モード):料金は音声の長さを切り上げたもので、送信時に引き落とされます。1080pのAvatar 6で12.3秒のクリップなら13 × 20 = 260クレジット($1.30)です。textの場合:送信時にクレジットが予約され、タスク終了時に完成動画の長さで精算されます。私たちのテストでは、Turboで27語のスクリプトは10.16秒になって11秒分の課金となり、現行料金では110クレジット(11秒 × 10、$0.55)です。Avatar 6で21語のスクリプトは6.88秒になって7秒分の課金となり、現行料金では140クレジット(7秒 × 20、$0.70)です。
照合すべき数値は、完了したタスクのdata.credits_amountです。その他の例はHeyGen Avatar 6 API料金にあります。
よくある質問
PythonからHeyGen Avatar 6 APIを呼び出すには?
requestsでhttps://api.poyo.ai/api/generate/submitにJSONをPOSTし、上記のループのように期限を設けて/api/generate/status/{task_id}をポーリングします。どのHTTPクライアントでも動作し、SDKは必須ではありません。
HeyGen Avatar 6 APIにコールバックはありますか?
はい。リクエストのトップレベルにcallback_urlを追加してください。タスクが完了または失敗すると、PoYoがタスクデータをPOSTします。
HeyGen Avatar 6 APIのリクエストがHTTP 200を返したのにタスクがないのはなぜですか?
本文を読んでください。codeが200以外であれば、HTTP 200でもリクエストは失敗しています。理由はerror.messageに書かれています。
HeyGen Avatar 6 APIにファイルを直接アップロードできますか?
できません。image_urls、video_url、audio_urlは、PoYoがダウンロードする公開HTTPまたはHTTPSのURLを受け付けます。
HeyGen Avatar 6 APIの結果はどのくらい保持されますか?
生成された動画は作成から3日間アクセスできます。MP4を自社のストレージにダウンロードしてください。