Building a Studio Template

Create a reusable template in HeyGen Studio, mark its script, voice, avatar, and background as variables, then fill those variables and render videos over the API.

Overview

A template is a video you design once in HeyGen Studio and reuse by swapping in different values. You mark the parts you want to change per video, the script, the voice, the avatar, the background, as variables, give each one a name, then use the API to fill those variables and generate a new video for every set of values.

One idea ties Studio and the API together: the name you give a variable in Studio is the exact key you send in the API. Name a variable name in the editor, and you fill it with "name": { ... } in your request.

This guide walks the full loop: build the template in Studio, then drive it from the API.

For the complete variable-type schema (text, image, video, audio, voice, character), asset inputs, scenes, and every generate option, see the Studio Template reference.

Prerequisites

• A HeyGen account with Studio access (app.heygen.com).
• An API key.

Part 1 — Build the template in Studio

You’ll build a one-scene welcome video with four variables: the viewer’s name (text), the voiceover, the presenter (avatar), and the background.

1. Open the template editor

   In HeyGen Studio, create a new video (or open an existing one) and lay out your avatar, script, and background as usual. This layout is what every generated video will share.

   
2. Turn script text into a variable

   In the Script pane, wrap any word you want to change per video in double braces. Here the script is Hi {{name}}, Welcome to HeyGen, so name becomes a text variable you fill at generate time.

   

   The text between the braces is the variable name, and it is the exact key you send in the API.
3. Make the voice a variable

   Open the three-dots menu on the script and choose API Variable. Name it voiceover and click Save. The voice for the scene can now be set per request.

   
4. Make the avatar a variable

   Select the avatar on the canvas, then click the API button in the hover toolbar. Name it presenter and Save. You can now swap the avatar per video.

   
5. Make the background a variable

   Click the background directly (not the avatar), then click the API button in its toolbar. Name it background and Save. The scene background can now be set per request.

   
6. Save the template

   Click Done Editing. Your template is now API-ready and will appear in the templates list.

   

You now have a template with four named variables, name, voiceover, presenter, and background. Those names are exactly the keys you use next.

Part 2 — Generate videos from the API

The flow is four calls: find the template, read its variables, fill them, then poll for the finished video.

1. Find your template

   List the API-ready templates in your workspace and grab the id of the one you built.

   curl -X GET "https://api.heygen.com/v3/templates?limit=10" \
     -H "x-api-key: YOUR_API_KEY"
   

   Response

   {
     "data": [
       {
         "id": "8ce3768236cd4e8a9ee8d88aad3537ae",
         "name": "DemoTemp",
         "thumbnail_url": "https://resource2.heygen.ai/image/.../original.png",
         "aspect_ratio": "16:9",
         "created_at": 1784323047,
         "updated_at": 1784323073
       }
     ],
     "has_more": false,
     "next_token": null
   }
   
2. Read the variable schema

   Fetch the template to see the variables you named in Studio, with their types and current defaults.

   curl -X GET "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae" \
     -H "x-api-key: YOUR_API_KEY"
   

   Response

   {
     "data": {
       "id": "8ce3768236cd4e8a9ee8d88aad3537ae",
       "name": "DemoTemp",
       "aspect_ratio": "16:9",
       "variables": {
         "name":       { "type": "text",      "content": "" },
         "voiceover":  { "type": "voice",     "voice_id": "330290724a1b470fb63153f34d4c0183" },
         "presenter":  { "type": "character", "character_id": "Annie_expressive5_public", "character_type": "avatar" },
         "background": { "type": "image",     "asset": { "type": "url", "url": "https://..." }, "fit": "none" }
       },
       "scenes": [
         {
           "scene_id": "BSueuHJY",
           "script": "Hi {{name}}, Welcome to HeyGen",
           "variables": [
             { "name": "name",       "variable_type": "text" },
             { "name": "voiceover",  "variable_type": "voice" },
             { "name": "presenter",  "variable_type": "character" },
             { "name": "background", "variable_type": "image" }
           ]
         }
       ]
     }
   }
   

   Each variable comes back in the same shape a generate request accepts, so you can take this object, swap the values, and send it straight back.
3. Fill the variables and generate

   Send the variables keyed by the names you set in Studio. Here we personalize name to “Alex” and set a new background.

   cURL

   curl -X POST "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Welcome video for Alex",
       "variables": {
         "name":       { "type": "text",  "content": "Alex" },
         "voiceover":  { "type": "voice", "voice_id": "330290724a1b470fb63153f34d4c0183" },
         "presenter":  { "type": "character", "character_id": "Annie_expressive5_public", "character_type": "avatar" },
         "background": { "type": "image", "asset": { "type": "url", "url": "https://example.com/office.jpg" }, "fit": "cover" }
       }
     }'
   

   import requests
   
   resp = requests.post(
       "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae",
       headers={"x-api-key": "YOUR_API_KEY"},
       json={
           "title": "Welcome video for Alex",
           "variables": {
               "name":       {"type": "text", "content": "Alex"},
               "voiceover":  {"type": "voice", "voice_id": "330290724a1b470fb63153f34d4c0183"},
               "presenter":  {"type": "character", "character_id": "Annie_expressive5_public", "character_type": "avatar"},
               "background": {"type": "image", "asset": {"type": "url", "url": "https://example.com/office.jpg"}, "fit": "cover"},
           },
       },
   )
   video_id = resp.json()["data"]["id"]
   print(video_id)
   

   const res = await fetch(
     "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae",
     {
       method: "POST",
       headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
       body: JSON.stringify({
         title: "Welcome video for Alex",
         variables: {
           name:       { type: "text", content: "Alex" },
           voiceover:  { type: "voice", voice_id: "330290724a1b470fb63153f34d4c0183" },
           presenter:  { type: "character", character_id: "Annie_expressive5_public", character_type: "avatar" },
           background: { type: "image", asset: { type: "url", url: "https://example.com/office.jpg" }, fit: "cover" },
         },
       }),
     }
   );
   const { data } = await res.json();
   console.log(data.id);
   

   Response

   {
     "data": {
       "id": "cb0009e7367b4a14b12981c4b6a85cb2",
       "status": "pending",
       "title": "Welcome video for Alex",
       "created_at": 1784325403
     }
   }
   

   Only include the variables you want to change, any you omit keep their template defaults. Add "test": true to render a lower-quality test video with no credit charge while you wire things up.
4. Poll for the finished video

   Generation is asynchronous. Poll the video by the id returned above until its status is completed, then read video_url.

   curl -X GET "https://api.heygen.com/v3/videos/cb0009e7367b4a14b12981c4b6a85cb2" \
     -H "x-api-key: YOUR_API_KEY"
   

   Response

   {
     "data": {
       "id": "cb0009e7367b4a14b12981c4b6a85cb2",
       "status": "completed",
       "video_url": "https://files2.heygen.ai/.../cb0009e7....mp4",
       "duration": 2.03
     }
   }
   

   Instead of polling, set a callback_url on the generate request to be notified when the video is ready. See Webhooks.

Troubleshooting

My template isn't in the list

Only templates that have at least one variable defined appear in GET /v3/templates, and the detail endpoint supports templates built in the current editor (draft version 4). Make sure you marked and saved at least one variable in Studio.

I get an unknown-variable error

The keys in your variables object must match the variable names you set in Studio exactly (case-sensitive). Read GET /v3/templates/{template_id} to confirm the names.

A text variable comes back empty

A text variable can be empty in the schema (an unfilled default), but it must be non-empty when you generate.

Next steps

Studio Template reference

Every variable type, asset input, scenes, and generate options.

Webhooks

Get notified when a video finishes instead of polling.