how-tos

HeyGen Avatar 6 APIガイド:cURLとPythonで最初のトーキング動画を作る

Poyo.ai Team
4 min read
Share:

HeyGen Avatar 6 APIガイド:cURLとPythonで最初のトーキング動画

この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文字
voicetextを使うパブリックアバター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ステータスだけを確認するのでは不十分です。

本文のcodeerror.type対処
400validation_error など入力を修正する:2〜60秒の範囲外の音声、不明なアバター名、別モードのフィールド。そのまま再試行しない
401authentication_errorAuthorization: Bearerヘッダーを確認する
402insufficient_credits_errorチャージするか、実行中のテキストタスクの精算を待つ(後述)
429rate_limit_error間隔を空けて再試行する
500 / 502 / 503internal_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)。

モデル1080p2K
heygen-avatar-6-turbo10クレジット($0.05)/ 秒18クレジット($0.09)/ 秒
heygen-avatar-620クレジット($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を自社のストレージにダウンロードしてください。

Share: