Developer Guide
Start typing to search…

Replace Text/Voice in Template

Modify script text and voice in templates using HeyGen's API

❗️

Note:

  • This guide and the associated API endpoints refer to HeyGen API V2, which correspond to the Legacy AI Studio. These endpoints will be deprecated soon as HeyGen has transitioned to the new AI Studio and updated API versions. It’s recommended to start migrating your workflows to the latest APIs for continued support and feature compatibility.
  • A newer Retrieve Template Details (V3) API is available under the New AI Studio, offering enhanced functionality and updated variable mappings. Refer to the Generate Video from Template (V3) section for details.

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:

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.

In this example, we currently have one script in the scene. We’ll update it by replacing the existing script text with a 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

For instructions on listing your templates that you have created in the HeyGen interface and retrieving the template_id, see Get a List of Templates.

Retrieve Template Elements

To retrieve template elements you will need to submit an API request as follows. In the response, you’ll receive details of all variables defined in the template, in this case, the voice and text element details, which can later be modified when creating videos.

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"
        }
      }
    }
  }
}

For a full list of parameters and complete response details, see detailed API Reference: Retrieve Template Details.

Voices

For the target voice_id, you can choose any id returned from theList All Voices (V2) 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>'

For the complete list of available voices, including their IDs, supported languages and preview audio links, see detailed API Reference : List All Voices (V2)

Modify Template Elements and Generate Video

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>"
  }
}

To explore how different variable types can be modified when generating a new video, see detailed API Reference: Generate Video from Template

You will receive a video_id after your request. To check the video's status and retrieve further details, you can use the Retrieve Video Status/Details API endpoint. You can view complete status response examples on the right-side Response panel of the API Reference page - open the Examples dropdown to view responses for different video statuses. You can select any example to preview the corresponding response body.

Status Descriptions

pending
The video is queued and waiting to start rendering.

waiting
The video is in waiting state.

processing
The video is currently rendering.

completed
The video has successfully rendered and is ready for download.

failed
The video could not be rendered due to an error (for example, if the duration exceeds plan limits).

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.

ℹ️

Note:

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.

Updated 13 days ago