how-tos

Guide de la HeyGen Avatar 6 API : première vidéo parlante en cURL et Python

Poyo.ai Team
9 min read
Share:

Guide de la HeyGen Avatar 6 API : première vidéo parlante en cURL et Python

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-key et exportez-la sous POYO_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.

ChampModeRègle
modelTousheygen-avatar-6 ou heygen-avatar-6-turbo
image_urlsPhoto (obligatoire), vidéo de référence (facultatif)Tableau d’exactement une URL
video_urlVidéo de référenceAu moins 2 s, jusqu’à 50 MB
avatarAvatar publicL’un des 1,248 noms répertoriés
audio_urlPhoto, vidéo de référence ; ou avatar public à la place de text2–60 s, jusqu’à 15 MB
textAvatar public1–1,000 caractères
voiceAvatar public avec textL’un des 102 noms
promptTousJusqu’à 1,200 caractères
aspect_ratioAvatar public16:9, 9:16, 1:1, 4:5, 5:4
resolutionTous1080p (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 corpserror.typeQue faire
400validation_error et autresCorrigez l’entrée : audio hors de 2–60 s, nom d’avatar inconnu, champ d’un autre mode. Ne réessayez pas sans modification
401authentication_errorVérifiez l’en-tête Authorization: Bearer
402insufficient_credits_errorRechargez votre compte, ou attendez que les tâches texte en cours soient réglées (voir ci-dessous)
429rate_limit_errorTemporisez puis réessayez
500 / 502 / 503internal_error, upstream_error, service_errorRé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èle1080p2K
heygen-avatar-6-turbo10 crédits ($0.05) / s18 crédits ($0.09) / s
heygen-avatar-620 crédits ($0.10) / s29 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.

Share: