![]()
Dieser Leitfaden zur HeyGen Avatar 6 API führt Sie vom API-Schlüssel bis zum fertigen sprechenden Video auf PoYo. Sie senden eine JSON-Anfrage mit der Modell-ID heygen-avatar-6 (oder heygen-avatar-6-turbo), speichern die zurückgegebene Task-ID und pollen, bis das MP4 fertig ist. Jeder Request-Body unten folgt der Struktur aus der PoYo-Dokumentation; die HeyGen Avatar 6 Modellseite hat einen Playground, falls Sie die Eingaben zuerst sehen möchten.
Bevor Sie beginnen
- Erstellen Sie einen Schlüssel unter
poyo.ai/dashboard/api-keyund exportieren Sie ihn alsPOYO_API_KEY. Bewahren Sie ihn auf Ihrem Server auf. - Stellen Sie jede Eingabedatei unter einer öffentlichen, direkt herunterladbaren HTTP- oder HTTPS-URL bereit. PoYo lädt die Medien selbst herunter; Uploads in der Anfrage werden nicht akzeptiert.
- Wählen Sie eine Stufe. Beide IDs nehmen dieselben Felder. Turbo kostet 10 Credits ($0.05) pro Sekunde in 1080p; Avatar 6 kostet 20 Credits ($0.10). Siehe Avatar 6 vs Turbo.
Ihre erste Anfrage an die HeyGen Avatar 6 API mit cURL
Die schnellste erste Anfrage braucht überhaupt keine Medien: Ein öffentlicher HeyGen-Avatar liest Ihren Text vor.
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"
}
}'
Eine erfolgreiche Antwort enthält "code": 200 und data.task_id, wobei status auf not_started steht. Das ist ein Job in der Warteschlange, noch kein Video. Pollen Sie ihn:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Die Status sind not_started, running, finished und failed. Bei finished liegt das MP4 in data.files[] mit file_type video, und data.credits_amount zeigt, was berechnet wurde. Bei failed lesen Sie data.error_message.
Eine begrenzte Polling-Schleife in Python
In unseren Tests am Launch-Tag, dem 19. November 2026, brauchten kurze Textclips etwa 2 bis 2.4 Minuten vom Absenden bis zum Ergebnis. Diese Schleife pollt alle 5 Sekunden (die Status-Dokumentation empfiehlt 2–5 s), stoppt nach 15 Minuten und sendet bei einem Timeout nie erneut ab, denn ein zweites Absenden ist eine zweite kostenpflichtige Aufgabe.
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)
Für die Produktion fügen Sie statt des Pollings eine callback_url auf oberster Ebene hinzu. PoYo sendet dasselbe Task-Objekt (ohne die code- / data-Hülle) per POST, wenn die Aufgabe finished oder failed ist, signiert mit HMAC-SHA256 in X-Webhook-Signature; die Webhook-Dokumentation beschreibt die Signaturregel.
Die drei Eingabemodi der HeyGen Avatar 6 API
Es gibt keinen Modusschalter. avatar wählt den Public-Avatar-Modus; andernfalls wählt video_url den Referenzvideo-Modus; andernfalls läuft die Anfrage im Fotomodus. Verwenden Sie pro Anfrage die Eingaben genau eines Modus.
Public-Avatar-Modus mit Text
Siehe oben. avatar ist einer von 1,248 öffentlichen Looks, text umfasst bis zu 1,000 Zeichen, und voice ist eine von 102 Stimmen (Standard Warm Pro Narrator). Die Text-to-Avatar-Anleitung zeigt, wie Sie Looks und Stimmen aus dem Katalog auswählen.
Public-Avatar-Modus mit Ihrem Audio
Ersetzen Sie text und voice durch audio_url. aspect_ratio gilt weiterhin:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Fotomodus
Ein Foto einer realen Person plus Sprache. Das Video behält das Seitenverhältnis des Fotos, schneiden Sie das Foto also vor dem Senden auf den gewünschten Bildausschnitt zu. callback_url steht neben model, nicht innerhalb von input:
{
"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"
}
}
Referenzvideo-Modus
Für animierte oder gezeichnete Figuren. video_url ist ein Clip der Figur; image_urls fügt optional ein Standbild derselben Figur hinzu. Die Ausgabe behält das Seitenverhältnis des Clips:
{
"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"
}
}
Prüfregeln für die Felder der HeyGen Avatar 6 API
Prüfen Sie diese Punkte vor dem Absenden in Ihrem eigenen Code; es sind die dokumentierten Limits.
| Feld | Modus | Regel |
|---|---|---|
model | Alle | heygen-avatar-6 oder heygen-avatar-6-turbo |
image_urls | Foto (Pflicht), Referenzvideo (optional) | Array mit genau einer URL |
video_url | Referenzvideo | Mindestens 2 s, bis 50 MB |
avatar | Öffentlicher Avatar | Einer der 1,248 aufgeführten Namen |
audio_url | Foto, Referenzvideo; oder öffentlicher Avatar statt text | 2–60 s, bis 15 MB |
text | Öffentlicher Avatar | 1–1,000 Zeichen |
voice | Öffentlicher Avatar mit text | Einer von 102 Namen |
prompt | Alle | Bis 1,200 Zeichen |
aspect_ratio | Öffentlicher Avatar | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Alle | 1080p (Standard) oder 2K |
Avatar- und Stimmennamen werden unabhängig von Groß-/Kleinschreibung und zusätzlichen Leerzeichen erkannt, mit einer dokumentierten Ausnahme: Hope und Hope (mit Leerzeichen am Ende) sind zwei verschiedene Stimmen. Das Eingabeschema erlaubt keine zusätzlichen Felder, senden Sie also keine HeyGen-nativen Optionen wie motion_expressiveness oder motion_prompt aus HeyGens eigener API; auf PoYo gehören Bewegungsanweisungen in prompt.
Fehler, die Sie behandeln sollten
Lesen Sie immer code im Antwort-Body. Manche Validierungsfehler kommen als HTTP 200 mit "code": 400 zurück, daher reicht es nicht, nur den HTTP-Status zu prüfen.
Body-code | error.type | Was zu tun ist |
|---|---|---|
| 400 | validation_error und andere | Eingabe korrigieren: Audio außerhalb von 2–60 s, unbekannter Avatar-Name, ein Feld aus einem anderen Modus. Nicht unverändert wiederholen |
| 401 | authentication_error | Den Authorization: Bearer-Header prüfen |
| 402 | insufficient_credits_error | Aufladen oder warten, bis laufende Textaufgaben abgerechnet sind (siehe unten) |
| 429 | rate_limit_error | Zurückhalten und erneut versuchen |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Mit exponentiellem Backoff erneut versuchen |
Audiolänge, Länge des Referenzvideos und der Avatar-Name werden beim Absenden geprüft, sodass diese Fehler als sofortiger 400 auftauchen statt als fehlgeschlagene Aufgabe Minuten später.
Der Fall 402 hat bei HeyGen eine Besonderheit. In unserem Test am Launch-Tag kam, nachdem zwei Textaufgaben abgesendet worden waren, eine dritte Anfrage (Turbo, 2K, 22 Wörter) als HTTP 200 mit Body-code 402 und Typ insufficient_credits_error zurück: „Diese Anfrage benötigt mindestens 252 Credits, und 344 Credits sind bereits durch Ihre unfertigen HeyGen Avatar 6 Textaufgaben reserviert.“ Textaufgaben halten Credits, solange sie laufen, sodass eine Welle von Textanfragen einen 402 auslösen kann, obwohl die endgültigen Beträge passen würden. Stellen Sie Textjobs in eine Warteschlange oder zeigen Sie die Fehlermeldung dem Nutzer an, denn sie nennt bereits beide Zahlen.
Wie die erste Rechnung der HeyGen Avatar 6 API berechnet wird
PoYo rechnet pro Sekunde Ausgabe ab, aufgerundet auf ganze Sekunden (1 Credit = $0.005):
| Modell | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 Credits ($0.05) / s | 18 Credits ($0.09) / s |
heygen-avatar-6 | 20 Credits ($0.10) / s | 29 Credits ($0.145) / s |
- Mit
audio_url(alle Modi): Abgerechnet wird die Audiolänge, aufgerundet, abgebucht beim Absenden. Ein Clip von 12.3 Sekunden auf Avatar 6 in 1080p kostet 13 × 20 = 260 Credits ($1.30). - Mit
text: Credits werden beim Absenden reserviert und am Ende der Aufgabe auf die Länge des fertigen Videos abgerechnet. In unseren Tests lieferte ein Skript mit 27 Wörtern auf Turbo 10.16 s und wurde mit 11 Sekunden abgerechnet, zu aktuellen Preisen 110 Credits (11 s × 10, $0.55); ein Skript mit 21 Wörtern auf Avatar 6 lieferte 6.88 s und wurde mit 7 Sekunden abgerechnet, zu aktuellen Preisen 140 Credits (7 s × 20, $0.70).
data.credits_amount in der fertigen Aufgabe ist der Wert, mit dem Sie abgleichen. Weitere Beispiele finden Sie unter Preise der HeyGen Avatar 6 API.
Häufig gestellte Fragen
Wie rufe ich die HeyGen Avatar 6 API aus Python auf?
Senden Sie JSON per POST mit requests an https://api.poyo.ai/api/generate/submit und pollen Sie dann /api/generate/status/{task_id} mit einer Frist, wie in der Schleife oben. Jeder HTTP-Client funktioniert; ein SDK ist nicht erforderlich.
Gibt es einen Callback für die HeyGen Avatar 6 API?
Ja. Fügen Sie callback_url auf oberster Ebene der Anfrage hinzu. PoYo sendet die Aufgabendaten per POST, wenn sie fertig ist oder fehlschlägt.
Warum hat meine Anfrage an die HeyGen Avatar 6 API HTTP 200 geliefert, aber keine Aufgabe?
Lesen Sie den Body. Ein code ungleich 200 bedeutet, dass die Anfrage fehlgeschlagen ist, auch bei HTTP 200; error.message nennt den Grund.
Kann ich eine Datei direkt an die HeyGen Avatar 6 API hochladen?
Nein. image_urls, video_url und audio_url nehmen öffentliche HTTP- oder HTTPS-URLs, die PoYo herunterlädt.
Wie lange werden Ergebnisse der HeyGen Avatar 6 API aufbewahrt?
Generierte Videos sind nach der Erstellung 3 Tage lang abrufbar. Laden Sie das MP4 in Ihren eigenen Speicher herunter.