![]()
Ce guide de la HeyGen Avatar 6 API vous mène d’une clé API à une vidéo parlante terminée sur PoYo. Vous soumettez une requête JSON avec l’identifiant de modèle heygen-avatar-6 (ou heygen-avatar-6-turbo), conservez l’identifiant de tâche renvoyé et interrogez le statut jusqu’à ce que le MP4 soit prêt. Chaque corps de requête ci-dessous suit la forme de la documentation PoYo ; la page du modèle HeyGen Avatar 6 propose un Playground si vous voulez d’abord voir les entrées.
Avant de commencer
- Créez une clé sur
poyo.ai/dashboard/api-keyet exportez-la sousPOYO_API_KEY. Gardez-la côté serveur. - Hébergez chaque fichier d’entrée à une URL HTTP ou HTTPS publique et directement téléchargeable. PoYo récupère lui-même les médias ; il n’accepte pas de fichiers envoyés dans la requête.
- Choisissez un niveau. Les deux identifiants acceptent les mêmes champs. Turbo coûte 10 crédits ($0.05) par seconde en 1080p ; Avatar 6 coûte 20 crédits ($0.10). Voir Avatar 6 vs Turbo.
Votre première requête à la HeyGen Avatar 6 API avec cURL
La première requête la plus rapide ne nécessite aucun média : un avatar public HeyGen lit votre texte.
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"
}
}'
Une réponse réussie contient "code": 200 et data.task_id, avec status à not_started. C’est une tâche en file d’attente, pas une vidéo. Interrogez son statut :
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Les statuts sont not_started, running, finished et failed. Une fois finished, le MP4 se trouve dans data.files[] avec file_type video, et data.credits_amount indique le montant facturé. En cas de failed, lisez data.error_message.
Une boucle de polling Python bornée
Lors de nos tests du jour du lancement, le 19 novembre 2026, de courts extraits à partir de texte ont pris environ 2 à 2.4 minutes entre la soumission et le résultat. Cette boucle interroge le statut toutes les 5 secondes (la documentation du statut recommande 2–5 s), s’arrête au bout de 15 minutes et ne resoumet jamais en cas de dépassement du délai, car une seconde soumission est une seconde tâche facturable.
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)
En production, ajoutez un callback_url au premier niveau au lieu d’interroger le statut. PoYo envoie le même objet de tâche (sans l’enveloppe code / data) lorsque la tâche est finished ou failed, signé en HMAC-SHA256 dans X-Webhook-Signature ; la documentation des webhooks donne la règle de signature.
Les trois modes d’entrée de la HeyGen Avatar 6 API
Il n’y a pas de sélecteur de mode. avatar sélectionne le mode avatar public ; sinon, video_url sélectionne le mode vidéo de référence ; sinon, la requête s’exécute en mode photo. Utilisez les entrées d’un seul mode par requête.
Mode avatar public avec du texte
Présenté ci-dessus. avatar est l’un des 1,248 looks publics, text compte jusqu’à 1,000 caractères et voice est l’une des 102 voix (par défaut Warm Pro Narrator). Le tutoriel texte vers avatar explique comment choisir les looks et les voix dans le catalogue.
Mode avatar public avec votre audio
Remplacez text et voice par audio_url. aspect_ratio s’applique toujours :
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Mode photo
Une photo d’une personne réelle plus la parole. La vidéo conserve le format de la photo : recadrez donc la photo au cadre voulu avant de l’envoyer. callback_url se place à côté de model, pas dans 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"
}
}
Mode vidéo de référence
Pour les personnages animés ou illustrés. video_url est un extrait du personnage ; image_urls ajoute en option une image fixe du même personnage. La sortie conserve le format de l’extrait :
{
"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"
}
}
Règles de validation des champs de la HeyGen Avatar 6 API
Vérifiez-les dans votre propre code avant de soumettre ; ce sont les limites documentées.
| Champ | Mode | Règle |
|---|---|---|
model | Tous | heygen-avatar-6 ou heygen-avatar-6-turbo |
image_urls | Photo (obligatoire), vidéo de référence (facultatif) | Tableau d’exactement une URL |
video_url | Vidéo de référence | Au moins 2 s, jusqu’à 50 MB |
avatar | Avatar public | L’un des 1,248 noms répertoriés |
audio_url | Photo, vidéo de référence ; ou avatar public à la place de text | 2–60 s, jusqu’à 15 MB |
text | Avatar public | 1–1,000 caractères |
voice | Avatar public avec text | L’un des 102 noms |
prompt | Tous | Jusqu’à 1,200 caractères |
aspect_ratio | Avatar public | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Tous | 1080p (par défaut) ou 2K |
Les noms d’avatars et de voix sont reconnus indépendamment de la casse et des espaces superflus, avec une exception documentée : Hope et Hope (avec une espace finale) sont deux voix différentes. Le schéma d’entrée n’autorise pas de champs supplémentaires : n’envoyez donc pas d’options natives de l’API HeyGen comme motion_expressiveness ou motion_prompt ; sur PoYo, la direction des mouvements passe par prompt.
Les erreurs à gérer
Lisez toujours code dans le corps de la réponse. Certaines erreurs de validation reviennent en HTTP 200 avec "code": 400 : vérifier uniquement le statut HTTP ne suffit donc pas.
code du corps | error.type | Que faire |
|---|---|---|
| 400 | validation_error et autres | Corrigez l’entrée : audio hors de 2–60 s, nom d’avatar inconnu, champ d’un autre mode. Ne réessayez pas sans modification |
| 401 | authentication_error | Vérifiez l’en-tête Authorization: Bearer |
| 402 | insufficient_credits_error | Rechargez votre compte, ou attendez que les tâches texte en cours soient réglées (voir ci-dessous) |
| 429 | rate_limit_error | Temporisez puis réessayez |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Réessayez avec un backoff exponentiel |
La durée de l’audio, la durée de la vidéo de référence et le nom de l’avatar sont vérifiés à la soumission : ces erreurs apparaissent donc sous forme de 400 immédiat plutôt que de tâche échouée quelques minutes plus tard.
Le cas 402 a une particularité propre à HeyGen. Lors de notre test du jour du lancement, après la soumission de deux tâches texte, une troisième requête (Turbo, 2K, 22 mots) est revenue en HTTP 200 avec un code 402 dans le corps et le type insufficient_credits_error : « this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks. » Les tâches texte bloquent des crédits pendant leur exécution : une rafale de soumissions texte peut donc déclencher un 402 même si les montants finaux tiendraient dans le solde. Mettez les tâches texte en file d’attente, ou affichez le message d’erreur à l’utilisateur, puisqu’il indique déjà les deux chiffres.
Comment est calculée la première facture de la HeyGen Avatar 6 API
PoYo facture à la seconde de sortie, arrondie à la seconde entière supérieure (1 crédit = $0.005) :
| Modèle | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 crédits ($0.05) / s | 18 crédits ($0.09) / s |
heygen-avatar-6 | 20 crédits ($0.10) / s | 29 crédits ($0.145) / s |
- Avec
audio_url(tous les modes) : le montant correspond à la durée de l’audio, arrondie à l’entier supérieur, et est prélevé à la soumission. Un extrait de 12.3 secondes sur Avatar 6 en 1080p coûte 13 × 20 = 260 crédits ($1.30). - Avec
text: les crédits sont réservés à la soumission et ajustés à la durée de la vidéo finale à la fin de la tâche. Lors de nos tests, un script de 27 mots sur Turbo a produit 10.16 s, facturées comme 11 secondes, soit 110 crédits (11 s × 10, $0.55) aux prix actuels ; un script de 21 mots sur Avatar 6 a produit 6.88 s, facturées comme 7 secondes, soit 140 crédits (7 s × 20, $0.70) aux prix actuels.
data.credits_amount sur la tâche terminée est le chiffre à rapprocher. D’autres exemples figurent dans Prix de la HeyGen Avatar 6 API.
Questions fréquentes
Comment appeler la HeyGen Avatar 6 API depuis Python ?
Envoyez du JSON en POST à https://api.poyo.ai/api/generate/submit avec requests, puis interrogez /api/generate/status/{task_id} avec une échéance, comme dans la boucle ci-dessus. N’importe quel client HTTP convient ; aucun SDK n’est requis.
La HeyGen Avatar 6 API propose-t-elle un callback ?
Oui. Ajoutez callback_url au premier niveau de la requête. PoYo envoie les données de la tâche lorsqu’elle se termine ou échoue.
Pourquoi ma requête à la HeyGen Avatar 6 API a-t-elle renvoyé HTTP 200 mais aucune tâche ?
Lisez le corps. Un code différent de 200 signifie que la requête a échoué, même avec HTTP 200 ; error.message en donne la raison.
Puis-je envoyer un fichier directement à la HeyGen Avatar 6 API ?
Non. image_urls, video_url et audio_url acceptent des URL HTTP ou HTTPS publiques que PoYo télécharge.
Combien de temps les résultats de la HeyGen Avatar 6 API sont-ils conservés ?
Les vidéos générées restent accessibles 3 jours après leur création. Téléchargez le MP4 dans votre propre stockage.