Comment utiliser l'API HeyGen Avatar V ? Du choix de l'avatar au téléchargement de la vidéo finale

HeyGen Avatar V : choisissez un avatar numérique prédéfini, saisissez un script ou un audio, et vous générez une vidéo synchronisée avec la lèvre. HiAPI facture selon la durée de sortie, à 0,15 $ par seconde, soit 1,50 $ pour une vidéo de 10 secondes.

HeyGen Avatar V est disponible sur HiAPI. Ouvrez la page du modèle pour choisir d'abord l'avatar et la voix, puis connectez l'API. La démo métier ci-dessous est une vidéo déjà produite :

Brandon Office Sitting Front, Dexter - Professional ; 16:9, vidéo finale 1280×720, environ 8 secondes. La requête d'origine était en 1080p ; cette page affiche la version web en 720p.

Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.

Générer avec ce prompt → Le script est déjà rempli ; sélectionnez manuellement l'avatar, la voix, la résolution 1080p et le format 16:9 ci-dessus, puis choisissez MP4 en sortie.

Comment l'essayer en ligne ?

1. Ouvrez le lien prérempli en conservant ce court script.
2. Choisissez l'avatar et la voix ; ces paramètres doivent être sélectionnés manuellement, le lien ne transporte que le script.
3. Définissez le format d'image, la résolution et le format de fichier ; pour un premier essai, utilisez la combinaison ci-dessus.
4. Après génération, écoutez la voix, vérifiez la synchronisation labiale, téléchargez la vidéo, puis remplacez par votre propre texte.

Notez l'avatar, la voix et le format d'image de cet essai ; pour la génération par lots, réutilisez-les en ne changeant que le script, afin de garder le même présentateur et la même voix.

V choisit le présentateur parmi les avatars prédéfinis ; pour faire apparaître votre propre photo, choisissez Avatar IV.

Toutes les résolutions sont facturées selon le nombre réel de secondes produites, avec remboursement intégral en cas d'échec ; le détail complet des coûts figure dans le tableau des prix et du budget.

Que préparer pour l'API ?

Créez une clé API dans la console. Dans la requête, indiquez explicitement model, le champ obligatoire input.avatar, puis choisissez entre prompt et audio_url. Pour l'avatar et la voix, utilisez les valeurs de requête en anglais des fiches de documentation ; les noms chinois ne servent qu'à l'identification.

Le script est lu directement ; n'insérez pas d'instructions de cadrage dans prompt. Pour le pilotage audio, transmettez une adresse HTTP(S) accessible et retirez prompt et voice. Il n'est pas nécessaire de transmettre duration ; la durée est déterminée par la lecture du script ou par l'audio.

Ce que vous avez	Quels champs de pilotage transmettre
Un script à lire	avatar + prompt ; voice facultatif
Un audio déjà enregistré	avatar + audio_url ; omettre prompt et voice

Recherche de l'avatar : documentation des paramètres → avatars numériques, dépliez tout, puis recherchez et copiez la « valeur de requête » en anglais ; la voix se cherche de la même manière dans voix prédéfinies. La page anglaise correspond à Request value ; ne mettez pas le nom d'affichage chinois dans la requête.

**Requête minimale complète pour le pilotage audio :** remplacez l'adresse d'exemple par l'URL publique accessible de votre propre audio. Les champs omis concernant le format d'image, la résolution et le format de fichier utilisent les valeurs par défaut de la documentation ; l'audio peut durer jusqu'à 600 secondes et peser au maximum 32 MiB.

{
  "model": "heygen-avatar-v",
  "input": {
    "avatar": "Brandon Office Sitting Front",
    "audio_url": "https://example.com/your-recording.mp3"
  }
}

Créer et interroger une tâche avec cURL

Remplacez le placeholder de clé par votre propre valeur ; cette requête reprend les paramètres de l'exemple métier :

export HIAPI_API_KEY="sk-YOUR_KEY"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-v",
    "input": {
      "avatar": "Brandon Office Sitting Front",
      "prompt": "Hi, I\u0027m Daniel. Send me your quarterly numbers, and I\u0027ll walk your team through what changed and what to do next.",
      "voice": "Dexter - Professional",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "caption": false,
      "output_format": "mp4"
    }
  }'

Vérifiez le statut HTTP et le code du JSON, puis, après une création réussie, conservez data.taskId. Ensuite, interrogez uniquement cette même tâche :

TASK_ID="REPLACE_WITH_data.taskId"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

queued, handling, archiving indiquent un traitement en cours ; les états finaux sont success ou fail. En cas de succès, cherchez video selon data.output[].type, puis caption si les sous-titres sont activés. Lisez l'url de l'artefact et téléchargez-le à temps selon expireAt.

**Exemple de structure de réponse :** le premier bloc correspond à une création réussie, le second à une interrogation réussie après activation des sous-titres ; les identifiants de tâche, URL et dates d'expiration sont des valeurs indicatives ; expireAt est un nombre en secondes Unix. En cas de timeout POST ou de réponse perdue, consultez d'abord l'historique de la tâche, et interdisez-vous de refaire un POST à l'aveugle ; si vous avez un ID, continuez avec GET.

{
  "code": 200,
  "data": {"taskId": "TASK_ID_FROM_CREATE"}
}

{
  "code": 200,
  "data": {
    "taskId": "TASK_ID_FROM_CREATE",
    "status": "success",
    "output": [
      {"type": "video", "url": "https://example.com/result.mp4", "expireAt": 4070908800},
      {"type": "caption", "url": "https://example.com/result.srt", "expireAt": 4070908800}
    ]
  }
}

Python : création, polling limité, téléchargement

Installez d'abord requests, puis définissez la clé dans la variable d'environnement HIAPI_API_KEY. Le code ne soumet qu'une seule fois et interroge pendant 30 minutes au maximum ; en cas de timeout, conservez l'ID de tâche pour continuer à interroger.

import os
import time
from pathlib import Path
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
payload = {
    "model": "heygen-avatar-v",
    "input": {
        "avatar": "Brandon Office Sitting Front",
        "prompt": "Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.",
        "voice": "Dexter - Professional",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
        "caption": False,
        "output_format": "mp4",
    },
}

def api_request(method, url, **kwargs):
    advice = (
        "Submission state may be unknown; check task history before another POST."
        if method == "POST"
        else f"Continue GET with the saved task ID: {url.rsplit('/', 1)[-1]}."
    )
    try:
        response = requests.request(
            method, url, headers=HEADERS, timeout=(10, 30), **kwargs
        )
    except requests.RequestException:
        raise RuntimeError(f"Network error. {advice}") from None
    if not response.ok:
        raise RuntimeError(f"HTTP {response.status_code}. {advice}")
    try:
        body = response.json()
    except ValueError:
        raise RuntimeError(f"Response is not JSON. {advice}") from None
    if not isinstance(body, dict):
        raise RuntimeError(f"Unexpected response shape. {advice}")
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"API error: code={body.get('code')}. {advice}")
    return body["data"]

# Submit once. No automatic POST retries.
created = api_request("POST", API, json=payload)
task_id = created.get("taskId")
if not isinstance(task_id, str) or not task_id:
    raise RuntimeError("Missing taskId; check task history before resubmitting.")
print("taskId:", task_id)  # Keep this ID to resume GET queries.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    data = api_request("GET", f"{API}/{task_id}")
    status = data.get("status")
    if status == "fail":
        raise RuntimeError(f"Task failed: {task_id}; inspect its task record.")
    if status == "success":
        break
    if status not in ("queued", "handling", "archiving"):
        raise RuntimeError(f"Unexpected task status: {status}")
    time.sleep(8)
else:
    raise TimeoutError(f"Polling timed out; continue GET for taskId={task_id}.")

raw_outputs = data.get("output")
if not isinstance(raw_outputs, list):
    raise RuntimeError(f"Missing output list; inspect taskId={task_id}.")
outputs = {
    item["type"]: item
    for item in raw_outputs
    if isinstance(item, dict) and item.get("type") in ("video", "caption")
}
if "video" not in outputs:
    raise RuntimeError("Successful task has no video artifact.")
for kind, artifact in outputs.items():
    if not isinstance(artifact.get("url"), str) or not artifact["url"]:
        raise RuntimeError(f"Missing {kind} URL; inspect taskId={task_id}.")
    suffix = payload["input"]["output_format"] if kind == "video" else "srt"
    target = Path(f"avatar-v.{suffix}")
    # Artifact downloads do not need the API Authorization header.
    with requests.get(artifact["url"], stream=True, timeout=(10, 120)) as response:
        response.raise_for_status()
        with target.open("wb") as file:
            for chunk in response.iter_content(chunk_size=1024 * 1024):
                if chunk:
                    file.write(chunk)
    print("saved:", target)

Quels paramètres définir explicitement ?

Champ	Règles et valeurs par défaut
avatar	Obligatoire, valeur de requête de l'avatar en anglais
prompt / audio_url	Choix exclusif ; script jusqu'à 5 000 caractères, audio jusqu'à 600 secondes et 32 MiB maximum
voice	Facultatif pour le parcours script, valeur par défaut Warm Pro Narrator
resolution	Valeur par défaut 720p, options 1080p, 4k en minuscules
aspect_ratio	Valeur par défaut 16:9 ; également 9:16, 4:5, 5:4, 1:1, auto
fit	Valeur par défaut cover, option contain
caption	Valeur par défaut false ; true renvoie un SRT séparé
output_format	Valeur par défaut mp4, option webm
remove_background	Valeur par défaut false ; pour un usage transparent, choisissez true avec webm, et vérifiez d'abord l'avatar choisi avec un court extrait
background	Objet ; type vaut color ou image, value contient une couleur hexadécimale ou une URL d'image HTTP(S)

La résolution et le format d'image sont deux paramètres distincts : utilisez 16:9 pour une explication en paysage et 9:16 pour une prise de parole en vertical, en les indiquant tous deux dans la requête. Après téléchargement, jetez un œil aux dimensions réelles du fichier. Pour un WebM transparent, vérifiez d'abord le détourage de l'avatar choisi, puis importez-le dans votre logiciel de montage.

Les sous-titres ne sont pas incrustés dans l'image ; il faut les superposer dans le lecteur ou le logiciel de montage. L'exemple vertical ci-dessous définit caption=true et renvoie un SRT séparé ; la vidéo fait 1080×1920 et 6,52 secondes, la requête étant en 1080p, 9:16. Le sous-titre SRT séparé peut être importé au montage.

New drop just landed: our travel mug keeps coffee hot for twelve hours. Swipe up and grab yours today!

Générer avec ce prompt → Le script est déjà rempli ; sélectionnez manuellement Riley Casual Front, Charming Charles - Friendly, 9:16 et 1080p, activez les sous-titres et choisissez MP4 en sortie.

Quels sont les quatre points à vérifier avant la mise en ligne ?

1. Valider les entrées : avatar, mode de pilotage, valeurs de requête en anglais et limites de longueur.
2. Conserver l'ID de tâche : après un échec d'interrogation ou un timeout, continuez avec GET sur le même ID.
3. Récupérer tous les artefacts : en cas de succès, cherchez video selon type, et caption si les sous-titres sont activés.
4. Vérifier les téléchargements : confirmez les dimensions réelles, le son et le fichier de sous-titres avant livraison.

Comment gérer les problèmes courants ?

• **Problème de validation des entrées :** vérifiez avatar, le champ de pilotage exclusif, les valeurs de requête en anglais, les limites de script et d'audio ; écrivez 4k en minuscules pour la résolution et supprimez duration.
• **Timeout POST :** consultez d'abord l'historique de la tâche ; si vous avez déjà un taskId, continuez avec GET, car chaque POST crée une nouvelle tâche.
• **Tâche fail :** consultez la cause de l'erreur dans l'historique de la tâche, corrigez l'entrée correspondante, puis soumettez à nouveau.
• **Lien de téléchargement expiré :** enregistrez les artefacts à temps après le succès ; les sous-titres se lisent via type=caption.

Le serveur peut ajouter, au même niveau que input, "callback": {"url": "https://yourapp.com/webhook", "when": "final"}, pour recevoir l'objet de tâche à l'état final et compenser par une interrogation GET.

Pour les détails de prix, voir le prix à la seconde et le tableau budgétaire ; pour changer d'avatar, consultez les deux exemples ; pour toutes les valeurs, voir la documentation des paramètres de l'API.

Générer avec ce prompt → Le script est déjà rempli ; sélectionnez manuellement l'avatar et la voix métier, 1080p, 16:9, MP4, générez d'abord une phrase, puis intégrez le script complet.