# Retrieve Template Details (V3)
Retrieves the details of a template created under your account by its ID, including all variables available for replacement. For templates created in the New AI Studio, the scenes field is also returned, showing variables mapped to each `scene`.
**Note:**
* This API supports the New AI Studio.
* Scroll down to the **Response** section below and expand the status code(s) to view the detailed response schema.
* Refer to the **RESPONSE** section on the right and choose an example to see how the API response appears for each status code.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "heygen-api",
"version": "4.0.8"
},
"servers": [
{
"url": "https://api.heygen.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/v3/template/{template_id}": {
"get": {
"summary": "Retrieve Template Details (V3)",
"description": "This API supports a new field `scenes` for the New AI Studio, returning template variables mapped to scenes.",
"operationId": "get-template-v3",
"parameters": [
{
"name": "template_id",
"in": "path",
"schema": {
"type": "string"
},
"required": true,
"description": "Unique identifier of the template. Can be retrieved from the List Templates endpoint."
}
],
"responses": {
"200": {
"description": "Template details retrieved successfully - Expand to view the detailed response schema.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"error\": null,\n \"data\": {\n \"version\": \"4\",\n \"variables\": {\n \"firstName\": {\n \"name\": \"firstName\",\n \"type\": \"text\",\n \"properties\": {\n \"content\": \"\"\n }\n },\n \"image\": {\n \"name\": \"image\",\n \"type\": \"image\",\n \"properties\": {\n \"url\": \"https://example.com/sample-image.png\",\n \"asset_id\": null,\n \"fit\": \"cover\"\n }\n },\n \"video\": {\n \"name\": \"video\",\n \"type\": \"video\",\n \"properties\": {\n \"url\": \"https://example.com/sample-video.mp4\",\n \"asset_id\": null,\n \"play_style\": \"loop\",\n \"fit\": \"none\",\n \"volume\": 1\n }\n },\n \"avatar\": {\n \"name\": \"avatar\",\n \"type\": \"character\",\n \"properties\": {\n \"character_id\": \"Annie_expressive12_public\",\n \"type\": \"avatar\"\n }\n },\n \"introduction_audio\": {\n \"name\": \"introduction_audio\",\n \"type\": \"voice\",\n \"properties\": {\n \"voice_id\": \"330290724a1b470fb63153f34d4c0183\",\n \"locale\": null\n }\n }\n },\n \"scenes\": [\n {\n \"id\": \"ZvtWi9HS\",\n \"script\": \"Hey {{first_name}}! Great to see you. I’m your {{type}}, here to help you explore, learn, and create amazing things. Stick around, and let’s make something awesome together! \",\n \"variables\": [\n {\n \"name\": \"avatar\",\n \"type\": \"character\"\n },\n {\n \"name\": \"first_name\",\n \"type\": \"text\"\n },\n {\n \"name\": \"image\",\n \"type\": \"image\"\n },\n {\n \"name\": \"introduction_audio\",\n \"type\": \"voice\"\n }\n ]\n },\n {\n \"id\": \"rTYsc537\",\n \"script\": \"Now that you’re here, let’s dive right in. Whether you’re learning something new or just exploring, I’ll make sure it’s simple, clear, and maybe even a little fun. Ready? Let’s get started!\",\n \"variables\": [\n {\n \"name\": \"video\",\n \"type\": \"video\"\n }\n ]\n }\n ]\n }\n}\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Displays error message when the request fails; null if the request is successful."
},
"data": {
"type": "object",
"description": "Contains detailed information about the template, including its variables and their configurations.",
"properties": {
"version": {
"type": "string",
"description": "The draft version of the template (e.g., `3`, `4`). This indicates which iteration of the template you are retrieving."
},
"variables": {
"type": "object",
"description": "A collection of dynamic elements defined in the template.",
"properties": {
"name": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the variable as defined in the template. "
},
"type": {
"type": "string",
"description": "Type of variable (e.g., `text`, `image`, `video`, `character`, `voice`). "
},
"properties": {
"type": "object",
"description": "Configuration details for the variable, depending on its type.
Note:
The properties object returned for each variable depends on its type. The following fields are returned for each variable type:
- Text Variables: Only the
content field is returned. - Image Variables: Fields such as
url, asset_id, and fit are returned. - Video Variables: Fields such as
url, asset_id, play_style, fit, and volume are returned. - Character Variables: Fields such as
character_id and type are returned. - Voice Variables: Fields such as
voice_id and locale are returned.
",
"properties": {
"content": {
"type": "string",
"description": "The text content assigned to the variable."
},
"url": {
"type": "string",
"description": "URL to the image/audio/video resource. "
},
"asset_id": {
"type": "string",
"description": "Unique identifier of the uploaded image/audio/video. "
},
"play_style": {
"type": "string",
"description": "Playback mode (e.g., `loop`, `freeze`, `once`, `fit_to_scene`)"
},
"fit": {
"type": "string",
"description": "How the background video fits to the screen (e.g., `crop`, `contain`, `none`, `cover`). "
},
"volume": {
"type": "string",
"description": "Playback volume level. "
},
"voice_id": {
"type": "string",
"description": "Unique identifier of the voice."
},
"locale": {
"type": "string",
"description": "Voice accents/locales for multilingual voices (e.g., en-US, en-IN, pt-PT, pt-BR). "
},
"character_id": {
"type": "string",
"description": "Unique identifier of the character."
},
"type": {
"type": "string",
"description": "Type of variable. Returned for the `character` type. "
}
}
},
"scenes": {
"type": "array",
"description": "List of scenes in the template, in order. For V3 drafts, this may be `null`. ",
"items": {
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the scene within the template. "
},
"script": {
"type": "string",
"description": "The text or dialogue content contained in the scene."
},
"variables": {
"type": "array",
"description": "Variables available for replacement in the scene. Each variable allows dynamic content to be inserted when generating videos.",
"items": {
"properties": {
"name": {
"type": "string",
"description": "Name of the variable as defined in the template. "
},
"type": {
"type": "string",
"description": "Type of variable (e.g., `text`, `image`, `video`, `character`, `voice`). "
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"description": "Individual variable in the template. "
}
}
}
}
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```