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.

📘

url and asset_id can be retrieved from the Upload Asset endpoint.

Creating Template through the Interface

To create a new template:

1. Go to the HeyGen Dashboard and open the Templates tab.
2. Click Create Template. This opens the template editor.
3. Below the script field, locate the Audio option. You can upload an audio file or record one directly.
4. To make the audio dynamic, click the three-dot (⋯) menu next to the audio element and select API Variable.

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 audio element details, which can later be modified when creating videos.

curl --request GET \
     --url https://api.heygen.com/v3/template/<template_id> \
     --header 'accept: application/json' \
     --header 'x-api-key: <your-api-key>'

{
  "error": null,
  "data": {
  "version": "4",
    "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
        }
      }
    },
    "scenes": [
      {
        "id": "<scene_id>",
        "script": "",
        "variables": {
          "bg_music": {
        		"name": "bg_music",
            "type": "audio"
          },
					"my_script": {
        		"name": "my_script",
            "type": "audio"
         }
        }
      }
    ]
  }
}

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

Modify Template Elements and Generate Video

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

If you want to explore all configurable options - including how to update multiple elements or adjust video metadata, 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).

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 modify template elements to create customized videos that suit your specific needs.