Generate Video from Template V1 (deprecated)

Suggest Edits

📘

If you are interested in using Instant Avatars within the template to generate videos, please use V2 API. Instant Avatars are not supported in the V1 API.

🚧

This API is deprecated and will be removed in 6 months. Please migrate to Template V2 . Finetuned and Studio Avatars created after 03/21/2024 will no longer be supported in v1 API.

HeyGen API supports the generation of videos from templates, enabling you to create customized videos with ease.

Create a Template Video on HeyGen

To create a template, you can use any videos as a template. Here's how you can make a video template:

  1. Head to HeyGen, where you can access the video editor interface.
  2. Customize the template to create your unique video using the editor's controls and tools.
    Modify the text, images, audio, and other elements to match your desired content.
  3. Once the video is ready find the video ID in your video list by clicking the three dots icon and selecting "Get Video ID".

Videos older than this date are not supported as template, 06:00 am on Friday, 19th August 2022 UTC

Get Template Info

See detailed API reference
Use the Retrieve a template API endpoint to fetch template variables in the template video. Provide the video_id to obtain these variables.

curl -X GET 'https://api.heygen.com/v1/template.get?video_id=<video_id>' \
-H 'X-Api-Key: <your-api-key>'

{
  "code": 100,
  "data": {
    "scenes": [
      {
        "variables": [
          {
            "name": "text_0",
            "properties": [
              {
                "default": "3 Easy Steps",
                "name": "text"
              }
            ],
            "type": "text"
          },
          {
            "name": "avatar_0",
            "properties": [
              {
                "default": "Kent-inTshirt-20220728",
                "name": "id"
              },
              {
                "default": "Welcome to HeyGen! \nHere's how you can create spokesperson video in 3 easy steps.",
                "name": "text"
              },
              {
                "default": "3d00ae9d06a440819b067f6651d950b7",
                "name": "voice_id"
              }
            ],
            "type": "avatar"
          }
        ]
      }
    ],
    "template_id": "4d1fc8798e91410fb0928269405a757a",
    "video_id": "4d1fc8798e91410fb0928269405a757a"
  },
  "message": "Success"
}

This request will return a list of template variables along with their data types and other information, helping you identify which variables to customize in your video.

Customize Template Variables and Generate Video

See detailed API reference
After identifying the template variables to modify, use the Generate from template API endpoint to create a new video version with your customizations. The request should include a data parameter, containing the template variables and their corresponding values.

For example, let's say that you want to customize the text_0 variables in your video, use the following request:

curl --request POST \
     --url https://api.heygen.com/v1/template.generate \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: <your-api-key>' \
     --data '
{
  "template_id": "4d1fc8798e91410fb0928269405a757a",
  "variables": [
    {
      "properties": {
        "text": "New Value."
      },
      "name": "text_0"
    }
  ],
  "title": "video_title",
  "test": true
}'

{
  "code": 100,
  "data": {
    "video_id": "<video_id>"
  },
  "message": "Success"
}

Please note the text length of the original template. The Generate Template API will only replace the variables you specify in the request.

📘

test flag

The "test" flag indicates that you're in a test environment, and video generation will not deduct your credits. However, there will be a watermark on the video.

To generate a video without a watermark, set the "test" flag to false or remove the test field. Ensure you have enough quota to deduct, or the generation will fail.

Check Video Generation Status

See detailed API reference

The Generate Template API will return a video_id in the response data, get the video status by Video Status API.

You'll get a response like this if the video has been ready:

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.

Conclusion

In summary, HeyGen API empowers users to effortlessly generate customized videos from templates. It starts by creating a template in the web interface. Users can then use this template to generate tailored videos, replacing variables as needed, and track the video's status via the API, unlocking a versatile tool for video creation and personalization.

For more related guides on template videos, explore:

Updated 29 days ago