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

Audio Properties:

• url: URL for the audio file.
• asset_id:: Asset ID.

Creating Template through the Interface

To create templates, visit HeyGen Template page and click on Create Template.

You can use the "API Variable" menu to assign a variable to a sound element in your timeline.

You can also assign a variable to your audio script. To do this, select your audio with 'Upload Audio' in the Script section, then assign a variable with the 'API Variable' menu.

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": {
      "bg_music": {
        "name": "bg_music",
        "type": "audio",
        "properties": {
          "url": "https://files.heygen.ai/...",
          "asset_id": null
        }
      },
      "my_script": {
        "name": "my_script",
        "type": "audio",
        "properties": {
          "url": "https://resource.heygen.ai/...",
          "asset_id": null
        }
      }
    }
  }
}

Modify Template Elements and Generate Video

See detailed API reference
To modify template elements and generate videos, you need to submit an API request as follows In the request body, specify the elements you want to change 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": {
      "bg_music": {
        "name": "bg_music",
        "type": "audio",
        "properties": {
          "url": "<url>",
          "asset_id": null
        }
      },
      "my_script": {
        "name": "my_script",
        "type": "audio",
        "properties": {
          "url": null,
          "asset_id": "<asset_id>"
        }
      }
  }
}'

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

As for background audio, each audio must at least align with and contain one scene. Basically, scenes scale with contained script, background audios scale with contained scenes, and all visual elements (linearly) scale with whichever scene they are in. Here are some examples:

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

Conclusion

In this guide, we've walked you through the process of replacing audio 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.