how-tos

Przewodnik po HeyGen Avatar 6 API: pierwsze mówiące wideo w cURL i Pythonie

Poyo.ai Team
8 min read
Share:

Przewodnik po HeyGen Avatar 6 API: pierwsze mówiące wideo w cURL i Pythonie

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-key i wyeksportuj go jako POYO_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.

PoleTrybZasada
modelWszystkieheygen-avatar-6 lub heygen-avatar-6-turbo
image_urlsZdjęcie (wymagane), wideo referencyjne (opcjonalne)Tablica z dokładnie jednym URL
video_urlWideo referencyjneCo najmniej 2 s, do 50 MB
avatarPubliczny awatarJedna z 1,248 wymienionych nazw
audio_urlZdjęcie, wideo referencyjne; lub publiczny awatar zamiast text2–60 s, do 15 MB
textPubliczny awatar1–1,000 znaków
voicePubliczny awatar z textJedna ze 102 nazw
promptWszystkieDo 1,200 znaków
aspect_ratioPubliczny awatar16:9, 9:16, 1:1, 4:5, 5:4
resolutionWszystkie1080p (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ścierror.typeCo zrobić
400validation_error i innePopraw dane wejściowe: audio poza zakresem 2–60 s, nieznana nazwa awatara, pole z innego trybu. Nie ponawiaj bez zmian
401authentication_errorSprawdź nagłówek Authorization: Bearer
402insufficient_credits_errorDoładuj konto albo poczekaj, aż trwające zadania tekstowe zostaną rozliczone (poniżej)
429rate_limit_errorOdczekaj i ponów
500 / 502 / 503internal_error, upstream_error, service_errorPonó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):

Model1080p2K
heygen-avatar-6-turbo10 kredytów ($0.05) / s18 kredytów ($0.09) / s
heygen-avatar-620 kredytów ($0.10) / s29 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.

Share: