Comment utiliser Heygen AI via l'API : Un guide complet

Heygen AI est une plateforme puissante qui permet aux utilisateurs de créer de manière programmatique des vidéos d'avatars réalistes générées par l'IA. Ce tutoriel complet vous guidera tout au long du processus d'intégration et d'exploitation de l'API de Heygen pour une variété de cas d'utilisation, des simples vidéos d'avatars à la création de contenu complexe basée sur des modèles. Chaque section fournit des instructions détaillées, étape par étape, pour vous aider à maîtriser les capacités de Heygen.

💡

Vous cherchez à rationaliser votre flux de travail de développement d'API ? Apidog se distingue comme l'alternative ultime à Postman, offrant une suite complète d'outils pour la conception, le débogage, les tests et la documentation des API, le tout sur une plateforme unifiée.

button

Grâce à son interface intuitive, ses fonctionnalités de collaboration et ses puissantes capacités d'automatisation, Apidog réduit considérablement le temps de développement tout en améliorant la qualité des API.

button

Que vous construisiez une architecture de microservices complexe ou que vous vous intégriez à des API tierces comme Heygen, les serveurs simulés, les variables d'environnement et les nombreuses options de test d'Apidog en font le choix préféré des développeurs qui exigent efficacité et fiabilité. Essayez Apidog dès aujourd'hui et découvrez la prochaine évolution des outils de développement d'API.

button

Introduction à l'API Heygen

L'API Heygen permet aux développeurs de créer des vidéos d'avatars alimentées par l'IA de manière programmatique et d'intégrer les capacités de Heygen dans leurs applications. L'API offre diverses fonctionnalités, notamment la génération de vidéos, la traduction et la création de contenu basée sur des modèles. En suivant ce tutoriel, vous apprendrez à exploiter ces capacités pour créer du contenu attrayant pour le marketing, l'éducation, le service client, et plus encore.

La fonctionnalité principale de l'API repose sur la génération de vidéos avec des avatars IA réalistes qui peuvent parler n'importe quel texte que vous fournissez ou se synchroniser avec des fichiers audio. De plus, vous pouvez personnaliser les arrière-plans, traduire des vidéos en plusieurs langues et travailler avec des modèles pour des productions plus complexes.

Au-delà de la simple création de vidéos de base, l'API de Heygen vous permet de créer des applications sophistiquées qui peuvent générer automatiquement du contenu personnalisé pour vos utilisateurs, créer des expériences interactives ou même traduire des vidéos existantes en plusieurs langues. Cela la rend inestimable pour les entreprises mondiales, les créateurs de contenu, les éducateurs et les développeurs qui cherchent à intégrer la vidéo générée par l'IA dans leurs produits.

Premiers pas avec l'API Heygen

Création d'un compte pour l'API Heygen

Suivez ces étapes pour créer votre compte Heygen :

Visitez le site Web officiel de Heygen à l'adresse heygen website.
Cliquez sur le bouton "S'inscrire" ou "Commencer" dans le coin supérieur droit
Choisissez votre méthode d'inscription préférée (e-mail, Google, etc.)
Remplissez le formulaire d'inscription avec vos coordonnées
Acceptez les conditions et la politique de confidentialité
Vérifiez votre adresse e-mail si nécessaire
Connectez-vous à votre nouveau compte

Après l'inscription, vous aurez accès à l'interface Web et aux capacités de l'API de Heygen. Les nouveaux utilisateurs reçoivent généralement un essai gratuit avec des fonctionnalités limitées. L'essai gratuit comprend des vidéos filigranées et des quotas d'utilisation limités, mais il est suffisant pour tester les fonctionnalités de l'API avant de s'engager dans un forfait payant.

Au cours du processus d'inscription, Heygen peut vous poser des questions sur votre cas d'utilisation prévu. Fournir ces informations peut aider Heygen à adapter les recommandations à vos besoins spécifiques, bien que cela ne soit pas strictement nécessaire pour l'accès à l'API.

Obtention de votre clé API

Pour accéder à l'API, suivez ces étapes détaillées pour obtenir votre clé API :

Connectez-vous à votre compte Heygen
Cliquez sur votre photo de profil ou votre avatar dans le coin supérieur droit
Sélectionnez "Paramètres" dans le menu déroulant
Accédez à l'onglet "Abonnements"
Faites défiler vers le bas jusqu'à la section "HeyGen API"
Cliquez sur "Afficher" à côté de "Jeton API"
Authentifiez-vous si vous y êtes invité
Copiez votre jeton API à utiliser dans vos requêtes

Conservez ce jetton en lieu sûr, car il donne un accès complet à l'API sous votre compte. Ne l'exposez jamais dans le code côté client ou les référentiels publics. Si vous soupçonnez que votre clé API a été compromise, vous pouvez en générer une nouvelle à partir de la même page de paramètres.

Votre clé API sera utilisée dans toutes vos requêtes vers l'API Heygen. En général, vous l'inclurez dans l'en-tête X-Api-Key de vos requêtes HTTP. Par exemple :

X-Api-Key: your-api-key-here

Différents niveaux d'abonnement offrent différentes limites d'utilisation de l'API. L'essai gratuit offre un accès de base avec des vidéos filigranées, tandis que les forfaits payants (Pro, Scale et Enterprise) offrent des limites d'utilisation, des fonctionnalités et des options de qualité croissantes. Consultez la page de tarification de Heygen pour obtenir les informations les plus récentes sur les fonctionnalités et les limitations des forfaits.

Création de vidéos d'avatars de base avec l'API Heygen

Liste des avatars disponibles avec l'API Heygen

Pour commencer à créer des vidéos, vous devez d'abord savoir quels avatars sont disponibles. Suivez ces étapes :

Ouvrez votre terminal ou votre client API
Effectuez la requête suivante :

curl --request GET \\\\
  --url <https://api.heygen.com/v2/avatars> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Examinez la réponse, qui ressemblera à ceci :

{
  "error": null,
  "data": {
    "avatars": [
      {
        "avatar_id": "Angela-inblackskirt-20220820",
        "avatar_name": "Angela in Black Dress",
        "gender": "female",
        "preview_image_url": "<preview_image_url>",
        "preview_video_url": "<preview_video_url>"
      },
      // More avatars...
    ]
  }
}

Choisissez un avatar et notez son avatar_id pour une utilisation ultérieure

Chaque avatar a des apparences et des styles différents. Certains avatars sont conçus pour des contextes spécifiques, comme les présentations professionnelles, les conversations informelles ou le contenu éducatif. Prévisualisez les avatars à l'aide des URL fournies pour en trouver un qui correspond à votre cas d'utilisation prévu.

Si vous utilisez Python, vous pouvez utiliser cet extrait de code à la place :

import requests

headers = {
    'Accept': 'application/json',
    'X-Api-Key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/avatars>', headers=headers)
avatars = response.json()['data']['avatars']

# Print all available avatars
for avatar in avatars:
    print(f"ID: {avatar['avatar_id']}, Name: {avatar['avatar_name']}")

Les avatars ont différents styles disponibles, tels que "normal" ou "casual". Le style par défaut est "normal", mais vous pouvez en spécifier d'autres lors de la création de vidéos si l'avatar prend en charge plusieurs styles.

Liste des voix disponibles avec l'API Heygen

Ensuite, vous devez sélectionner une voix pour votre avatar. Suivez ces étapes :

Effectuez la requête API suivante :

curl --request GET \\\\
  --url <https://api.heygen.com/v2/voices> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Examinez la réponse pour trouver les voix disponibles :

{
  "error": null,
  "data": {
    "voices": [
      {
        "voice_id": "26b2064088674c80b1e5fc5ab1a068ec",
        "language": "English",
        "gender": "male",
        "name": "Rex",
        "preview_audio": "<https://resource.heygen.ai/text_to_speech/bCo7SFtTvcJz6udLqHmUKf.mp3>",
        "support_pause": false,
        "emotion_support": true,
        "support_interactive_avatar": true
      },
      // More voices...
    ]
  }
}

Choisissez une voix et notez son voice_id pour une utilisation ultérieure

Les voix sont disponibles dans différentes langues, accents et genres. Écoutez l'aperçu audio pour trouver une voix qui correspond au ton et au style de votre projet. Certaines voix prennent en charge des fonctionnalités supplémentaires telles que les inflexions émotionnelles ou les pauses, ce qui peut être utile pour des présentations plus dynamiques.

Faites attention à la propriété support_interactive_avatar si vous prévoyez d'utiliser des avatars interactifs plus tard, car toutes les voix ne prennent pas en charge cette fonctionnalité.

Équivalent Python :

response = requests.get('<https://api.heygen.com/v2/voices>', headers=headers)
voices = response.json()['data']['voices']

# Print all available voices
for voice in voices:
    print(f"ID: {voice['voice_id']}, Name: {voice['name']}, Language: {voice['language']}")

# Filter for English voices only
english_voices = [v for v in voices if v['language'] == 'English']
print(f"Found {len(english_voices)} English voices")

Génération d'une simple vidéo d'avatar avec l'API Heygen

Maintenant que vous avez sélectionné un avatar et une voix, suivez ces étapes pour créer une vidéo :

Préparez votre charge utile de requête avec l'avatar et la voix choisis :

{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Angela-inTshirt-20220820",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "speed": 1.1
      },
      "background": {
        "type": "color",
        "value": "#87CEEB"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

Envoyez la requête pour générer la vidéo :

curl -X POST <https://api.heygen.com/v2/video/generate> \\\\
-H 'X-Api-Key: <your-api-key>' \\\\
-H 'Content-Type: application/json' \\\\
-d '<your-prepared-json>'

Enregistrez le video_id de la réponse :

{
  "error": null,
  "data": {
    "video_id": "abcdef123456"
  }
}

Décomposons les paramètres de la requête :

video_inputs : Un tableau de configurations de scène
character : Spécifie l'avatar à utiliser
type : "avatar" pour les avatars Heygen standard
avatar_id : L'ID de votre avatar choisi
avatar_style : Le style visuel de l'avatar (par exemple, "normal", "casual")
voice : Configuration de la parole
type : "text" pour la conversion texte-parole
input_text : Le script que l'avatar prononcera
voice_id : L'ID de votre voix choisie
speed : Vitesse d'élocution (1,0 est normal, plus élevé est plus rapide)
background : Configuration de l'arrière-plan
type : "color" pour les arrière-plans de couleur unie
value : Code couleur hexadécimal
dimension : Dimensions de la vidéo de sortie
width : Largeur de la vidéo en pixels
height : Hauteur de la vidéo en pixels

Vous pouvez ajuster ces paramètres pour personnaliser votre vidéo. Par exemple, la modification de la valeur speed affecte la vitesse à laquelle l'avatar parle, tandis que dimension contrôle la résolution vidéo.

Implémentation Python :

import json
import requests

payload = {
    "video_inputs": [
        {
            "character": {
                "type": "avatar",
                "avatar_id": "Angela-inTshirt-20220820",
                "avatar_style": "normal"
            },
            "voice": {
                "type": "text",
                "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
                "voice_id": "1bd001e7e50f421d891986aad5158bc8",
                "speed": 1.1
            },
            "background": {
                "type": "color",
                "value": "#87CEEB"
            }
        }
    ],
    "dimension": {
        "width": 1280,
        "height": 720
    }
}

response = requests.post(
    '<https://api.heygen.com/v2/video/generate>',
    headers={
        'X-Api-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    data=json.dumps(payload)
)

video_id = response.json()['data']['video_id']
print(f"Video generation initiated! Video ID: {video_id}")

Vérification de l'état de la génération vidéo avec l'API Heygen

Après avoir lancé la génération vidéo, suivez ces étapes pour vérifier son état :

Utilisez le video_id de l'étape précédente pour effectuer une requête de vérification d'état :

curl --request GET \\\\
  --url <https://api.heygen.com/v1/video_status.get?video_id=><video_id> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Surveillez l'état dans la réponse :

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "processing",
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "error": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Répétez la vérification jusqu'à ce que l'état passe à "completed" ou "failed"

La génération vidéo prend généralement entre 30 secondes et plusieurs minutes, selon :

La longueur du texte d'entrée
La charge du serveur
La complexité de la vidéo
Votre niveau d'abonnement

Les valeurs d'état que vous pourriez rencontrer :

pending : Votre requête a été reçue, mais le traitement n'a pas encore commencé
processing : Votre vidéo est en cours de génération
completed : Votre vidéo est prête à être téléchargée
failed : Une erreur s'est produite lors de la génération de votre vidéo

Lorsqu'une vidéo échoue, la réponse inclura un message d'erreur expliquant le problème :

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "failed",
    "error": {
      "code": 40119,
      "message": "Video is too long",
      "detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos"
    },
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Implémentation Python avec interrogation :

import time
import requests

def check_video_status(video_id, api_key):
    headers = {
        'Accept': 'application/json',
        'X-Api-Key': api_key
    }

    max_attempts = 30  # Avoid infinite loops
    attempt = 0

    while attempt < max_attempts:
        response = requests.get(
            f'<https://api.heygen.com/v1/video_status.get?video_id={video_id}>',
            headers=headers
        )

        data = response.json()['data']
        status = data['status']

        if status == 'completed':
            print("Video generation complete!")
            return {
                'video_url': data['video_url'],
                'thumbnail_url': data['thumbnail_url'],
                'duration': data['duration']
            }
        elif status == 'failed':
            error = data['error']
            print(f"Video generation failed: {error}")
            return None
        else:
            print(f"Video status: {status}. Checking again in 5 seconds...")
            attempt += 1
            time.sleep(5)

    print("Maximum attempts reached. Video still not ready.")
    return None

# Usage
result = check_video_status("abcdef123456", "your-api-key")
if result:
    print(f"Video URL: {result['video_url']}")
    print(f"Duration: {result['duration']} seconds")

Téléchargement de votre vidéo générée avec l'API Heygen

Une fois que l'état de la vidéo est "completed", suivez ces étapes pour télécharger votre vidéo :

Extrayez le video_url de la réponse d'état
Téléchargez la vidéo à l'aide de l'URL :

curl <video_url> --output my_avatar_video.mp4

Vérifiez que le fichier téléchargé fonctionne correctement

Implémentation Python :

import requests

def download_video(video_url, output_filename="my_avatar_video.mp4"):
    response = requests.get(video_url)

    if response.status_code == 200:
        with open(output_filename, 'wb') as file:
            file.write(response.content)

        print(f"Video downloaded successfully to {output_filename}")
        print(f"File size: {len(response.content) / (1024 * 1024):.2f} MB")
        return True
    else:
        print(f"Failed to download video. Status code: {response.status_code}")
        return False

# Usage
success = download_video("<https://storage.googleapis.com/heygen-videos/>...")

Remarque importante : L'URL de la vidéo expire au bout de 7 jours. Assurez-vous de télécharger votre vidéo avant son expiration ou mettez en œuvre un système pour régénérer ou récupérer à nouveau l'URL de la vidéo si nécessaire.

Pour les systèmes de production, envisagez :

La configuration d'une tâche planifiée pour télécharger les vidéos rapidement après leur génération
Le stockage des vidéos dans votre propre stockage cloud pour un accès à long terme
L'implémentation d'une base de données pour suivre les ID de vidéo, les dates de génération et les dates d'expiration

Heygen API : Utilisation des modèles

Les modèles offrent plus de flexibilité que les simples vidéos d'avatars, vous permettant de personnaliser le texte, les images, les vidéos, les audios et les avatars dans une mise en page préconçue.

Modèles d'API Heygen par rapport aux simples vidéos d'avatars

Voici une comparaison des principales différences :

Vidéos d'avatars :

Se concentrent uniquement sur un avatar qui parle
Limitées à une seule scène avec un seul avatar
Options d'arrière-plan simples
Idéales pour les vidéos de type "tête parlante" simples
Créées entièrement via des appels d'API

Vidéos de modèles :

Plusieurs scènes avec divers éléments
Espaces réservés personnalisables pour le texte, les images, les vidéos, les avatars et l'audio
Transitions et animations complexes
Prise en charge de plusieurs avatars dans une seule vidéo
Les modèles sont créés via l'interface Web Heygen
L'API est utilisée pour générer des vidéos basées sur des modèles

Les modèles sont particulièrement utiles pour créer des séries de vidéos cohérentes ou générer des vidéos personnalisées à grande échelle. Par exemple, vous pouvez créer un modèle pour les démonstrations de produits, puis générer des versions personnalisées pour différents produits en modifiant uniquement le texte, les images et les détails du produit pertinents.

API Heygen Création de modèles avec des espaces réservés

Les modèles sont créés via l'interface Web Heygen :

Connectez-vous à votre compte Heygen
Accédez à la section Modèles
Cliquez sur "Créer un modèle"
Utilisez l'éditeur pour concevoir votre modèle avec ces composants :

Éléments de texte : Ajoutez des textes qui peuvent être personnalisés ultérieurement
Scènes d'avatar : Ajoutez des avatars qui prononceront du contenu personnalisable
Espaces réservés d'image : Ajoutez des espaces pour des images personnalisées
Espaces réservés vidéo : Ajoutez des espaces pour des clips vidéo personnalisés
Éléments audio : Ajoutez de la musique de fond ou des effets sonores

Pour chaque élément que vous souhaitez rendre personnalisable, définissez un espace réservé à l'aide de doubles accolades :

Exemple de texte : {{product_name}}
Exemple de script d'avatar : {{product_description}}
Espace réservé d'image : Sélectionnez une image et marquez-la comme variable

Organisez les éléments comme vous le souhaitez et prévisualisez le modèle
Enregistrez votre modèle avec un nom descriptif

Par exemple, lors de la création d'un modèle d'annonce de produit, vous pouvez inclure :

Un texte d'ouverture avec {{company_name}} et {{product_name}}
Un avatar qui dit "Nous sommes ravis de présenter {{product_name}}, qui offre {{key_benefit}}"
Un espace réservé d'image pour {{product_image}}
De la musique de fond qui peut être remplacée

Les espaces réservés peuvent être de différents types :

Texte : Pour remplacer du texte écrit ou des scripts d'avatar
Image : Pour remplacer des éléments d'image
Vidéo : Pour remplacer des clips vidéo
Avatar : Pour modifier l'avatar qui apparaît
Voix : Pour modifier la voix utilisée par les avatars
Audio : Pour remplacer la musique de fond ou les effets sonores

Liste de vos modèles avec l'API Heygen

Pour récupérer tous les modèles que vous avez créés :

curl --location '<https://api.heygen.com/v2/templates>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Cela renvoie des informations sur tous vos modèles, y compris leurs ID et URL de miniatures :

{
  "error": null,
  "data": {
    "templates": [
      {
        "template_id": "abcdef123456",
        "title": "Product Announcement",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-15T14:25:30Z"
      },
      {
        "template_id": "ghijkl789012",
        "title": "Weekly Update",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-18T09:12:45Z"
      }
    ]
  }
}

Implémentation Python :

import requests

headers = {
    'accept': 'application/json',
    'x-api-key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/templates>', headers=headers)
templates = response.json()['data']['templates']

print(f"Found {len(templates)} templates:")
for template in templates:
    print(f"ID: {template['template_id']}, Title: {template['title']}, Created: {template['created_at']}")

Récupération des éléments de modèle avec l'API Heygen

Pour voir les variables disponibles dans un modèle spécifique :

curl --location '<https://api.heygen.com/v2/template/><template_id>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Cela affiche tous les éléments personnalisables de votre modèle :

{
  "error": null,
  "data": {
    "template_id": "abcdef123456",
    "title": "Product Announcement",
    "variables": {
      "company_name": {
        "name": "company_name",
        "type": "text",
        "properties": {
          "default_content": "Company Name"
        }
      },
      "product_name": {
        "name": "product_name",
        "type": "text",
        "properties": {
          "default_content": "Product Name"
        }
      },
      "key_benefit": {
        "name": "key_benefit",
        "type": "text",
        "properties": {
          "default_content": "amazing benefits to users"
        }
      },
      "product_image": {
        "name": "product_image",
        "type": "image",
        "properties": {
          "default_url": "<https://example.com/default-image.jpg>"
        }
      }
    }
  }
}

Comprendre la structure des variables de votre modèle est crucial pour générer correctement les vidéos. Notez le type de chaque variable (texte, image, vidéo, etc.) et toutes les valeurs par défaut fournies.

Implémentation Python :

def get_template_details(template_id, api_key):
    headers = {
        'accept': 'application/json',
        'x-api-key': api_key
    }

    response = requests.get(
        f'<https://api.heygen.com/v2/template/{template_id}>',
        headers=headers
    )

    if response.status_code == 200:
        template = response.json()['data']
        variables = template['variables']

        print(f"Template: {template['title']} (ID: {template['template_id']})")
        print("\\\\nVariables:")
        for var_name, var_details in variables.items():
            var_type = var_details['type']
            print(f"- {var_name} ({var_type})")

            if var_type == 'text' and 'default_content' in var_details['properties']:
                print(f"  Default: \\\\"{var_details['properties']['default_content']}\\\\"")
            elif var_type == 'image' and 'default_url' in var_details['properties']:
                print(f"  Default image: {var_details['properties']['default_url']}")