> ## 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. # Create Template from Video > Creates a private template whose scenes, avatars, script and media are copied from one of your videos. The video must carry a draft in the current editor format, which every video generated with POST /v3/videos or saved in the HeyGen editor has; URL-to-Video and older editor videos are refused with template_source_unsupported. The video's render status is not checked. The new template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables or in the HeyGen editor, then generate videos from it with POST /v3/templates/{template_id}. Returns the template detail. ## OpenAPI ````yaml /openapi/external-api.json post /v3/templates 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: post: tags: - Templates summary: Create Template from Video description: >- Creates a private template whose scenes, avatars, script and media are copied from one of your videos. The video must carry a draft in the current editor format, which every video generated with POST /v3/videos or saved in the HeyGen editor has; URL-to-Video and older editor videos are refused with template_source_unsupported. The video's render status is not checked. The new template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables or in the HeyGen editor, then generate videos from it with POST /v3/templates/{template_id}. Returns the template detail. operationId: createTemplateV3 parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTemplateV3Request' responses: '201': description: Created. 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: template_source_unsupported message: >- Video 7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b has no editable draft in the current editor format (draft version 2), so it cannot become a template. param: video_id 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: video_not_found message: Video not found. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '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 security: - ApiKeyAuth: [] - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateTemplateV3Request: additionalProperties: false description: Request body for POST /v3/templates. properties: video_id: description: >- ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point. examples: - 7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b minLength: 1 title: Video Id type: string name: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' default: null description: Template name. Defaults to the source video's title. examples: - Q4 outreach title: Name required: - video_id title: CreateTemplateV3Request 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 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 responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null 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. ````