--- title: "Update Template" method: PATCH path: "/v3/templates/{template_id}" tags: ["Templates"] --- # Update Template `PATCH /v3/templates/{template_id}` ## Request - Base URL: `https://api.heygen.com` - URL: `https://api.heygen.com/v3/templates/{template_id}` - Auth: one of: - API key in header `x-api-key` - HTTP bearer Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail. ## Path parameters - `template_id` string, required ## Request body - UpdateTemplateV3Request: Request body for PATCH /v3/templates/{template_id}. - `name` string, required: New template name ## Response `200` Successful response - object - `data` TemplateDetailV3: Template detail: its variable schema, the July scene summary and, for authoring workspaces, its composition. - `id` string, required: Unique template identifier - `name` string, required: Template name - `thumbnail_url` string, nullable: URL to the template thumbnail image - `aspect_ratio` string, nullable: Template aspect ratio - `created_at` integer, nullable: Unix timestamp of creation - `updated_at` integer, nullable: Unix timestamp of last update - `variables` object: Variables defined in the template with their current default values, keyed by variable name - `source_video_id` string, nullable: Video the template was created from, when known. Present only for workspaces with access to the template authoring API. - `edit_version` string, nullable: Opaque version of the template returned by this request. Every save of the template's draft or variable set changes it, whether through PUT /v3/templates/{template_id}/variables or the HeyGen editor; renaming or deleting the template does not. Send it back as expected_edit_version on PUT /v3/templates/{template_id}/variables to detect concurrent edits. Present only for workspaces with access to the template authoring API. - `scene_ids` string[]: Scene IDs in template order, as POST /v3/templates/{template_id} accepts them - `scenes` TemplateSceneV3[]: Per-scene summary: the scene id, its script text and the variables it uses. Deprecated in favour of composition, which describes each scene in the same shape as GET /v3/videos/{video_id}/scenes; kept until a published sunset. - `scene_id` string, required: Scene ID, usable in the generate request's scene_ids - `script` string, nullable: Scene script text, with variable placeholders unreplaced - `variables` TemplateSceneVariableRef[]: Variables used in this scene - `name` string, required: Variable name, matching a key in the template's variables - `variable_type` string, required: Variable type: text, image, video, audio, character, or voice - `composition` TemplateComposition: What the template is made of, in the vocabulary of GET /v3/videos/{video_id}/scenes. - `scenes` TemplateScene[]: Scenes in template order, each in the video-scenes shape plus bindings. - `id` string, required: Identifier of this scene within the video. - `background` union: What fills the frame behind this scene's elements. - ColorBackground: A solid colour filling the frame behind the scene's elements. - `type` 'color': Background type discriminator. - `color` string, required: Hex colour, e.g. '#f6f6fc'. - TemplateImageBackground: A frame-filling image; an image variable replaces it. - `id` string, required: Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video. - `type` 'image': Background type discriminator. - `url` string, nullable: URL of the image. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL. - `bindable_as` string[]: Variable types that can be bound to this node. - `variable` string, nullable: Name of the image, video, audio, character or voice variable bound to this node, if any. - `text_variables` string[]: Text variable names appearing as {{placeholders}} in this node's text, in order of first appearance. - TemplateVideoBackground: A frame-filling clip; a video variable replaces it. - `id` string, required: Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video. - `type` 'video': Background type discriminator. - `url` string, nullable: URL of the clip. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL. - `playback` string, nullable: How the clip is reconciled to the scene. Same values as a video element's playback. - `trim` VideoTrim: Seconds trimmed from each end of a clip. - … - `volume` number, nullable: Clip audio volume. 1.0 = source level, 0.0 = silent. - `speed_multiplier` number, nullable: Playback speed multiplier. 2.0 = twice as fast. - `bindable_as` string[]: Variable types that can be bound to this node. - `variable` string, nullable: Name of the image, video, audio, character or voice variable bound to this node, if any. - `text_variables` string[]: Text variable names appearing as {{placeholders}} in this node's text, in order of first appearance. - `elements` union[]: Every element this scene places, in the template's own order. - union - TemplateAvatarElement: An avatar element; a character variable replaces its look. - … - TemplateImageElement: An image element; an image variable replaces its picture. - … - TemplateVideoElement: A video element; a video variable replaces its clip. - … - TemplateTextElement: An on-screen text element; text variables fill its {{placeholders}}. - … - PlaceholderElement: An element this version names but does not describe. Exists so a scene's ``elements`` array is never a filtered view presented as a complete one: a caller iterating it sees every element the scene places. Carries exactly two fields: which element this is, and what kind of thing it is. **Absence of content is not by itself proof that an element is undescribed.** A described category can serialize with nothing but an id and a type when every optional field happens to be unavailable, and one case is reachable today: an image with no usable link carries no ``url``, leaving ``{id, type}``. Read the ``type`` to tell them apart. ``avatar``, ``image``, ``video`` and ``text`` are described, so a bare one of those is a described element missing an optional value rather than an unexpanded node. The ``id`` matters most here. Two masked elements in one scene are otherwise identical on the wire, so without it a caller can see that the scene places two things and nothing else about either. - … - TemplateContainerElement: A group or mask; nothing binds to the container itself, its children carry their own bindings. - … - `script` union[]: This scene's audio sources in order, each one synthesized speech, uploaded audio, or a silence. - union - TemplateTextScriptEntry: Synthesized speech; a voice variable replaces its voice, text variables fill its {{placeholders}}. - … - TemplateAudioScriptEntry: Uploaded audio; an audio variable replaces the recording. - … - SilenceScriptEntry: A held silence, with no words spoken over the scene. - … - `background_audio` TemplateBackgroundAudio[]: Music and sound-effect tracks that play across scenes, with what an audio variable can replace. - `bindable_as` string[]: Variable types that can be bound to this node. - `variable` string, nullable: Name of the image, video, audio, character or voice variable bound to this node, if any. - `text_variables` string[]: Text variable names appearing as {{placeholders}} in this node's text, in order of first appearance. - `id` string, required: Opaque identifier of this track within the template. Stable for the life of the template. - `type` 'audio': Element type discriminator. - `url` string, nullable: URL of the track. Present when the template records a link and, if that link is signed, it is not at or near its deadline. Signed links expire, so download what you need rather than storing the URL. ## Other responses - `400`: Invalid request parameters - `401`: Authentication failed - `403`: Forbidden - `404`: Resource not found - `429`: Rate limit exceeded ## Changes - **2026-11-03** `7dfa5e59b4f5`: 1 info - endpoint added [Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/templates/:template_id/patch.md) --- [API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)