![]()
Ten przewodnik po HeyGen Avatar 6 API prowadzi od klucza API do gotowego mówiącego wideo w PoYo. Wysyłasz jedno żądanie JSON z ID modelu heygen-avatar-6 (lub heygen-avatar-6-turbo), zachowujesz zwrócone ID zadania i odpytujesz status, aż MP4 będzie gotowy. Każda treść żądania poniżej ma kształt zgodny z dokumentacją PoYo; strona modelu HeyGen Avatar 6 ma Playground, jeśli chcesz najpierw zobaczyć dane wejściowe.
Zanim zaczniesz
- Utwórz klucz na
poyo.ai/dashboard/api-keyi wyeksportuj go jakoPOYO_API_KEY. Trzymaj go na serwerze. - Umieść każdy plik wejściowy pod publicznym, bezpośrednio pobieralnym adresem HTTP lub HTTPS. PoYo samo pobiera multimedia; nie przyjmuje plików przesłanych w żądaniu.
- Wybierz wariant. Oba ID przyjmują te same pola. Turbo kosztuje 10 kredytów ($0.05) za sekundę w 1080p; Avatar 6 kosztuje 20 kredytów ($0.10). Zobacz Avatar 6 vs Turbo.
Pierwsze żądanie do HeyGen Avatar 6 API w cURL
Najszybsze pierwsze żądanie w ogóle nie potrzebuje multimediów: publiczny awatar HeyGen czyta Twój tekst.
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"
}
}'
Udana odpowiedź zawiera "code": 200 i data.task_id, a status ma wartość not_started. To zadanie w kolejce, a nie wideo. Odpytuj je:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Statusy to not_started, running, finished i failed. Przy finished plik MP4 jest w data.files[] z file_type video, a data.credits_amount pokazuje pobraną kwotę. Przy failed odczytaj data.error_message.
Ograniczona pętla odpytywania w Pythonie
W naszych testach w dniu premiery, 19 listopada 2026 roku, krótkie klipy z tekstu zajmowały od około 2 do 2.4 minuty od wysłania do wyniku. Ta pętla odpytuje co 5 sekund (dokumentacja statusu zaleca 2–5 s), kończy po 15 minutach i nigdy nie wysyła żądania ponownie po przekroczeniu czasu, bo drugie wysłanie to drugie płatne zadanie.
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)
Na produkcji zamiast odpytywania dodaj callback_url na najwyższym poziomie żądania. PoYo wysyła ten sam obiekt zadania (bez opakowania code / data), gdy zadanie ma status finished lub failed, podpisany HMAC-SHA256 w X-Webhook-Signature; dokumentacja webhooków opisuje zasadę podpisu.
Trzy tryby wejścia HeyGen Avatar 6 API
Nie ma przełącznika trybu. avatar wybiera tryb publicznego awatara; w przeciwnym razie video_url wybiera tryb wideo referencyjnego; w przeciwnym razie żądanie działa w trybie zdjęcia. W jednym żądaniu używaj danych wejściowych jednego trybu.
Tryb publicznego awatara z tekstem
Pokazany powyżej. avatar to jeden z 1,248 publicznych wyglądów, text ma do 1,000 znaków, a voice to jeden ze 102 głosów (domyślnie Warm Pro Narrator). Poradnik text-to-avatar pokazuje, jak wybierać wyglądy i głosy z katalogu.
Tryb publicznego awatara z własnym audio
Zastąp text i voice polem audio_url. aspect_ratio nadal obowiązuje:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Tryb zdjęcia
Jedno zdjęcie prawdziwej osoby plus mowa. Wideo zachowuje proporcje zdjęcia, więc przed wysłaniem przytnij zdjęcie do docelowego kadru. callback_url znajduje się obok model, a nie wewnątrz 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"
}
}
Tryb wideo referencyjnego
Dla animowanych lub rysowanych postaci. video_url to klip z postacią; image_urls opcjonalnie dodaje jedną klatkę tej samej postaci. Wynik zachowuje proporcje klipu:
{
"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"
}
}
Zasady walidacji pól HeyGen Avatar 6 API
Sprawdzaj je we własnym kodzie przed wysłaniem; to udokumentowane limity.
| Pole | Tryb | Zasada |
|---|---|---|
model | Wszystkie | heygen-avatar-6 lub heygen-avatar-6-turbo |
image_urls | Zdjęcie (wymagane), wideo referencyjne (opcjonalne) | Tablica z dokładnie jednym URL |
video_url | Wideo referencyjne | Co najmniej 2 s, do 50 MB |
avatar | Publiczny awatar | Jedna z 1,248 wymienionych nazw |
audio_url | Zdjęcie, wideo referencyjne; lub publiczny awatar zamiast text | 2–60 s, do 15 MB |
text | Publiczny awatar | 1–1,000 znaków |
voice | Publiczny awatar z text | Jedna ze 102 nazw |
prompt | Wszystkie | Do 1,200 znaków |
aspect_ratio | Publiczny awatar | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Wszystkie | 1080p (domyślnie) lub 2K |
Nazwy awatarów i głosów są dopasowywane bez względu na wielkość liter i dodatkowe spacje, z jednym udokumentowanym wyjątkiem: Hope i Hope (ze spacją na końcu) to dwa różne głosy. Schemat wejścia nie dopuszcza dodatkowych pól, więc nie wysyłaj natywnych opcji HeyGen, takich jak motion_expressiveness czy motion_prompt z własnego API HeyGen; w PoYo wskazówki dotyczące ruchu trafiają do prompt.
Błędy, które warto obsłużyć
Zawsze odczytuj code w treści odpowiedzi. Niektóre błędy walidacji wracają jako HTTP 200 z "code": 400, więc samo sprawdzenie statusu HTTP nie wystarczy.
code w treści | error.type | Co zrobić |
|---|---|---|
| 400 | validation_error i inne | Popraw dane wejściowe: audio poza zakresem 2–60 s, nieznana nazwa awatara, pole z innego trybu. Nie ponawiaj bez zmian |
| 401 | authentication_error | Sprawdź nagłówek Authorization: Bearer |
| 402 | insufficient_credits_error | Doładuj konto albo poczekaj, aż trwające zadania tekstowe zostaną rozliczone (poniżej) |
| 429 | rate_limit_error | Odczekaj i ponów |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Ponów z wykładniczym wycofaniem (backoff) |
Długość audio, długość wideo referencyjnego i nazwa awatara są sprawdzane przy wysłaniu, więc te pomyłki pojawiają się od razu jako 400, a nie jako nieudane zadanie kilka minut później.
Przypadek 402 ma specyficzny dla HeyGen haczyk. W naszym teście w dniu premiery, po wysłaniu dwóch zadań tekstowych, trzecie żądanie (Turbo, 2K, 22 słowa) wróciło jako HTTP 200 z code 402 w treści i typem insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Zadania tekstowe blokują kredyty w trakcie działania, więc seria żądań tekstowych może trafić na 402, nawet jeśli końcowe opłaty by się zmieściły. Kolejkuj zadania tekstowe albo pokaż komunikat błędu użytkownikowi, bo podaje on już obie liczby.
Jak obliczany jest pierwszy rachunek za HeyGen Avatar 6 API
PoYo nalicza opłaty za sekundę wyjścia, zaokrągloną w górę do pełnych sekund (1 kredyt = $0.005):
| Model | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 kredytów ($0.05) / s | 18 kredytów ($0.09) / s |
heygen-avatar-6 | 20 kredytów ($0.10) / s | 29 kredytów ($0.145) / s |
- Z
audio_url(wszystkie tryby): opłata to długość audio zaokrąglona w górę, pobierana przy wysłaniu. Klip 12.3-sekundowy na Avatar 6 w 1080p to 13 × 20 = 260 kredytów ($1.30). - Z
text: kredyty są rezerwowane przy wysłaniu i rozliczane według długości gotowego wideo po zakończeniu zadania. W naszych testach skrypt z 27 słów na Turbo dał 10.16 s, rozliczonych jako 11 sekund, co według obecnych cen daje 110 kredytów (11 s × 10, $0.55); skrypt z 21 słów na Avatar 6 dał 6.88 s, rozliczonych jako 7 sekund, co według obecnych cen daje 140 kredytów (7 s × 20, $0.70).
data.credits_amount w zakończonym zadaniu to liczba do uzgodnienia. Więcej przykładów znajdziesz w artykule Cennik HeyGen Avatar 6 API.
Najczęściej zadawane pytania
Jak wywołać HeyGen Avatar 6 API z Pythona?
Wyślij JSON metodą POST na https://api.poyo.ai/api/generate/submit za pomocą requests, a potem odpytuj /api/generate/status/{task_id} z limitem czasu, jak w pętli powyżej. Działa dowolny klient HTTP; SDK nie jest wymagane.
Czy HeyGen Avatar 6 API ma callback?
Tak. Dodaj callback_url na najwyższym poziomie żądania. PoYo wyśle dane zadania, gdy się zakończy lub nie powiedzie.
Dlaczego moje żądanie do HeyGen Avatar 6 API zwróciło HTTP 200, ale bez zadania?
Odczytaj treść odpowiedzi. code inny niż 200 oznacza, że żądanie się nie powiodło, nawet przy HTTP 200; error.message podaje przyczynę.
Czy mogę przesłać plik bezpośrednio do HeyGen Avatar 6 API?
Nie. image_urls, video_url i audio_url przyjmują publiczne adresy HTTP lub HTTPS, które PoYo pobiera.
Jak długo przechowywane są wyniki HeyGen Avatar 6 API?
Wygenerowane wideo jest dostępne przez 3 dni od utworzenia. Pobierz MP4 do własnego magazynu.