In this guide, we will learn how to replace script text and voice within a template and generate a video.

Text Properties:

• content: Text content.

Voice Properties:

• voice_id: Supports any ID returned from /v2/voices.

Creating Template through the Interface

To create templates, visit HeyGen Template page and click on Create Template. Under the Script tab you can create a new script section.

As you can see we have 1 script in our scene, we are going to change script with the variable, here is how we can assign variable.

Regarding the voice of the script, you can assign a variable to the voice using the "API Variable (Voice)" menu. The current voice for script_en is Tony (American - English) in this guide we will replace it with Fable (Multilingual).

Get a List of Your Templates

See detailed API reference
Using the following API request you will get a list of your templates that you have created in the HeyGen interface, obtain your template_id from here.

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

{
  "error": null,
  "data": {
    "templates": [
      {
        "template_id": "<template_id>",
        "name": "<name>",
        "thumbnail_image_url": "<thumbnail_image_url>"
      },
      ...
    ]
  }
}

Retrieve Template Elements

See detailed API reference
To retrieve template elements, use this API request. Get the variable you want to change from here.

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

{
  "error": null,
  "data": {
    "variables": {
      "script_en": {
        "name": "script_en",
        "type": "text",
        "properties": {
          "content": ""
        }
      },
      "script1_voice": {
        "name": "script1_voice",
        "type": "voice",
        "properties": {
          "voice_id": "1ae3be1e24894ccabdb4d8139399f721"
        }
      }
    }
  }
}

Voices

For the target voice_id you can choose any id returned from the /v2/voices endpoint. In this guide we will utilize Fable (Multilingual).

...
{
  "voice_id": "8b92884579014f8e8147836bbd0c13ca",
  "language": "Multilingual",
  "gender": "male",
  "name": "Fable",
  "preview_audio": "https://static.heygen.ai/voice_preview/3ii9BykcfMVv2kTCZUm9mf.wav",
  "support_pause": false
}
...

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

Modify Template Elements and Generate Video

See detailed API reference
To change template elements and generate videos, you will need to submit an API request as follows. In the request body, specify the elements you want to modify by providing the appropriate object within the variables section.

curl --location 'https://api.heygen.com/v2/template/<template_id>/generate' \
     --header 'X-Api-Key: <your-api-key>' \
     --header 'Content-Type: application/json' \
     --data '{
  "caption": false,
  "title": "New Video",
  "variables": {
    "script_en": {
      "name": "script_en",
      "type": "text",
      "properties": {
        "content": "Hey there, how are you today?"
      }
    },
    "script1_voice": {
      "name": "script1_voice",
      "type": "voice",
      "properties": {
        "voice_id": "8b92884579014f8e8147836bbd0c13ca"
      }
    }
  }
}'

{
  "error": null,
  "data": {
    "video_id": "<video_id>"
  }
}

You will receive a video_id after your request. To check the video's status and retrieve further details, you can use the video_status API endpoint.

Template Scene Guidelines

There are certain guidelines to follow when using your template in the API. The new AI Studio allows your script to span multiple scenes. While users can save their templates as desired, to use the template in the API, scripts must be contained within a scene, or scenes must be contained within a script.

Failure to follow these guidelines will result in an "End of scene 1 does not align with script" error.

Conclusion

In this guide, we've walked you through the process of replacing voice and script text within a template video using HeyGen's Template API. By following the steps outlined here, you can seamlessly modify template elements to create customized videos that suit your specific needs.