Documentation

Generate Video from Template

Suggest Edits

Templates enable you to add and customize existing text, images, videos, audios, voices and avatars, 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, audios, voices and avatars seamlessly. If you need a richer, more versatile content format for your workflow, templates are the perfect choice.

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.

When using your template in the API, certain guidelines must be followed. See

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 '{
  "caption": false,
  "title": "New Video",
  "variables": {
    "first_name": {
      "name": "first_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:

Quick Guides:

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 adhere to these guidelines will result in the "End of scene 1 does not align with script" error.

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.

Updated 3 days ago