Generate Video from Template V2

πŸ“˜

V2 APIs are still in Beta

πŸ“˜

If you are interested in using Instant Avatars within the template to generate videos, please follow this tutorial.

Templates enable you to add and customize existing text, images, videos, and elements, while avatar videos consist only of avatars without these elements. If you plan to use it within a workflow and need richer content, templates are likely a better fit for your use case compared to simple talking avatar videos. 🌟

Quick Comparison:

  • Avatar Videos: Avatar videos are centered around avatars delivering content without any additional elements. They are ideal for straightforward, avatar-focused communication.
  • Template Videos: In contrast, template videos offer a wide canvas for creativity. They enable you to customize existing text, images, videos, and elements seamlessly. If you need a richer, more versatile content format for your workflow, templates are the perfect choice. They empower you to create captivating, multifaceted content that stands out.

Quick Start

Let's get started quickly to see how to create a template, add placeholders, and create a new video by dynamically changing these placeholders using the Template API.

Creating Template through the Interface

To create templates, visit HeyGen Template page and click on Create Template. After that, add a placeholder in your template by using double curly brackets {{}}.

As shown, we've placed a {{name}} placeholder within our scene and script. In this tutorial, we'll set a value for this placeholder using the Template API and create a new video.

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 Video Elements

See detailed API reference
To retrieve video elements for a specific template, use this API request to get the variable you want to change.

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": {
      "name": {
        "name": "name",
        "type": "text",
        "properties": {
          "content": ""
        }
      }
    }
  }
}

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 '{
  "test": true,
  "caption": false,
  "title": "New Video",
  "variables": {
    "name": {
      "name": "name",
      "type": "text",
      "properties": {
        "content": "John"
      }
    }
  }
}'
{
  "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.

curl --request GET \
     --url https://api.heygen.com/v1/video_status.get?video_id=<video_id> \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: <your-api-key>'
{
  "code": 100,
  "data": {
    "callback_id": null,
    "caption_url": "<caption_url>",
    "duration": 1.234,
    "error": null,
    "gif_url": "<gif_url>",
    "id": "<id>",
    "status": "completed",
    "thumbnail_url": "<thumbnail_url>",
    "video_url": "<video_url>",
    "video_url_caption": null
  },
  "message": "Success"
}
{
  "code": 100,
  "data": {
    "callback_id": null,
    "caption_url": null,
    "duration": null,
    "error": null,
    "gif_url": null,
    "id": "<id>",
    "status": "processing",
    "thumbnail_url": null,
    "video_url": null,
    "video_url_caption": null
  },
  "message": "Success"
}
{
  "code": 100,
  "data": {
    "callback_id": null,
    "caption_url": null,
    "duration": null,
    "error": null,
    "gif_url": null,
    "id": "<id>",
    "status": "pending",
    "thumbnail_url": null,
    "video_url": null,
    "video_url_caption": null
  },
  "message": "Success"
}
{
  "code": 100,
  "data": {
    "callback_id": null,
    "caption_url": null,
    "duration": null,
    "error": {
      "code": 40119,
      "detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos",
      "message": "Video is too long"
    },
    "gif_url": null,
    "id": "<id>",
    "status": "failed",
    "thumbnail_url": null,
    "video_url": null,
    "video_url_caption": null
  },
  "message": "Success"
}

πŸ“˜

The video file URL you get will expire in 7 days. πŸ“†

You can observe this expiration in the URL parameters. Every time you call the video status endpoint, the Expires and other queries are regenerated accordingly.

Here is the result:

Explore the guides below for detailed information on how to modify and customize template content:

Please note that we currently do not support changing Avatars in Template V2 API.

Conclusion

In summary, HeyGen's Template API empowers users to effortlessly generate customized videos from templates. The process begins with creating a template through the web interface. Users can then use this template to generate tailored videos, replacing variables as needed. This approach provides a versatile tool for video creation and personalization. So, whether your goal is to captivate your audience or communicate your message more effectively, templates offer the versatility you need to succeed.