API & Integrations

December 12, 2024 · Last updated on May 20, 2025

Send personalized messages using HeyGen’s API: a step-by-step walkthrough

# API

# Personalized Video

Creating personalized birthday videos using templates and integrating OpenAI to generate dynamic scripts

HeyGen’s API empowers you to automate video creation, personalize content at scale, and integrate avatars into your projects. Want to see what a personalized video from HeyGen looks like? Fill out this form to receive one.

In this guide, we’ll demonstrate two examples based on Alec’s webinar:

1) Creating Personalized Birthday Videos Using Templates

2) Integrating OpenAI to Generate Dynamic Scripts

Let’s get started!

Step 1: Access the HeyGen API Documentation

Visit docs.heygen.com to access HeyGen’s official API documentation. This contains:

Setup guides for beginners.

Detailed API references for developers.

If you’re unfamiliar with APIs, don’t worry—this guide will walk you through the essentials.

Step 2: Create a Video Template

Templates allow you to design reusable videos with customizable elements (variables). These templates are central to automating video creation.

How to Create a Template:

Log into HeyGen and navigate to the Templates section.

Click Create Template and design your video:

Add your avatar, background, and any static elements (e.g., text, images).

Define Variables for dynamic content:

Select an element (e.g., text or image).

Click the API button to assign a variable name (e.g., name, message, background).

Save the template and copy its Template ID by clicking the three dots next to the template.

Step 3: Generate Videos Using the Template API

Python Example:

Below is a corrected script to dynamically generate a personalized birthday video:

import requests

# API and Template Information
api_key = "YOUR_API_KEY"
template_id = "YOUR_TEMPLATE_ID"
generate_url = f"https://api.heygen.com/v2/template/{template_id}/generate"

# Request Headers
headers = {"Accept": "application/json", "X-API-KEY": api_key}

# Payload with Dynamic Variables
payload = {
    "title": "Birthday Greeting for Alec",
    "variables": {
        "name": {"name": "name", "type": "text", "properties": {"content": "Alec"}},
        "message": {
            "name": "message",
            "type": "text",
            "properties": {"content": "Happy birthday, Alec! Wishing you a fantastic day."},
        },
    },
}

# API Request
response = requests.post(generate_url, json=payload, headers=headers)

# Handle Response
if response.status_code == 200:
    video_data = response.json()
    print("Video URL:", video_data["video_url"])
else:
    print("Error:", response.json())

Steps to Follow:

Replace YOUR_API_KEY with your API key (found under Settings > API in your HeyGen account).

Replace YOUR_TEMPLATE_ID with your Template ID from Step 2.

Customize the name and message fields in the payload.

Run the script to generate the video. The video URL will appear in the response.

Step 4: Add OpenAI for Dynamic Script Creation

Integrating OpenAI allows you to generate unique scripts for each video, making the content even more personalized.

Python Example with OpenAI:

import requests
import openai

# OpenAI API Key
openai.api_key = "YOUR_OPENAI_API_KEY"

# Generate Dynamic Script with OpenAI
response = openai.Completion.create(
    engine="text-davinci-003",
    prompt="Write a funny birthday message for Alec.",
    max_tokens=50,
)
dynamic_message = response.choices[0].text.strip()

# HeyGen API Details
api_key = "YOUR_API_KEY"
template_id = "YOUR_TEMPLATE_ID"
generate_url = f"https://api.heygen.com/v2/template/{template_id}/generate"

# Request Headers
headers = {"Accept": "application/json", "X-API-KEY": api_key}

# Payload with OpenAI-Generated Script
payload = {
    "title": "Dynamic Birthday Greeting",
    "variables": {
        "name": {"name": "name", "type": "text", "properties": {"content": "Alec"}},
        "message": {
            "name": "message",
            "type": "text",
            "properties": {"content": dynamic_message},
        },
    },
}

# API Request
response = requests.post(generate_url, json=payload, headers=headers)

# Handle Response
if response.status_code == 200:
    video_data = response.json()
    print("Video URL:", video_data["video_url"])
else:
    print("Error:", response.json())

Steps to Follow:

Replace YOUR_OPENAI_API_KEY and YOUR_API_KEY with your respective API keys.

Update the OpenAI prompt for the type of message you’d like (e.g., professional, humorous).

Run the script to dynamically generate and personalize the video.

Step 5: Check Video Status and Download

After generating the video, you can check its status and download it.

Code Snippet:

import time

# Video Status Check
video_status_url = f"https://api.heygen.com/v1/video_status.get?video_id={video_id}"

while True:
    response = requests.get(video_status_url, headers=headers)
    status = response.json()["data"]["status"]
    if status == "completed":
        video_url = response.json()["data"]["video_url"]
        print("Video Completed! URL:", video_url)
        break
    elif status in ["processing", "pending"]:
        print("Video is still processing...")
        time.sleep(5)  # Wait for 5 seconds before checking again
    elif status == "failed":
        print("Video generation failed.")
        break

Resources and Support

API Documentation: HeyGen API Docs

Community Hub: Join our community to ask questions, share ideas, and get inspired.

Contact Support: Email us at [email protected] for technical assistance.

We hope this walkthrough empowers you to explore HeyGen’s API capabilities. Happy creating! 🎉

Comments (0)

Popular

Table Of Contents