> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Set Template Variables > Declares the complete set of variables for a template, replacing whatever was declared before. This is a full replacement, not a patch: every variable you want to keep must be included in every call, and any variable omitted is removed (text placeholders are restored to their default text). Character, voice, image, video and audio variables bind to an element by element_id; use the elements list from GET /v3/templates/{template_id} to find IDs, and each element takes at most one such variable. Text variables are created with match: every occurrence of that exact text in the template's script and on-screen text (or only in element_ids) becomes a {{name}} placeholder, with the matched text as the default. Declare a text variable without match to keep placeholders that already exist. Returns the updated template detail. ## OpenAPI ````yaml /openapi/external-api.json put /v3/templates/{template_id}/variables openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: Create folders to organize videos and translations in the workspace - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Models description: '' - name: Filler Word Removal description: '' paths: /v3/templates/{template_id}/variables: put: tags: - Templates summary: Set Template Variables description: >- Declares the complete set of variables for a template, replacing whatever was declared before. This is a full replacement, not a patch: every variable you want to keep must be included in every call, and any variable omitted is removed (text placeholders are restored to their default text). Character, voice, image, video and audio variables bind to an element by element_id; use the elements list from GET /v3/templates/{template_id} to find IDs, and each element takes at most one such variable. Text variables are created with match: every occurrence of that exact text in the template's script and on-screen text (or only in element_ids) becomes a {{name}} placeholder, with the matched text as the default. Declare a text variable without match to keep placeholders that already exist. Returns the updated template detail. operationId: setTemplateVariablesV3 parameters: - name: template_id in: path required: true schema: type: string description: Unique template identifier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetTemplateVariablesV3Request' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TemplateDetailV3' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: variable_match_not_found message: >- Text 'Acme' for variable 'company' was not found in the template. param: variables.company.match doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '403': description: Forbidden content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: resource_access_denied message: >- Template creation is restricted by your workspace settings. Ask a workspace admin to allow it. param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: template_not_found message: Template not found. param: null doc_url: null '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer '503': description: >- Temporarily unavailable — the request did not complete and is safe to retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: service_unavailable message: >- The template's element metadata could not be read, so the character variable was not stored. Retry the request. param: null doc_url: null security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: SetTemplateVariablesV3Request: additionalProperties: false description: >- Request body for PUT /v3/templates/{template_id}/variables. Full replacement: the body is the complete variable set after the call. A variable that exists on the template but is missing here is removed. properties: variables: additionalProperties: discriminator: mapping: audio: $ref: '#/components/schemas/TemplateAudioBinding' character: $ref: '#/components/schemas/TemplateCharacterBinding' image: $ref: '#/components/schemas/TemplateImageBinding' text: $ref: '#/components/schemas/TemplateTextBinding' video: $ref: '#/components/schemas/TemplateVideoBinding' voice: $ref: '#/components/schemas/TemplateVoiceBinding' propertyName: type oneOf: - $ref: '#/components/schemas/TemplateTextBinding' - $ref: '#/components/schemas/TemplateCharacterBinding' - $ref: '#/components/schemas/TemplateVoiceBinding' - $ref: '#/components/schemas/TemplateImageBinding' - $ref: '#/components/schemas/TemplateVideoBinding' - $ref: '#/components/schemas/TemplateAudioBinding' description: >- The complete variable set, keyed by variable name (letters, digits, underscores; must start with a letter or underscore; at most 64 characters). An empty object removes every variable. examples: - company: match: Acme type: text first_name: element_ids: - t81c0d4b match: John type: text hero_image: element_id: i77e5f60 type: image narration_voice: element_id: t81c0d4b type: voice presenter: element_id: a3f9c2e1 type: character title: Variables type: object required: - variables title: SetTemplateVariablesV3Request type: object TemplateDetailV3: description: >- Template detail including its variable schema, scenes, and bindable elements. properties: id: description: Unique template identifier examples: - 77e650952c024c6188a35e23e7088617 title: Id type: string name: description: Template name examples: - Quarterly Update title: Name type: string thumbnail_url: anyOf: - type: string - type: 'null' default: null description: URL to the template thumbnail image title: Thumbnail Url aspect_ratio: anyOf: - type: string - type: 'null' default: null description: Template aspect ratio examples: - '16:9' title: Aspect Ratio created_at: anyOf: - type: integer - type: 'null' default: null description: Unix timestamp of creation examples: - 1711929600 title: Created At updated_at: anyOf: - type: integer - type: 'null' default: null description: Unix timestamp of last update examples: - 1711929600 title: Updated At variables: additionalProperties: discriminator: mapping: audio: $ref: '#/components/schemas/TemplateAudioVariable' character: $ref: '#/components/schemas/TemplateCharacterVariable' image: $ref: '#/components/schemas/TemplateImageVariable' text: $ref: '#/components/schemas/TemplateTextVariable' video: $ref: '#/components/schemas/TemplateVideoVariable' voice: $ref: '#/components/schemas/TemplateVoiceVariable' propertyName: type oneOf: - $ref: '#/components/schemas/TemplateTextVariable' - $ref: '#/components/schemas/TemplateImageVariable' - $ref: '#/components/schemas/TemplateVideoVariable' - $ref: '#/components/schemas/TemplateAudioVariable' - $ref: '#/components/schemas/TemplateCharacterVariable' - $ref: '#/components/schemas/TemplateVoiceVariable' description: >- Variables defined in the template with their current default values, keyed by variable name title: Variables type: object source_video_id: anyOf: - type: string - type: 'null' default: null description: Video the template was created from, when known title: Source Video Id scene_ids: description: Scene IDs in template order items: type: string title: Scene Ids type: array scenes: description: Scenes defined in the template items: $ref: '#/components/schemas/TemplateSceneV3' title: Scenes type: array elements: description: >- Elements a variable can be bound to, in scene order, with their current values and existing bindings items: $ref: '#/components/schemas/TemplateElementV3' title: Elements type: array required: - id - name title: TemplateDetailV3 type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message TemplateAudioBinding: additionalProperties: false description: >- Bind an audio variable to an uploaded-audio script element, background audio, or sound effect. properties: type: const: audio description: Variable type discriminator title: Type type: string element_id: description: >- ID of the element to bind, from the elements list in GET /v3/templates/{template_id}; must be an audio, background_audio, or sound_effect element minLength: 1 title: Element Id type: string required: - type - element_id title: TemplateAudioBinding type: object TemplateCharacterBinding: additionalProperties: false description: Bind a character variable to an avatar element. properties: type: const: character description: Variable type discriminator title: Type type: string element_id: description: >- ID of the element to bind, from the elements list in GET /v3/templates/{template_id}; must be an avatar element minLength: 1 title: Element Id type: string required: - type - element_id title: TemplateCharacterBinding type: object TemplateImageBinding: additionalProperties: false description: Bind an image variable to an image element or image background. properties: type: const: image description: Variable type discriminator title: Type type: string element_id: description: >- ID of the element to bind, from the elements list in GET /v3/templates/{template_id}; must be an image or background_image element minLength: 1 title: Element Id type: string required: - type - element_id title: TemplateImageBinding type: object TemplateTextBinding: additionalProperties: false description: >- Declare a text variable. With ``match``, every occurrence of that exact text in the template's script and on-screen text becomes a ``{{name}}`` placeholder and the matched text becomes the default. Without ``match``, the template must already contain ``{{name}}`` placeholders (from the editor or an earlier call) and they are kept. properties: type: const: text description: Variable type discriminator title: Type type: string match: anyOf: - maxLength: 10000 minLength: 1 type: string - type: 'null' default: null description: >- Exact, case-sensitive text to turn into this variable. Every occurrence in the template's script and on-screen text becomes a {{name}} placeholder and the text becomes the variable's default. Omit to keep {{name}} placeholders the template already contains. examples: - Acme title: Match element_ids: anyOf: - items: type: string minItems: 1 type: array - type: 'null' default: null description: >- Limit match to these script (tts), text, or richtext elements. Defaults to every element that carries text. Only meaningful together with match. title: Element Ids required: - type title: TemplateTextBinding type: object TemplateVideoBinding: additionalProperties: false description: Bind a video variable to a video element or video background. properties: type: const: video description: Variable type discriminator title: Type type: string element_id: description: >- ID of the element to bind, from the elements list in GET /v3/templates/{template_id}; must be a video or background_video element minLength: 1 title: Element Id type: string required: - type - element_id title: TemplateVideoBinding type: object TemplateVoiceBinding: additionalProperties: false description: Bind a voice variable to a script element. properties: type: const: voice description: Variable type discriminator title: Type type: string element_id: description: >- ID of the element to bind, from the elements list in GET /v3/templates/{template_id}; must be a tts script element minLength: 1 title: Element Id type: string required: - type - element_id title: TemplateVoiceBinding type: object TemplateAudioVariable: additionalProperties: false description: Replaces an audio placeholder in the template. properties: type: const: audio description: Variable type discriminator title: Type type: string asset: description: Audio to place. Accepts url, asset_id, or base64 input. discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Asset required: - type - asset title: TemplateAudioVariable type: object TemplateCharacterVariable: additionalProperties: false description: Replaces an avatar or talking-photo placeholder in the template. properties: type: const: character description: Variable type discriminator title: Type type: string avatar_look_id: description: >- Avatar look ID to place; any avatar look, including talking photos. Same IDs as GET /v3/avatars/looks. Whether the look is an avatar or a talking photo is inferred from the look itself. examples: - Abigail_expressive_2024112501 minLength: 1 title: Avatar Look Id type: string required: - type - avatar_look_id title: TemplateCharacterVariable type: object TemplateImageVariable: additionalProperties: false description: Replaces an image placeholder in the template. properties: type: const: image description: Variable type discriminator title: Type type: string asset: description: Image to place. Accepts url, asset_id, or base64 input. discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Asset fit: default: contain description: How the image fits the placeholder box enum: - cover - contain - crop - none title: Fit type: string required: - type - asset title: TemplateImageVariable type: object TemplateTextVariable: additionalProperties: false description: Replaces a text placeholder in the template. properties: type: const: text description: Variable type discriminator title: Type type: string content: description: >- Replacement text content. May be empty in GET responses (unfilled template default); must be non-empty when generating. maxLength: 10000 title: Content type: string required: - type - content title: TemplateTextVariable type: object TemplateVideoVariable: additionalProperties: false description: Replaces a video placeholder in the template. properties: type: const: video description: Variable type discriminator title: Type type: string asset: description: Video to place. Accepts url, asset_id, or base64 input. discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Asset fit: default: contain description: How the video fits the placeholder box enum: - cover - contain - crop - none title: Fit type: string play_style: default: loop description: Playback behavior when the video is shorter than the scene enum: - fit_to_scene - freeze - loop - once - full_video title: Play Style type: string volume: default: 1 description: Audio volume of the video track, 0.0 (muted) to 1.0 maximum: 1 minimum: 0 title: Volume type: number required: - type - asset title: TemplateVideoVariable type: object TemplateVoiceVariable: additionalProperties: false description: Overrides the voice used by a script placeholder in the template. properties: type: const: voice description: Variable type discriminator title: Type type: string voice_id: description: Voice ID used for text-to-speech minLength: 1 title: Voice Id type: string locale: anyOf: - type: string - type: 'null' default: null description: Optional voice locale, e.g. 'en-US' title: Locale required: - type - voice_id title: TemplateVoiceVariable type: object TemplateSceneV3: description: A scene defined in the template. properties: scene_id: description: Scene ID, usable in the generate request's scene_ids title: Scene Id type: string script: anyOf: - type: string - type: 'null' default: null description: Scene script text, with variable placeholders unreplaced title: Script variables: description: Variables used in this scene items: $ref: '#/components/schemas/TemplateSceneVariableRef' title: Variables type: array required: - scene_id title: TemplateSceneV3 type: object TemplateElementV3: description: A draft element a variable can be bound to. properties: element_id: description: Element ID, stable for the life of the template title: Element Id type: string element_type: description: Kind of element enum: - avatar - tts - audio - background_audio - sound_effect - text - richtext - image - video - background_image - background_video title: Element Type type: string scene_id: anyOf: - type: string - type: 'null' default: null description: >- Scene the element belongs to; null for elements spanning scenes, such as background audio title: Scene Id bindable_as: description: Variable types that can be bound to this element items: enum: - text - image - video - audio - character - voice type: string title: Bindable As type: array current: $ref: '#/components/schemas/TemplateElementCurrentV3' description: The element's current value variable: anyOf: - type: string - type: 'null' default: null description: Name of the non-text variable bound to this element, if any title: Variable text_variables: description: Text variable names appearing as {{placeholders}} in this element items: type: string title: Text Variables type: array required: - element_id - element_type title: TemplateElementV3 type: object StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message AssetId: additionalProperties: false description: Asset input via HeyGen asset ID from the asset upload endpoint. properties: type: const: asset_id description: Input type discriminator title: Type type: string asset_id: description: HeyGen asset ID from the asset upload endpoint title: Asset Id type: string required: - type - asset_id title: AssetId type: object AssetBase64: additionalProperties: false description: Asset input via base64-encoded content. properties: type: const: base64 description: Input type discriminator title: Type type: string media_type: description: MIME type of the encoded content (e.g. "image/png") title: Media Type type: string data: description: Base64-encoded file content title: Data type: string required: - type - media_type - data title: AssetBase64 type: object x-mcp-visible: false AssetUrl: additionalProperties: false description: Asset input via publicly accessible HTTPS URL. properties: type: const: url description: Input type discriminator title: Type type: string url: description: Publicly accessible HTTPS URL for the asset title: Url type: string required: - type - url title: AssetUrl type: object TemplateSceneVariableRef: description: A variable used within a scene. properties: name: description: Variable name, matching a key in the template's variables title: Name type: string variable_type: description: 'Variable type: text, image, video, audio, character, or voice' title: Variable Type type: string required: - name - variable_type title: TemplateSceneVariableRef type: object TemplateElementCurrentV3: description: 'The element''s current value: what a variable bound to it would replace.' properties: avatar_look_id: anyOf: - type: string - type: 'null' default: null description: >- Avatar look placed in an avatar element; same IDs as GET /v3/avatars/looks title: Avatar Look Id character_type: anyOf: - enum: - avatar - talking_photo type: string - type: 'null' default: null description: Kind of look the avatar_look_id refers to title: Character Type voice_id: anyOf: - type: string - type: 'null' default: null description: Voice used by a script element title: Voice Id text: anyOf: - type: string - type: 'null' default: null description: Text content, with any {{placeholders}} unreplaced title: Text url: anyOf: - type: string - type: 'null' default: null description: Media URL of an image, video, or audio element title: Url play_style: anyOf: - type: string - type: 'null' default: null description: Playback behavior of a video element title: Play Style volume: anyOf: - type: number - type: 'null' default: null description: Audio volume of a video element, 0.0 to 1.0 title: Volume title: TemplateElementCurrentV3 type: object securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````