{ "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": "Webhooks", "description": "Manage webhook endpoints and events" }, { "name": "Lipsync", "description": "Dub or replace audio on existing videos" }, { "name": "Brand", "description": "Brand-related resources \u2014 brand kits (colors, fonts, logos) and brand glossaries (custom term translations)" }, { "name": "HyperFrames", "description": "Render HyperFrames composition zips into video \u2014 separate from /v3/videos" }, { "name": "Models", "description": "" }, { "name": "Filler Word Removal", "description": "" } ], "paths": { "/v1/video_agent/generate": { "post": { "summary": "Create a video from a prompt", "description": "Create a video from a text prompt using HeyGen's Video Agent. This is the recommended way to create videos \u2014 just describe what you want and the agent handles avatar selection, scripting, and production. The video is generated asynchronously \u2014 use the returned video_id to poll status via GET /v2/videos/{video_id}.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": [ "object", "null" ], "default": null }, "data": { "$ref": "#/components/schemas/ExternalCreateVideoAgentSessionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/LegacyAPIError" }, "data": { "type": [ "object", "null" ], "default": null } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/LegacyAPIError" }, "data": { "type": [ "object", "null" ], "default": null } } }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized" }, "data": null } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/LegacyAPIError" }, "data": { "type": [ "object", "null" ], "default": null } } }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests" }, "data": null } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createVideoAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalCreateVideoAgentSessionRequest" } } } }, "x-heygen-required-scopes": [ "video_agent:write" ] } }, "/v3/video-agents": { "post": { "summary": "Create Video Agent Session", "description": "One-shot video generation from a prompt \u2014 agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateVideoAgentResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'prompt' is required and must be 1-10000 characters.", "param": "prompt", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/create-video-agent-session" }, "operationId": "createVideoAgentV3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoAgentRequest" } } } }, "x-heygen-required-scopes": [ "video_agent:write" ] }, "get": { "summary": "List Video Agent Sessions", "description": "Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionListItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-video-agent-sessions" }, "operationId": "listVideoAgentSessions", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page. Obtained from next_token in a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "video_agent:read" ] } }, "/v3/video-agents/styles": { "get": { "summary": "List Video Agent Styles", "description": "Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech').", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StyleItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 50.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-video-agent-styles" }, "operationId": "listVideoAgentStyles", "parameters": [ { "name": "tag", "in": "query", "required": false, "description": "Filter by tag (e.g., 'cinematic', 'retro-tech', 'iconic-artist', 'pop-culture', 'handmade', 'print').", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page. Obtained from next_token in a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "video_agent:read" ] } }, "/v3/brand-glossaries": { "get": { "summary": "List Brand Glossaries", "description": "List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary controls how custom terms are pronounced in generated speech \u2014 for example, speaking \"HeyGen\" as \"hey-jen\" \u2014 and how they are handled when a video is translated: Don't Translate terms kept as-is, and Force Translate terms with a fixed replacement.\n\nPass the returned `brand_glossary_id` when creating a video or translation to apply the glossary. Use GET /v3/brand-glossaries/{brand_glossary_id} to see which terms it remaps, POST /v3/brand-glossaries to create one, and PATCH /v3/brand-glossaries/{brand_glossary_id} to change one.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandGlossaryItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-brand-glossaries" }, "operationId": "listBrandGlossaries", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of brand glossaries to return (1-100). Default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's `next_token`. Omit for the first page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "brand:read" ] }, "post": { "summary": "Create Brand Glossary", "description": "Creates a brand glossary in your workspace. Pass the returned `brand_glossary_id` when creating a video or translation to apply it.\n\n`name` must be unique within your workspace, compared without regard to case; a duplicate returns 409. `terms`, `do_not_translate_terms` and `forced_translations` may each be omitted to create an empty glossary you fill in later with PATCH /v3/brand-glossaries/{brand_glossary_id}.\n\nPronunciations affect generated audio only \u2014 a term keeps its original spelling in captions and subtitles. `do_not_translate_terms` and `forced_translations` apply only when the glossary is used by a translation feature (video translation, Studio script translation, on-screen text translation), in every target language; they have no effect on video generation or text-to-speech requests. Tone settings are managed in the HeyGen web app and cannot be set here.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BrandGlossaryDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'name' must be between 1 and 64 characters.", "param": "name", "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 } } } } }, "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" } } } }, "409": { "description": "Conflict \u2014 either the request conflicts with existing state, or a prior request with this `Idempotency-Key` is still in progress (`request_in_progress`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "conflict": { "summary": "Resource conflict", "value": { "error": { "code": "conflict", "message": "A brand glossary with this name already exists.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/create-brand-glossary" }, "operationId": "createBrandGlossary", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrandGlossaryRequest" } } } }, "x-heygen-required-scopes": [ "brand:write" ] } }, "/v3/brand-kits": { "post": { "summary": "Create Brand Kit", "description": "Creates a brand kit by importing brand assets from a public website, including logos, colors and font files found on the site. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen.\n\nThe kit is assembled in the background: the returned brand_kit_id is usable immediately, but poll GET /v3/brand-kits/{brand_kit_id} every 2 to 5 seconds until its status is 'completed' before relying on its colors, logos or fonts. A website import usually settles in under two minutes.\n\nSend an Idempotency-Key header to make retries safe: without one, a retried request starts a second import of the same site.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateBrandKitResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "URL is not supported", "param": null, "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 } } } } }, "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" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "Your workspace settings do not allow creating brand kits.", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-brand-kit" }, "operationId": "createBrandKit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrandKitRequest" } } } }, "x-heygen-required-scopes": [ "brand:write" ] }, "get": { "summary": "List Brand Kits", "description": "Returns brand kits available in the authenticated user's workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand_kit_id with POST /v3/video-agents to generate on-brand videos.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandKitItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-brand-kits" }, "operationId": "listBrandKits", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page. Obtained from next_token in a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "brand:read" ] } }, "/v3/brand-kits/{brand_kit_id}": { "get": { "summary": "Get Brand Kit", "description": "Returns one brand kit with the colors, logos and fonts it was built from, and which of them play which role. A brand kit imported from a website is assembled in the background: while status is 'loading' the collections and roles are provisional, and they are final once status is 'completed'. Poll every 2 to 5 seconds while status is 'loading'; a website import usually settles in under two minutes, and fonts are typically the last thing to land.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BrandKitDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand kit not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-brand-kit" }, "operationId": "getBrandKit", "parameters": [ { "name": "brand_kit_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand kit identifier" } ], "x-heygen-required-scopes": [ "brand:read" ] }, "patch": { "summary": "Update Brand Kit", "description": "Updates a brand kit's name or its role assignments \u2014 which color plays which part, which logo is the main one, and which font is used for headings and body text. A field you omit is left unchanged.\n\nCreation assigns these roles automatically, with no human in the loop, so this is how a caller corrects them.\n\nEach role object is replaced in full rather than merged: send the roles you want to keep, since a role you leave out of the object is cleared. Send an empty object to clear a role entirely. A cleared role stays cleared and is not recomputed later. Sending null for any field is rejected: omit it to leave it unchanged.\n\nRole edits require an assembled kit and return 409 while status is 'loading' or 'error'. Renaming is allowed at any time. Editing the colors themselves is not supported here yet.\n\nA brand kit shared into your workspace by another workspace is readable but not editable, and returns 403.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BrandKitDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Provide at least one field to update.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand kit not found.", "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": "This brand kit is shared with your workspace and can only be edited by the workspace that owns it.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "brand_kit_not_ready", "message": "This brand kit is still being assembled (status 'loading'). Roles can only be edited once it is 'completed'.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/update-brand-kit" }, "operationId": "updateBrandKit", "parameters": [ { "name": "brand_kit_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand kit identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandKitRequest" } } } }, "x-heygen-required-scopes": [ "brand:write" ] }, "delete": { "summary": "Delete Brand Kit", "description": "Deletes a brand kit, along with the colors, logos and fonts it holds.\n\nThis cannot be undone: there is no way to restore a deleted brand kit through the API. A kit that is still assembling can be deleted at any time.\n\nVideos already generated with the kit are unaffected, since their brand colors were applied at render time. A video agent still configured with a deleted kit will report the id as invalid on its next use.\n\nA brand kit shared into your workspace by another workspace can be read but not deleted, and returns 403.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteBrandKitResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand kit not found.", "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": "This brand kit is shared with your workspace and can only be deleted by the workspace that owns it.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-brand-kit" }, "operationId": "deleteBrandKit", "parameters": [ { "name": "brand_kit_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand kit identifier" } ], "x-heygen-required-scopes": [ "brand:write" ] } }, "/v3/brand-glossaries/{brand_glossary_id}": { "get": { "summary": "Get Brand Glossary", "description": "Returns one brand glossary with its full term list, so you can see exactly which terms are remapped and how. Use this to verify a glossary's contents when a generated video pronounces or translates a term unexpectedly.\n\nPronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its `pronunciation`.\n\nTranslation rules apply only when the glossary is used by a translation feature \u2014 video translation, Studio script translation, and on-screen text translation: `do_not_translate_terms` are kept untranslated in every target language, and `forced_translations` replace their `term` with their `translation` in every target language. They have no effect on video generation or text-to-speech requests; only `terms` applies there. Either list is omitted from the response when the glossary has no rules of that kind. Tone settings are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BrandGlossaryDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand glossary not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-brand-glossary" }, "operationId": "getBrandGlossary", "parameters": [ { "name": "brand_glossary_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand glossary identifier" } ], "x-heygen-required-scopes": [ "brand:read" ] }, "patch": { "summary": "Update Brand Glossary", "description": "Updates a brand glossary. Each field is replaced independently: a field you omit is left untouched, a field you send replaces that value in full, and an empty array removes every entry from that list. There is no way to add a single entry \u2014 read the glossary, append to the list, and send the whole list back.\n\nRenaming to a name another glossary in your workspace already uses returns 409.\n\nA glossary's tone settings are managed in the HeyGen web app and are never modified by this endpoint, so a glossary edited there keeps them through an update made here.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BrandGlossaryDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Provide at least one field to update.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand glossary not found.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "conflict", "message": "A brand glossary with this name already exists.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/update-brand-glossary" }, "operationId": "updateBrandGlossary", "parameters": [ { "name": "brand_glossary_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand glossary identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandGlossaryRequest" } } } }, "x-heygen-required-scopes": [ "brand:write" ] }, "delete": { "summary": "Delete Brand Glossary", "description": "Deletes a brand glossary.\n\nThis cannot be undone: there is no way to restore a deleted brand glossary through the API.\n\nThe glossary stops being returned by this API at once, and stops applying: neither its pronunciation terms nor its translation rules affect anything generated afterwards.\n\nVideos already generated with the glossary are unaffected, since their audio was synthesized at the time. A video or translation still configured with a deleted glossary keeps working rather than failing.", "tags": [ "Brand" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteBrandGlossaryResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Brand glossary not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-brand-glossary" }, "operationId": "deleteBrandGlossary", "parameters": [ { "name": "brand_glossary_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique brand glossary identifier" } ], "x-heygen-required-scopes": [ "brand:write" ] } }, "/v3/avatars": { "post": { "summary": "Create Avatar", "description": "Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At least one file source is required: provide image, video, or consent_video.", "param": "files", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-avatar" }, "operationId": "createAvatar", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarRequestBody" } } } }, "x-heygen-required-scopes": [ "avatars:write" ] }, "get": { "summary": "List Avatar Groups", "description": "Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvatarGroupItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 50.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-avatar-groups" }, "operationId": "listAvatarGroups", "parameters": [ { "name": "ownership", "in": "query", "required": false, "description": "Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all.", "schema": { "type": "string", "enum": [ "public", "private" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return per page (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "avatars:read" ] } }, "/v3/avatar-realtime": { "post": { "summary": "Create Avatar Realtime Session", "description": "Start a low-latency streaming avatar session and return a `stream_id`. Three modes, selected by the `type` discriminator: `tts` (speak a fixed script), `audio` (drive lip-sync from a pre-existing audio asset), and `text_stream` (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime/{stream_id}/text \u2014 e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/{stream_id} for the session status and HLS playback URL.", "tags": [ "Avatar Realtime" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarRealtimeResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid 'type'. Must be one of: tts, audio, text_stream.", "param": "type", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createAvatarRealtimeSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarRealtimeRequestBody" } } } }, "x-heygen-required-scopes": [ "avatar_realtime:write" ] } }, "/v3/avatar-realtime/{stream_id}": { "get": { "summary": "Get Avatar Realtime Session", "description": "Get the status of a streaming avatar session. `status` is one of `pending` (workflow starting), `streaming` (the `hls_url` is live), `completed` (finished \u2014 `end_reason` describes how), or `error` (`error_message` describes the failure). Poll this after POST /v3/avatar-realtime until `hls_url` is present.", "tags": [ "Avatar Realtime" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarRealtimeStatusResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Streaming session not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getAvatarRealtimeSession", "parameters": [ { "name": "stream_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Streaming session identifier returned by POST /v3/avatar-realtime." } ], "x-heygen-required-scopes": [ "avatar_realtime:read" ] } }, "/v3/avatar-realtime/{stream_id}/words": { "get": { "summary": "Stream Avatar Realtime Word Timestamps", "description": "Open a Server-Sent Events (`text/event-stream`) stream of per-word timestamps for a session. Each `data:` frame is a `WordBatch` (`{\"words\": [{\"word\", \"start\", \"end\"}, ...]}`); times are in seconds from the start of the streamed audio (matching OpenAI Whisper and ElevenLabs). Punctuation is emitted as its own word event. Batches are capped at ~1s of audio or 10 words, whichever comes first. Late subscribers receive the full session history; completed sessions are served from a durable snapshot. The stream ends with a single `event: end` frame carrying a `WordsEndEvent`.", "tags": [ "Avatar Realtime" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Server-Sent Events stream (`text/event-stream`). Each `data:` frame carries one `WordBatch` JSON payload; the stream terminates with a single `event: end` frame whose data is a `WordsEndEvent`.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/WordBatch" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Streaming session not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "streamAvatarRealtimeWords", "parameters": [ { "name": "stream_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Streaming session identifier returned by POST /v3/avatar-realtime." } ], "x-heygen-required-scopes": [ "avatar_realtime:read" ] } }, "/v3/avatar-realtime/{stream_id}/text": { "post": { "summary": "Append Avatar Realtime Text", "description": "Append a text delta to a session created with `type: text_stream`. Send fragments as they become available (e.g. tokens streamed from an upstream LLM); the avatar speaks them in order. Set `final: true` on the last delta to close input \u2014 further appends to a closed stream return 410. Returns the total bytes buffered so far.", "tags": [ "Avatar Realtime" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppendTextDeltaResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'delta' must be non-empty unless final=true.", "param": "delta", "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "appendAvatarRealtimeText", "parameters": [ { "name": "stream_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Streaming session identifier returned by POST /v3/avatar-realtime." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendTextDeltaRequest" } } } }, "x-heygen-required-scopes": [ "avatar_realtime:write" ] } }, "/v3/avatar-realtime/{stream_id}/cancel": { "post": { "summary": "Cancel Avatar Realtime Session", "description": "Cancel a running streaming session. Idempotent: `cancelled` is true when this request initiated the cancellation, or false when the session was already terminal (completed, failed, or previously cancelled).", "tags": [ "Avatar Realtime" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CancelAvatarRealtimeResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Streaming session not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "cancelAvatarRealtimeSession", "parameters": [ { "name": "stream_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Streaming session identifier returned by POST /v3/avatar-realtime." } ], "x-heygen-required-scopes": [ "avatar_realtime:write" ] } }, "/v1/audio/text_to_speech": { "post": { "summary": "Generate speech audio from text", "description": "Synthesize speech audio from text using a specified voice. Returns a URL to the generated audio file along with duration and optional word-level timestamps.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TextToSpeechResponseData" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'voice_id' is required.", "param": "voice_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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "textToSpeech", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToSpeechRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] } }, "/v1/audio/voices": { "get": { "summary": "List voices for text-to-speech", "description": "List voices available for TTS generation with cursor-based pagination. Filter by type (public/private), language, and gender.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudioVoiceItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listAudioVoices", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Voice type: 'public' for the shared library or 'private' for your cloned voices.", "schema": { "type": "string", "enum": [ "public", "private" ], "default": "public" } }, { "name": "language", "in": "query", "required": false, "description": "Filter by language (e.g. 'English').", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "Filter by gender ('male' or 'female').", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "voices:read" ] } }, "/v3/audio/sounds": { "get": { "summary": "Search audio (music or sound effects)", "description": "Semantically search the audio catalog by natural-language description \u2014 set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination.", "tags": [ "Audio" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudioSoundItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'query' is required.", "param": "query", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/search-audio-music-or-sound-effects" }, "operationId": "searchAudioSounds", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Natural-language description of the audio you want, e.g. 'upbeat lofi hip-hop' or 'tense cinematic riser'. Results are ranked by semantic similarity to this text.", "schema": { "type": "string", "minLength": 1, "maxLength": 5000 } }, { "name": "type", "in": "query", "required": false, "description": "Audio content type to search: 'music' (background-music catalog) or 'sound_effects' (SFX catalog). Defaults to 'music'.", "schema": { "type": "string", "enum": [ "music", "sound_effects" ], "default": "music" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "min_score", "in": "query", "required": false, "description": "Minimum semantic similarity score (0-1). Tracks scoring below this are omitted.", "schema": { "type": "number", "minimum": 0.0, "maximum": 1.0, "default": 0.7 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page, taken from 'next_token' in a prior response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "assets:read" ] } }, "/v3/voices/speech": { "post": { "summary": "Generate Speech", "description": "Synthesize speech audio from text using a specified voice. The voice must support the starfish engine \u2014 use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5\u20132.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TextToSpeechResponseData" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'voice_id' is required.", "param": "voice_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 } } } } }, "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" } } } }, "502": { "description": "Upstream dependency failed \u2014 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": "voice_provider_error", "message": "Our voice service is temporarily unavailable. Please try again in a moment.", "param": null, "doc_url": null } } } } }, "504": { "description": "Upstream dependency timed out \u2014 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": "gateway_timeout", "message": "Our voice service is temporarily unavailable. Please try again in a moment.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/generate-speech" }, "operationId": "createSpeechV3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToSpeechRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] } }, "/v3/voices": { "post": { "summary": "Design a Voice", "description": "Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DesignVoiceResponseData" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'prompt' is required.", "param": "prompt", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/design-a-voice" }, "operationId": "designVoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignVoiceRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] }, "get": { "summary": "List Voices", "description": "Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudioVoiceItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-voices" }, "operationId": "listVoicesV3", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Voice type: 'public' for the shared library or 'private' for your cloned voices.", "schema": { "type": "string", "enum": [ "public", "private" ], "default": "public" } }, { "name": "engine", "in": "query", "required": false, "description": "Filter by voice engine (e.g. 'starfish'). When set, only voices compatible with that engine are returned.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Filter by language (e.g. 'English').", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "Filter by gender ('male' or 'female').", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "voices:read" ] } }, "/v3/voices/clone": { "post": { "summary": "Clone a Voice", "description": "Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is 'complete'. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceCloneCreateV3Response" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_limit_reached", "message": "Voice clone limit reached (10). Delete unused clones or contact support to increase your limit." } } } } }, "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 } } } } }, "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" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "plan_upgrade_required", "message": "Voice cloning is not available on the free tier. Please upgrade your plan." } } } } } }, "x-mint": { "href": "/reference/clone-a-voice" }, "operationId": "cloneVoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVoiceCloneV3Request" } } } }, "x-heygen-required-scopes": [ "voices:write" ] } }, "/v3/models/audio/voices": { "post": { "summary": "Create or Retrain an Audio Voice", "description": "Creates a model-backed audio voice from one or more recordings, or retrains an existing professional voice when `voice_id` is supplied. Retraining requires only `voice_id` and source audio and retains the existing voice's ID, name, language, and mode. The voice is `PENDING` and unavailable for inference while either operation runs. Poll `GET /v3/models/audio/voices/{voice_id}` until its status becomes `ACTIVE` or `FAILED`. `Idempotency-Key` is optional; omitting it means repeated creation requests create separate voices. New voices require an unoccupied professional-voice slot. Each purchased slot provides five pooled trainings per monthly billing period, including initial training; failed trainings do not consume the allowance.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateModelAudioVoiceResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_audio": { "summary": "Source audio does not satisfy training requirements", "value": { "error": { "code": "invalid_parameter", "message": "The supplied recordings must contain at least 20 minutes of audio in total.", "param": "audio", "doc_url": null } } }, "voice_capacity": { "summary": "All purchased professional-voice slots are occupied", "value": { "error": { "code": "resource_limit_reached", "message": "No professional voice slots are available. Purchase another slot, or delete a voice after its training finishes." } } }, "training_allowance": { "summary": "The monthly professional-voice training allowance is exhausted", "value": { "error": { "code": "resource_limit_reached", "message": "The monthly professional voice training allowance is exhausted. Try again in the next billing period or purchase another slot." } } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "Professional voice source audio ingestion is temporarily unavailable. Retry with the same Idempotency-Key.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 either the request conflicts with existing state, or a prior request with this `Idempotency-Key` is still in progress (`request_in_progress`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "conflict": { "summary": "Resource conflict", "value": { "error": { "code": "resource_not_ready", "message": "The professional voice must be ACTIVE and have no training in progress before it can be retrained.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/create-or-retrain-an-audio-voice" }, "operationId": "createModelAudioVoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelAudioVoiceRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] }, "get": { "summary": "List Audio Voices", "description": "Returns the model-backed audio voices in the caller's workspace, ordered newest first. Use `limit` and `token` to retrieve additional pages.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelAudioVoiceResponse" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid pagination token", "param": "token", "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 } } } } }, "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" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/list-audio-voices" }, "operationId": "listModelAudioVoices", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of voices to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token returned by a previous request.", "schema": { "type": "string", "minLength": 1 } } ], "x-heygen-required-scopes": [ "voices:read" ] } }, "/v3/models/audio/tts": { "post": { "summary": "Generate Speech", "description": "Generates speech using the voice identified by `voice_id` and returns a URL for one completed mono PCM16 WAV file at 44.1 kHz. The request remains open until synthesis and output assembly finish. The voice must be an ACTIVE professional voice. Rate limit: 30 requests per minute per workspace member.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateSpeechResponseData" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_parameter": { "summary": "Unsupported language", "value": { "error": { "code": "invalid_parameter", "message": "language is not a supported language.", "param": "language", "doc_url": null } } }, "voice_expired": { "summary": "Professional voice clone over the workspace slot limit", "value": { "error": { "code": "voice_expired", "message": "Professional voice clone 'voice-1' expired because this workspace exceeded its professional voice clone slot limit of 2. Purchase more professional voice clone slots, or delete other professional voice clones to bring the workspace within its limit, then try again.", "param": null, "doc_url": null } } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "unauthorized", "message": "API key or OAuth token required", "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" } } } }, "402": { "description": "Payment required \u2014 `error.code` is one of: `insufficient_credit`, `plan_upgrade_required`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "insufficient_credit": { "summary": "Insufficient credits in the selected billing wallet", "value": { "error": { "code": "insufficient_credit", "message": "Insufficient credits. Please upgrade your plan or purchase additional credits.", "param": null, "doc_url": null } } }, "plan_upgrade_required": { "summary": "OAuth speech requires a paid plan", "value": { "error": { "code": "plan_upgrade_required", "message": "Professional voice speech through OAuth requires a paid plan. Please upgrade your subscription.", "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": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } }, "502": { "description": "Upstream dependency failed \u2014 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": "voice_provider_error", "message": "The upstream voice provider failed. Retry the request.", "param": null, "doc_url": null } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "Voice inference is temporarily busy. Retry the request.", "param": null, "doc_url": null } } } } }, "504": { "description": "Upstream dependency timed out \u2014 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": "gateway_timeout", "message": "The upstream voice provider timed out. Retry the request.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `voice_not_ready`, `voice_training_failed`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "voice_not_ready": { "summary": "Voice training is not complete", "value": { "error": { "code": "voice_not_ready", "message": "The professional voice clone is not ready for inference.", "param": null, "doc_url": null } } }, "voice_training_failed": { "summary": "Voice training failed", "value": { "error": { "code": "voice_training_failed", "message": "The professional voice clone failed training.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/generate-model-speech" }, "operationId": "generateModelSpeech", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpeechRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] } }, "/v3/models/audio/tts/stream": { "post": { "summary": "Stream Speech", "description": "Generates speech as Server-Sent Events. Audio events contain ordered base64-encoded standalone WAV parts; alignment events are included only when `with_timestamps` is true. A clean stream ends with `data: [DONE]`. The voice identified by `voice_id` must be an ACTIVE professional voice. Rate limit: 30 requests per minute per workspace member.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Server-Sent Events stream. Each `data:` frame contains an audio, alignment, or terminal error event; a clean stream terminates with `data: [DONE]`.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SpeechStreamEvent" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_parameter": { "summary": "Unsupported language", "value": { "error": { "code": "invalid_parameter", "message": "language is not a supported language.", "param": "language", "doc_url": null } } }, "voice_expired": { "summary": "Professional voice clone over the workspace slot limit", "value": { "error": { "code": "voice_expired", "message": "Professional voice clone 'voice-1' expired because this workspace exceeded its professional voice clone slot limit of 2. Purchase more professional voice clone slots, or delete other professional voice clones to bring the workspace within its limit, then try again.", "param": null, "doc_url": null } } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "unauthorized", "message": "API key or OAuth token required", "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" } } } }, "402": { "description": "Payment required \u2014 `error.code` is one of: `insufficient_credit`, `plan_upgrade_required`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "insufficient_credit": { "summary": "Insufficient credits in the selected billing wallet", "value": { "error": { "code": "insufficient_credit", "message": "Insufficient credits. Please upgrade your plan or purchase additional credits.", "param": null, "doc_url": null } } }, "plan_upgrade_required": { "summary": "OAuth speech requires a paid plan", "value": { "error": { "code": "plan_upgrade_required", "message": "Professional voice speech through OAuth requires a paid plan. Please upgrade your subscription.", "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": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } }, "502": { "description": "Upstream dependency failed \u2014 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": "voice_provider_error", "message": "The upstream voice provider failed. Retry the request.", "param": null, "doc_url": null } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "Voice inference is temporarily busy. Retry the request.", "param": null, "doc_url": null } } } } }, "504": { "description": "Upstream dependency timed out \u2014 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": "gateway_timeout", "message": "The upstream voice provider timed out. Retry the request.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `voice_not_ready`, `voice_training_failed`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "voice_not_ready": { "summary": "Voice training is not complete", "value": { "error": { "code": "voice_not_ready", "message": "The professional voice clone is not ready for inference.", "param": null, "doc_url": null } } }, "voice_training_failed": { "summary": "Voice training failed", "value": { "error": { "code": "voice_training_failed", "message": "The professional voice clone failed training.", "param": null, "doc_url": null } } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/stream-speech" }, "operationId": "streamModelSpeech", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamSpeechRequest" } } } }, "x-heygen-required-scopes": [ "voices:write" ] } }, "/v3/models/audio/voices/{voice_id}": { "get": { "summary": "Get an Audio Voice", "description": "Returns one caller-owned model-backed audio voice and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ModelAudioVoiceResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-an-audio-voice" }, "operationId": "getModelAudioVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique voice identifier" } ], "x-heygen-required-scopes": [ "voices:read" ] }, "delete": { "summary": "Delete an Audio Voice", "description": "Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads, but a voice cannot be deleted while its status is `PENDING`. Wait for training to finish and retry. Repeating a successful deletion returns the same successful response.", "tags": [ "Models" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteModelAudioVoiceResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "The professional voice cloning API is not enabled for this account.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_ready", "message": "A professional voice cannot be deleted while training is in progress. Wait until its status is ACTIVE or FAILED, then retry.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-an-audio-voice" }, "operationId": "deleteModelAudioVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique voice identifier" } ], "x-heygen-required-scopes": [ "voices:write" ] } }, "/v3/voices/{voice_id}": { "get": { "summary": "Get Voice", "description": "Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceDetailV3" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "voice_not_found", "message": "Voice not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-voice" }, "operationId": "getVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique voice identifier" } ], "x-heygen-required-scopes": [ "voices:read" ] }, "delete": { "summary": "Delete a Voice", "description": "Deletes a voice clone owned by the caller. The voice must not be in use by any template. The voice is removed from your voice list and no longer counts against your voice clone limit. Deleting an already-deleted or unknown voice returns 404 `voice_not_found` (not 200) \u2014 a delete-then-list flow should treat that 404 as success, not an error.", "tags": [ "Voices" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceDeleteV3Response" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "voice_not_found", "message": "Voice not found.", "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": "Voice is associated with an active template, please change the voice used in that template first before deleting this voice", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-a-voice" }, "operationId": "deleteVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique voice identifier" } ], "x-heygen-required-scopes": [ "voices:write" ] } }, "/v2/videos": { "post": { "summary": "Create an avatar video", "description": "Create a video from a specific avatar or image with full control over avatar, voice, and script. Use this only when you need explicit control over avatar selection and scripting. For most video creation, use the create_video_agent tool instead which handles these choices automatically. Supports photo avatars, video avatars (digital twins), and direct image input. The video is generated asynchronously \u2014 poll status via GET /v2/videos/{video_id}.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarVideoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_parameter": { "summary": "Invalid visual source", "value": { "error": { "code": "invalid_parameter", "message": "Exactly one visual source required: avatar_id, image_url, or image_asset_id.", "param": "avatar_id", "doc_url": null } } }, "avatar_not_usable": { "summary": "Avatar cannot be used", "value": { "error": { "code": "avatar_not_usable", "message": "This avatar cannot be used because it did not pass content moderation.", "param": null, "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 } } } } }, "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" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_ready", "message": "This avatar is still processing. Wait for avatar creation to complete, then try again.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createAvatarVideo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarVideoRequest" } } } }, "x-heygen-required-scopes": [ "videos:write" ] }, "get": { "summary": "List videos", "description": "List videos in the account with pagination and optional filtering.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listVideos", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "required": false, "description": "Filter videos by folder ID", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": false, "description": "Filter videos by title substring", "schema": { "type": "string", "minLength": 1 } } ], "x-heygen-required-scopes": [ "videos:read" ] } }, "/v2/videos/{video_id}": { "get": { "summary": "Get video details", "description": "Get detailed information about a video including status, URLs, and metadata. Supports both generated and translated videos.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getVideo", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video identifier" } ], "x-heygen-required-scopes": [ "videos:read" ] }, "delete": { "summary": "Delete a video", "description": "Permanently delete a video. Supports both generated and translated videos.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteVideoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "deleteVideo", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video identifier" } ], "x-heygen-required-scopes": [ "videos:write" ] } }, "/v3/videos": { "post": { "summary": "Create Video", "description": "Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarVideoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_parameter": { "summary": "Invalid visual source", "value": { "error": { "code": "invalid_parameter", "message": "Exactly one visual source required: avatar_id, image_url, or image_asset_id.", "param": "avatar_id", "doc_url": null } } }, "avatar_not_usable": { "summary": "Avatar cannot be used", "value": { "error": { "code": "avatar_not_usable", "message": "This avatar cannot be used because it did not pass content moderation.", "param": null, "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 } } } } }, "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" } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `resource_not_ready`, `request_in_progress`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "resource_not_ready": { "summary": "Avatar is still processing", "value": { "error": { "code": "resource_not_ready", "message": "This avatar is still processing. Wait for avatar creation to complete, then try again.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/create-video" }, "operationId": "createVideo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoV3RequestBody" } } } }, "x-heygen-required-scopes": [ "videos:write" ] }, "get": { "summary": "List Videos", "description": "Returns a paginated list of all videos in the account. Filterable by folder_id or title substring.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-videos" }, "operationId": "listVideosV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "required": false, "description": "Filter videos by folder ID", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": false, "description": "Filter videos by title substring", "schema": { "type": "string", "minLength": 1 } } ], "x-heygen-required-scopes": [ "videos:read" ] } }, "/v3/videos/{video_id}": { "get": { "summary": "Get Video", "description": "Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video" }, "operationId": "getVideoV3", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video identifier" } ], "x-heygen-required-scopes": [ "videos:read" ] }, "delete": { "summary": "Delete Video", "description": "Permanently deletes a video and its associated files. This action cannot be undone.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteVideoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-video" }, "operationId": "deleteVideoV3", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video identifier" } ], "x-heygen-required-scopes": [ "videos:write" ] } }, "/v3/videos/{video_id}/scenes": { "get": { "summary": "Get Video Scenes", "description": "Returns the video's scenes together with the video-level context needed to use them. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated. The response includes an opaque `edit_version` for optimistic concurrency. A video whose editor document is still being prepared returns `409 resource_not_ready`; retry after the video advances.\n\nEach scene splits by the role a thing plays: `background` fills the frame, `elements` are placed within it, and `script` is the audio delivered over it. A whole-frame image or clip lands in `background`, so code that reads only `elements` misses it.\n\nElement types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in `elements`, so the count is always truthful, but only `avatar`, `image` and `video` are described in full; `group` and `mask` carry their children; the rest carry an `id` and a `type` and nothing more.\n\n**What this does not describe.** A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which this version does not return.", "tags": [ "Videos" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": [ "object", "null" ], "default": null }, "data": { "$ref": "#/components/schemas/VideoScenesResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video not found.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_ready", "message": "The editor document is not ready yet. Retry after the video has finished preparing.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video-scenes" }, "operationId": "getVideoScenesV3", "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video identifier" } ], "x-heygen-required-scopes": [ "videos:read" ] } }, "/v3/templates": { "get": { "summary": "List Templates", "description": "Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateListItemV3" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid pagination token", "param": "token", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-templates" }, "operationId": "listTemplatesV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of templates to return per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token from a previous response's next_token", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "templates:read" ] } }, "/v3/templates/{template_id}": { "get": { "summary": "Get Template", "description": "Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "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" } } } } } }, "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 } } } } }, "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" } } } }, "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 } } } } } }, "x-mint": { "href": "/reference/get-template" }, "operationId": "getTemplateV3", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique template identifier" } ], "x-heygen-required-scopes": [ "templates:read" ] }, "post": { "summary": "Generate Video from Template", "description": "Generates a video from the template by replacing its variables (text, image, video, audio, character, voice). Use scene_ids to select, reorder, or repeat scenes \u2014 scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll GET /v3/videos/{video_id} or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video's current state.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Variable 'company_name' is not defined in this template.", "param": "variables", "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 } } } } }, "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" } } } }, "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 } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/generate-video-from-template" }, "operationId": "generateFromTemplateV3", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique template identifier" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFromTemplateV3Request" } } } }, "x-heygen-required-scopes": [ "templates:read", "videos:write" ] } }, "/v3/background-removals": { "post": { "summary": "Create Background Removal", "description": "Submit a video to remove its background. Returns the created job; runs asynchronously, so poll Get Background Removal with the returned id. Once completed, the job carries presigned download URLs for the requested layers: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), and 'background' (the scene with the subject removed). Idempotency is opt-in via the request body's `request_id` field: re-sending the same `request_id` returns the *original* job (same `id`, same charge) without creating a new one. The HTTP `Idempotency-Key` header is *not* honored \u2014 see `request_id` for the supported contract.", "tags": [ "Background Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackgroundRemovalJob" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-excluded": true, "operationId": "createBackgroundRemoval", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBackgroundRemovalRequest" } } } }, "x-heygen-required-scopes": [ "background_removal:write" ] }, "get": { "summary": "List Background Removals", "description": "Returns a paginated list of background removal jobs for the account, newest first.", "tags": [ "Background Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundRemovalJob" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-excluded": true, "operationId": "listBackgroundRemovals", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of jobs to return (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "background_removal:read" ] } }, "/v3/background-removals/{job_id}": { "get": { "summary": "Get Background Removal", "description": "Returns a background removal job including its status and, once completed, presigned download URLs for the produced layers.", "tags": [ "Background Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackgroundRemovalJob" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Background removal job not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-excluded": true, "operationId": "getBackgroundRemoval", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Background removal job id" } ], "x-heygen-required-scopes": [ "background_removal:read" ] }, "delete": { "summary": "Delete Background Removal", "description": "Soft-deletes a background removal job.", "tags": [ "Background Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackgroundRemovalDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Background removal job not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-excluded": true, "operationId": "deleteBackgroundRemoval", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Background removal job id" } ], "x-heygen-required-scopes": [ "background_removal:write" ] } }, "/v2/video_translate": { "post": { "summary": "Create video translation", "description": "Translate a video into one or more target languages. The translation runs asynchronously \u2014 the response contains a video_translate_id which can be used with get_video to poll status and retrieve the download URL when complete.\n\nUse list_video_translate_languages to discover supported language codes before calling this endpoint.\n\nKey parameters:\n- video_url (required): URL of the source video to translate.\n- output_language: Single target language code. Mutually exclusive with output_languages.\n- output_languages: Array of target language codes for batch translation. Mutually exclusive with output_language.\n- mode: \"speed\" (default, faster) or \"precision\" (higher quality, uses avatar inference).\n- brand_glossary_id (preferred) / brand_voice_id (legacy alias): Brand glossary ID for custom term translations (e.g. translate 'Reformer' as Pilates equipment, not as a political activist). Discover IDs via GET /v3/brand-glossaries.\n- stock_voice_config: Use a preset stock voice instead of recreating the original speaker's voice (set use_stock_voice=true). Enterprise feature, available for selected accounts and languages by request.\n- srt_url / srt_role: Custom subtitle file.\n- fps_mode: Frame rate mode (\"vfr\", \"cfr\", \"passthrough\"). Only valid when audio_url is provided.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslateCreateResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'video_url' is required.", "param": "video_url", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createVideoTranslate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPVideoTranslateCreateRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] } }, "/v2/video_translate/target_languages": { "get": { "summary": "List video translate languages", "description": "List all supported target language codes for video translation. Call this before create_video_translate to validate language choices.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListTargetLanguageResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listVideoTranslateLanguages", "x-heygen-required-scopes": [ "translations:read" ] } }, "/v2/video_translate/caption": { "get": { "summary": "Get video translate caption", "description": "Get the caption file (SRT or VTT format) for a completed video translation. The translation must have status \"completed\" \u2014 use get_video to check status first. Requires enable_caption=true when creating the translation.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslateCaptionGetResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'video_translate_id' is required.", "param": "video_translate_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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getVideoTranslateCaption", "parameters": [ { "name": "video_translate_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "caption_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "vtt", "srt" ] } } ], "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/video-translations": { "post": { "summary": "Create Video Translation", "description": "Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslationCreateResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'video_url' is required.", "param": "video_url", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-video-translation" }, "operationId": "createVideoTranslationV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoTranslationRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] }, "get": { "summary": "List Video Translations", "description": "Returns a paginated list of all video translation jobs in the account.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoTranslationDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-video-translations" }, "operationId": "listVideoTranslationsV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/video-translations/{video_translation_id}": { "get": { "summary": "Get Video Translation", "description": "Returns details for a translation job including status, output language, video_url, and failure info if applicable.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslationDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video translation not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video-translation" }, "operationId": "getVideoTranslationV3", "parameters": [ { "name": "video_translation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video translation identifier" } ], "x-heygen-required-scopes": [ "translations:read" ] }, "patch": { "summary": "Update Video Translation", "description": "Updates the display title of a video translation job.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslationDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At least one field must be provided for update.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video translation not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/update-video-translation" }, "operationId": "updateVideoTranslationV3", "parameters": [ { "name": "video_translation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video translation identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVideoTranslationRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] }, "delete": { "summary": "Delete Video Translation", "description": "Permanently deletes a video translation and its associated files. This action cannot be undone.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslationDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Video translation not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-video-translation" }, "operationId": "deleteVideoTranslationV3", "parameters": [ { "name": "video_translation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video translation identifier" } ], "x-heygen-required-scopes": [ "translations:write" ] } }, "/v3/video-translations/languages": { "get": { "summary": "List Supported Translation Languages", "description": "Returns all supported target language names for video translation.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoTranslationLanguagesResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-supported-translation-languages" }, "operationId": "listVideoTranslationLanguagesV3", "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/video-translations/proofreads": { "post": { "summary": "Create Proofread Session", "description": "Creates a proofread session that extracts editable subtitles from a video before final rendering.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateProofreadResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'video_url' is required.", "param": "video_url", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/create-proofread-session" }, "operationId": "createProofreadV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProofreadRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] }, "get": { "summary": "List Proofread Sessions", "description": "Returns a paginated list of all proofread sessions in the workspace, newest first.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProofreadDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/list-proofread-sessions" }, "operationId": "listProofreadsV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/video-translations/proofreads/{proofread_id}": { "get": { "summary": "Get Proofread Session", "description": "Returns the status and details of a proofread session.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProofreadDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Proofread not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/get-proofread-session" }, "operationId": "getProofreadV3", "parameters": [ { "name": "proofread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique proofread identifier" } ], "x-heygen-required-scopes": [ "translations:read" ] }, "delete": { "summary": "Delete Proofread Session", "description": "Deletes a proofread session, removing it from listings and from the workspace's projects. Requires an account role of Creator or higher. This action cannot be undone.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProofreadDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Proofread not found.", "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": "Forbidden", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/delete-proofread-session" }, "operationId": "deleteProofreadV3", "parameters": [ { "name": "proofread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique proofread identifier" } ], "x-heygen-required-scopes": [ "translations:write" ] } }, "/v3/video-translations/proofreads/{proofread_id}/srt": { "get": { "summary": "Download Proofread SRT", "description": "Returns presigned download URLs for the edited and original SRT files of a completed proofread session.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DownloadSRTResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Proofread not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/download-proofread-srt" }, "operationId": "downloadProofreadSrtV3", "parameters": [ { "name": "proofread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique proofread identifier" } ], "x-heygen-required-scopes": [ "translations:read" ] }, "put": { "summary": "Upload Proofread SRT", "description": "Replaces the proofread subtitles with an edited SRT file.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProofreadDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'srt_content' is required.", "param": "srt_content", "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Proofread not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/upload-proofread-srt" }, "operationId": "uploadProofreadSrtV3", "parameters": [ { "name": "proofread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique proofread identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSRTRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] } }, "/v3/video-translations/proofreads/{proofread_id}/generate": { "post": { "summary": "Generate Video from Proofread", "description": "Starts final video generation using the approved subtitles from a proofread session.", "tags": [ "Video Translate" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateVideoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Proofread not found.", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-action": true, "x-mint": { "href": "/reference/generate-video-from-proofread" }, "operationId": "generateFromProofreadV3", "parameters": [ { "name": "proofread_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique proofread identifier" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateVideoRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] } }, "/v3/lipsyncs": { "post": { "summary": "Create Lipsync", "description": "Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync.", "tags": [ "Lipsync" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LipsyncCreateResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'video_url' is required.", "param": "video_url", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-lipsync" }, "operationId": "createLipsyncV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLipsyncRequest" } } } }, "x-heygen-required-scopes": [ "lipsync:write" ] }, "get": { "summary": "List Lipsyncs", "description": "Returns a paginated list of all lipsync jobs in the account.", "tags": [ "Lipsync" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LipsyncDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-lipsyncs" }, "operationId": "listLipsyncsV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "lipsync:read" ] } }, "/v3/lipsyncs/{lipsync_id}": { "get": { "summary": "Get Lipsync", "description": "Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.", "tags": [ "Lipsync" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LipsyncDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Lipsync not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-lipsync" }, "operationId": "getLipsyncV3", "parameters": [ { "name": "lipsync_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique lipsync identifier" } ], "x-heygen-required-scopes": [ "lipsync:read" ] }, "patch": { "summary": "Update Lipsync", "description": "Updates the display title of a lipsync job.", "tags": [ "Lipsync" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LipsyncDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At least one field must be provided for update.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Lipsync not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/update-lipsync" }, "operationId": "updateLipsyncV3", "parameters": [ { "name": "lipsync_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique lipsync identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLipsyncRequest" } } } }, "x-heygen-required-scopes": [ "lipsync:write" ] }, "delete": { "summary": "Delete Lipsync", "description": "Permanently deletes a lipsync job and its associated files. This action cannot be undone.", "tags": [ "Lipsync" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LipsyncDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Lipsync not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-lipsync" }, "operationId": "deleteLipsyncV3", "parameters": [ { "name": "lipsync_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique lipsync identifier" } ], "x-heygen-required-scopes": [ "lipsync:write" ] } }, "/v3/hyperframes/renders": { "post": { "summary": "Create HyperFrames Render", "description": "Renders a HyperFrames composition (an HTML+JS+assets project bundled as a .zip) into a video. Submit the project via `url`, `asset_id` (pre-uploaded via POST /v3/assets), or inline `base64`. Returns a `render_id` to poll via GET /v3/hyperframes/renders/{render_id}.", "tags": [ "HyperFrames" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateHyperframesRenderResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Composition zip is invalid or missing index.html.", "param": "project", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/create-hyperframes-render" }, "operationId": "createHyperframesRenderV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHyperframesRenderRequest" } } } }, "x-heygen-required-scopes": [ "hyperframes:write" ] }, "get": { "summary": "List HyperFrames Renders", "description": "Returns a cursor-paginated list of HyperFrames renders in the account, newest first.", "tags": [ "HyperFrames" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HyperframesRenderDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/list-hyperframes-renders" }, "operationId": "listHyperframesRendersV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "hyperframes:read" ] } }, "/v3/hyperframes/renders/{render_id}": { "get": { "summary": "Get HyperFrames Render", "description": "Returns full details for a single HyperFrames render, including status and signed video_url when complete.", "tags": [ "HyperFrames" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HyperframesRenderDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "HyperFrames render not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/get-hyperframes-render" }, "operationId": "getHyperframesRenderV3", "parameters": [ { "name": "render_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique HyperFrames render identifier" } ], "x-heygen-required-scopes": [ "hyperframes:read" ] }, "delete": { "summary": "Delete HyperFrames Render", "description": "Soft-deletes a HyperFrames render. Subsequent GETs return 404.", "tags": [ "HyperFrames" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteHyperframesRenderResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "HyperFrames render not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/delete-hyperframes-render" }, "operationId": "deleteHyperframesRenderV3", "parameters": [ { "name": "render_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique HyperFrames render identifier" } ], "x-heygen-required-scopes": [ "hyperframes:write" ] } }, "/v3/custom-agents": { "get": { "summary": "List Custom Agents", "description": "Returns the installed custom agents. Each entry carries id, name, description, and the internal workflow_type.", "tags": [ "Custom Agents" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomAgentListResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listCustomAgents", "x-heygen-required-scopes": [ "custom_agents:read" ] } }, "/v3/custom-agents/{agent_id}": { "get": { "summary": "Get Custom Agent", "description": "Returns metadata for a single custom agent.", "tags": [ "Custom Agents" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomAgentDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Custom agent not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getCustomAgent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Custom-agent id (e.g. `chiron`)." } ], "x-heygen-required-scopes": [ "custom_agents:read" ] } }, "/v3/custom-agents/{agent_id}/videos": { "post": { "summary": "Create Custom Agent Video", "description": "Kicks off a custom-agent run from a topic prompt. Returns a video_id immediately; poll GET /v3/custom-agents/{agent_id}/videos/{video_id} for status + rendered MP4 URL. Assets (screen recording, still, wallpaper) come from POST /v3/assets/direct-uploads \u2014 pass the resulting URL in the matching *_url field.", "tags": [ "Custom Agents" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomAgentVideoCreateResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createCustomAgentVideo", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Custom-agent id (e.g. `chiron`)." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAgentVideoCreateRequest" } } } }, "x-heygen-required-scopes": [ "avatars:read", "custom_agents:write", "videos:read", "videos:write", "voices:read", "voices:write" ] } }, "/v3/custom-agents/{agent_id}/videos/{video_id}": { "get": { "summary": "Get Custom Agent Video Status", "description": "Returns status + presigned output MP4 URL once the workflow completes.", "tags": [ "Custom Agents" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomAgentVideoStatusResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Custom agent video not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getCustomAgentVideo", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Custom-agent id." }, { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video id from POST /v3/custom-agents/{agent_id}/videos." } ], "x-heygen-required-scopes": [ "custom_agents:read" ] } }, "/v1/user/me": { "get": { "summary": "Get current user info, remaining credits, and billing", "description": "Returns the authenticated user's profile, remaining credits or balance, and billing details. The billing_type field indicates which billing object is populated: wallet (prepaid balance), subscription (OAuth credit pools), or usage_based (metered spending).", "tags": [ "User" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "API status code (100 = success)", "example": 100 }, "data": { "$ref": "#/components/schemas/UserInfoResponse" }, "message": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1APIError" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1APIError" }, "example": { "code": 401, "message": "Unauthorized" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1APIError" }, "example": { "code": 429, "message": "Too many requests" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getUserMe", "x-heygen-required-scopes": [ "account:read" ] } }, "/v3/users/me": { "get": { "summary": "Get Current User", "description": "Returns the authenticated user's profile, remaining credits or balance, and billing details.", "tags": [ "User" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserInfoResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/get-current-user" }, "operationId": "getCurrentUserV3", "x-heygen-required-scopes": [ "account:read" ] } }, "/v3/api_keys/self": { "get": { "summary": "Get Current API Key", "description": "Returns non-secret metadata, expiration, and permission scopes for the API key used to authenticate this request. This endpoint accepts API-key authentication only and does not require the key to grant itself a permission scope.", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CurrentAPIKeyResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-mint": { "href": "/reference/get-current-api-key" }, "operationId": "getCurrentApiKeyV3" } }, "/v1/workflows/executions": { "post": { "summary": "Create a workflow execution", "description": "Submit a single workflow for asynchronous execution. Returns an execution_id that can be polled via GET /v1/workflows/executions/{execution_id}.", "tags": [ "Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowExecutionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'workflow_id' is required.", "param": "workflow_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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createWorkflowExecution", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowExecutionRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] } }, "/v1/workflows/graph-executions": { "post": { "summary": "Create a graph execution", "description": "Submit a multi-workflow graph for asynchronous execution. Returns an execution_id that can be polled via GET /v1/workflows/executions/{execution_id}.", "tags": [ "Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowExecutionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'workflows' is required and must not be empty.", "param": "workflows", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createGraphExecution", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGraphExecutionRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] } }, "/v1/workflows/executions/{execution_id}": { "get": { "summary": "Get workflow execution status", "description": "Poll the status and output of a workflow execution.\n\n**Single-workflow executions** return output in the `output` field.\n\n**Multi-workflow graph executions** return all outputs in the `outputs` field, keyed by workflow ID.", "tags": [ "Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowExecutionDetailResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Workflow execution not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getWorkflowExecution", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution ID returned from POST /v1/workflows/executions" } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v1/workflows": { "get": { "summary": "List available workflows", "description": "List all available workflow types with their input/output schemas.", "tags": [ "Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowCatalogEntry" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listWorkflows", "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/avatars/{group_id}": { "get": { "summary": "Get Avatar Group", "description": "Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarGroupItem" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "avatar_not_found", "message": "Avatar group not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-avatar-group" }, "operationId": "getAvatarGroup", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar group identifier" } ], "x-heygen-required-scopes": [ "avatars:read" ] }, "patch": { "summary": "Update Avatar Group", "description": "Updates an avatar group. Currently supports setting `default_voice_id`: the voice becomes the avatar's default for video generation and is linked to the group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own \u2014 public avatars cannot be updated.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarGroupItem" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid default_voice_id: 'abc123'. Voice not found.", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#invalid-parameter" } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "avatar_not_found", "message": "Avatar group ag_abc123 not found.", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#avatar-not-found" } } } } }, "403": { "description": "Forbidden \u2014 `error.code` is one of: `resource_access_denied`, `forbidden`, `voice_not_usable`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "resource_access_denied": { "summary": "Caller lacks write access to this avatar group", "value": { "error": { "code": "resource_access_denied", "message": "Forbidden", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#resource-access-denied" } } }, "forbidden": { "summary": "Workspace policy restricts avatar editing to the owner or an admin", "value": { "error": { "code": "forbidden", "message": "Only the avatar owner or a workspace admin can edit this avatar.", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#forbidden" } } }, "voice_not_usable": { "summary": "The voice exists but is not usable by this workspace", "value": { "error": { "code": "voice_not_usable", "message": "This voice can't be used to generate this video. Please select a different voice to continue.", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#voice-not-usable" } } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_ready", "message": "This voice is still being created. Please try again in a moment.", "param": null, "doc_url": "https://developers.heygen.com/docs/error-codes#resource-not-ready" } } } } } }, "x-mint": { "href": "/reference/update-avatar-group" }, "operationId": "updateAvatarGroup", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar group identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAvatarGroupRequest" } } } }, "x-heygen-required-scopes": [ "avatars:write" ] }, "delete": { "summary": "Delete Avatar Group", "description": "Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarGroupDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "avatar_not_found", "message": "Avatar group not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-avatar-group" }, "operationId": "deleteAvatarGroup", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar group identifier" } ], "x-heygen-required-scopes": [ "avatars:write" ] } }, "/v3/avatars/{group_id}/consent": { "post": { "summary": "Create Avatar Consent", "description": "Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation. The consent URL expires 24 hours after creation and is valid for one successful consent submission. A recording submitted after expiry fails and the group stays in pending consent status, so create a new consent link if the subject has not recorded within 24 hours.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarConsentResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "avatar_not_found", "message": "Avatar group not found.", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-avatar-consent" }, "operationId": "createAvatarConsent", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar group identifier" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarConsentRequest" } } } }, "x-heygen-required-scopes": [ "avatars:write" ] } }, "/v3/avatars/looks": { "get": { "summary": "List Avatar Looks", "description": "Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvatarLookItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 50.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-avatar-looks" }, "operationId": "listAvatarLooks", "parameters": [ { "name": "group_id", "in": "query", "required": false, "description": "Filter looks to a specific avatar group. Returns only looks belonging to this group.", "schema": { "type": "string" } }, { "name": "avatar_type", "in": "query", "required": false, "description": "Filter by avatar type: 'studio_avatar', 'digital_twin', or 'photo_avatar'.", "schema": { "type": "string", "enum": [ "studio_avatar", "digital_twin", "photo_avatar" ] } }, { "name": "ownership", "in": "query", "required": false, "description": "Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all.", "schema": { "type": "string", "enum": [ "public", "private" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return per page (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "avatars:read" ] }, "post": { "summary": "Create Avatar Looks", "description": "Generates new looks for an existing avatar. `reference_look_id` is an existing look used as the identity reference; the new looks are added to its avatar. `type` selects the method. `look_pack` applies a Look Pack: `template_id` is a public Look Pack template, or an enterprise custom pack assigned to your workspace, and the pack decides how many looks are generated; generation is always 16:9, and `aspect_ratio: \"9:16\"` center-crops the delivered frames to portrait. `template` restyles the look into a single look template, producing two looks in the template's aspect ratio. Billing happens when the request is accepted: an API key is charged 1 API credit per look generated; a connected integration is charged the method's standard price from the workspace's credits. Free-tier MCP access cannot use this endpoint. The response lists the new looks' ids; poll `GET /v3/avatars/looks/{id}` until each is `completed` or `failed`.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAvatarLooksResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "template_id must refer to a Look Pack template; a single look template is applied with type 'template'", "param": "template_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 } } } } }, "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" } } } }, "402": { "description": "Insufficient credit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "insufficient_credit", "message": "Insufficient credit to generate the looks. Add credits or choose a pack that generates fewer looks.", "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": "avatar_not_found", "message": "Avatar not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden \u2014 `error.code` is one of: `forbidden`, `resource_access_denied`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "temporarily_unavailable": { "summary": "Avatar look generation is temporarily unavailable", "value": { "error": { "code": "forbidden", "message": "Avatar look generation is temporarily unavailable. Please try again later.", "param": null, "doc_url": null } } }, "paid_plan_required": { "summary": "The connected integration cannot generate looks on the free tier", "value": { "error": { "code": "forbidden", "message": "Avatar look generation requires a paid plan. Upgrade to access this feature.", "param": null, "doc_url": null } } }, "workspace_access_denied": { "summary": "The workspace or avatar group does not allow look generation", "value": { "error": { "code": "resource_access_denied", "message": "Space is not allowed to create a private avatar", "param": null, "doc_url": null } } } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-avatar-looks" }, "operationId": "createAvatarLooks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarLooksRequestBody" } } } }, "x-heygen-required-scopes": [ "avatars:write" ] } }, "/v3/avatars/look-templates": { "get": { "summary": "List Look Templates", "description": "Returns the curated templates this workspace may apply with `POST /v3/avatars/looks`, so template ids can be discovered over the API instead of read out of the HeyGen app. Each item's `id` is the `template_id` to send and its `type` is the `type` to send with it: `look_pack` for a Look Pack, which generates the number of looks in `looks_count`, or `template` for a single look template, which generates two. Packs are curated per gender, so filter with `gender` to get the variant matching your avatar. Enterprise custom packs assigned to the workspace are listed alongside the public ones. Flattened pack members are not listed separately.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LookTemplateItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 50.", "param": "limit", "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 } } } } }, "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" } } } }, "403": { "description": "Forbidden \u2014 `error.code` is one of: `insufficient_api_key_scope`, `resource_access_denied`, `forbidden`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "insufficient_api_key_scope": { "summary": "The API key lacks the avatars:read scope", "value": { "error": { "code": "insufficient_api_key_scope", "message": "This API key does not have permission to perform this action. Required scope: avatars:read.", "param": null, "doc_url": null } } }, "workspace_role_denied": { "summary": "The caller's workspace role cannot read avatar templates", "value": { "error": { "code": "resource_access_denied", "message": "Your account does not have permission to access this resource. Ask your Space Admin for further details.", "param": null, "doc_url": null } } }, "workspace_session_unavailable": { "summary": "The active workspace session is unavailable", "value": { "error": { "code": "forbidden", "message": "The active workspace session is unavailable. Reauthenticate and try again.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/list-look-templates" }, "operationId": "listLookTemplates", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by generation method: 'look_pack' for Look Packs, 'template' for single look templates. Omit for both.", "schema": { "type": "string", "enum": [ "look_pack", "template" ] } }, { "name": "gender", "in": "query", "required": false, "description": "Filter to templates built for 'male' or 'female'. Templates with no gender of their own are returned for either value. Omit for all.", "schema": { "type": "string", "enum": [ "male", "female" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return per page (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "avatars:read" ] } }, "/v3/avatars/looks/{look_id}": { "get": { "summary": "Get Avatar Look", "description": "Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarLookItem" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Avatar look not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-avatar-look" }, "operationId": "getAvatarLook", "parameters": [ { "name": "look_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos." } ], "x-heygen-required-scopes": [ "avatars:read" ] }, "patch": { "summary": "Update Avatar Look", "description": "Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarLookItem" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Renaming is only supported for photo and digital twin avatar looks.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Avatar look not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/update-avatar-look" }, "operationId": "updateAvatarLook", "parameters": [ { "name": "look_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAvatarLookRequest" } } } }, "x-heygen-required-scopes": [ "avatars:write" ] }, "delete": { "summary": "Delete Avatar Look", "description": "Deletes an avatar look and its backing resource. Supported types: photo_avatar, digital_twin, and kit-based looks. Studio avatar (model_index) types cannot be deleted via the API. **Warning:** deleting the last look in a group also deletes the parent group. Subsequent requests referencing that group id (e.g. `POST /v3/avatars` with `avatar_group_id`) return 404 not found.", "tags": [ "Avatars" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarLookDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Deleting this avatar look type is not supported.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Avatar look not found.", "param": null, "doc_url": null } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "forbidden", "message": "Cannot update public avatar" } } } } } }, "x-mint": { "href": "/reference/delete-avatar-look" }, "operationId": "deleteAvatarLook", "parameters": [ { "name": "look_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique avatar look identifier. This is the value to pass as avatar_id to POST /v3/videos." } ], "x-heygen-required-scopes": [ "avatars:write" ] } }, "/v3/webhooks/event-types": { "get": { "summary": "List Webhook Event Types", "description": "Returns all available webhook event types with human-readable descriptions.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypeItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/list-webhook-event-types" }, "operationId": "listWebhookEventTypes", "x-heygen-required-scopes": [ "webhooks:read" ] } }, "/v3/webhooks/endpoints": { "get": { "summary": "List Webhook Endpoints", "description": "Returns a paginated list of registered webhook endpoints.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointResponse" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/list-webhook-endpoints" }, "operationId": "listWebhookEndpoints", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of endpoints to return (1-100). Default: 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "webhooks:read" ] }, "post": { "summary": "Create Webhook Endpoint", "description": "Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation \u2014 store it securely.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'url' must be a publicly accessible HTTPS URL.", "param": "url", "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 } } } } }, "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" } } } }, "409": { "description": "Conflict \u2014 either the request conflicts with existing state, or a prior request with this `Idempotency-Key` is still in progress (`request_in_progress`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "conflict": { "summary": "Resource conflict", "value": { "error": { "code": "conflict", "message": "A webhook endpoint with this URL already exists for this account.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/create-webhook-endpoint" }, "operationId": "createWebhookEndpoint", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "x-heygen-required-scopes": [ "webhooks:write" ] } }, "/v3/webhooks/endpoints/{endpoint_id}": { "patch": { "summary": "Update Webhook Endpoint", "description": "Updates the URL and/or subscribed event types for a webhook endpoint. The events array is fully replaced \u2014 include all types you want to keep.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At least one of 'url' or 'events' must be provided.", "param": null, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "webhook_not_found", "message": "Webhook endpoint not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/update-webhook-endpoint" }, "operationId": "updateWebhookEndpoint", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "x-heygen-required-scopes": [ "webhooks:write" ] }, "delete": { "summary": "Delete Webhook Endpoint", "description": "Permanently removes a webhook endpoint. Events will no longer be delivered to this URL. This action cannot be undone.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": [ "object", "null" ], "default": null }, "data": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "webhook_not_found", "message": "Webhook endpoint not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/delete-webhook-endpoint" }, "operationId": "deleteWebhookEndpoint", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID" } ], "x-heygen-required-scopes": [ "webhooks:write" ] } }, "/v3/webhooks/endpoints/{endpoint_id}/rotate-secret": { "post": { "summary": "Rotate Webhook Signing Secret", "description": "Generates a new signing secret for a webhook endpoint and immediately invalidates the old one. Store the new secret securely \u2014 it will not be shown again.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RotateSecretResponseData" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "webhook_not_found", "message": "Webhook endpoint not found.", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-action": true, "x-mint": { "href": "/reference/rotate-webhook-signing-secret" }, "operationId": "rotateWebhookEndpointSecret", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "x-heygen-required-scopes": [ "webhooks:write" ] } }, "/v3/webhooks/events": { "get": { "summary": "List Webhook Events", "description": "Returns a paginated history of delivered webhook events. Filterable by event_type or entity_id.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventResponse" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/list-webhook-events" }, "operationId": "listWebhookEvents", "parameters": [ { "name": "event_type", "in": "query", "required": false, "description": "Filter events by type, e.g. 'avatar_video.success'.", "schema": { "type": "string", "enum": [ "avatar_video.success", "avatar_video.fail", "avatar_video_gif.success", "avatar_video_gif.fail", "video_translate.success", "video_translate.fail", "video_translate.preflight.validation_failed", "video_translate.preflight.download_failed", "personalized_video", "instant_avatar.success", "instant_avatar.fail", "photo_avatar_generation.success", "photo_avatar_generation.fail", "photo_avatar_train.success", "photo_avatar_train.fail", "photo_avatar_add_motion.success", "photo_avatar_add_motion.fail", "proofread_creation.success", "proofread_creation.fail", "live_avatar.success", "live_avatar.fail", "avatar_video_caption.success", "avatar_video_caption.fail", "video_agent.success", "video_agent.fail", "hyperframes_video.success", "hyperframes_video.fail", "ai_clipping.success", "ai_clipping.fail", "filler_word_removal.success", "filler_word_removal.fail", "podcast.success", "podcast.fail", "batch.finished" ] } }, { "name": "entity_id", "in": "query", "required": false, "description": "Filter events by entity ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of events to return (1-100). Default: 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "webhooks:read" ] } }, "/v3/assets/search": { "get": { "summary": "Search assets (images and icons)", "description": "Semantically search re-hosted public images and icons by natural-language description, e.g. 'pepperoni pizza on a wooden table' or 'minimalist rocket icon'. Returns assets ranked by similarity, each with a stable public URL, plus cursor-based pagination.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSearchItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'query' is required.", "param": "query", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-action": true, "x-excluded": true, "operationId": "searchAssets", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Natural-language description of the image or icon you want, e.g. 'pepperoni pizza on a wooden table' or 'minimalist rocket icon'. Results are ranked by semantic similarity.", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page, taken from 'next_token' in a prior response.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": true, "description": "Asset type to search (image or icon).", "schema": { "type": "string", "enum": [ "image", "icon" ] } }, { "name": "scope", "in": "query", "required": false, "description": "Which assets to search: 'public' (the shared catalog, default) or 'personal' (your own space's assets).", "schema": { "type": "string", "enum": [ "public", "personal" ], "default": "public" } } ], "x-heygen-required-scopes": [ "assets:read" ] } }, "/v3/assets": { "post": { "summary": "Upload Asset", "description": "Uploads a file (image, video, audio, PDF, or SRT subtitle) and returns an asset_id for use in other endpoints. Max 32 MB. Supported types: png, jpeg, mp4, webm, mp3, wav, pdf, srt.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UploadAssetV3Response" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "File is required. Upload a file using multipart/form-data.", "param": "file", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-mint": { "href": "/reference/upload-asset" }, "operationId": "uploadAsset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload (image, video, audio, PDF, or SRT subtitle). Max 32 MB." } }, "required": [ "file" ] } } } }, "x-heygen-required-scopes": [ "assets:write" ] }, "get": { "summary": "List Assets", "description": "**Beta** \u2014 this endpoint may change with a few days' notice. Lists a workspace member's uploaded assets, newest first, with cursor-based pagination. Returns the same asset objects as GET /v3/assets/{asset_id}. The 'username' parameter (the 'owner' value on asset items) is required while the endpoint is in beta and will become an optional filter in a future release. Results are that member's non-deleted assets, across all folders, that the caller has access to \u2014 each item carries 'owner' and 'folder_id'. Pass the optional folder_id to narrow to one folder (empty folder_id = root-level assets); omit it for everything.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetAssetV3Response" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid pagination token", "param": "token", "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 } } } } }, "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" } } } } }, "x-excluded": true, "operationId": "listAssets", "parameters": [ { "name": "username", "in": "query", "required": true, "description": "Username of the workspace member whose assets to list \u2014 the same value as asset items' 'owner' field. Required while this endpoint is in beta; it will become an optional filter in a future release.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of assets to return per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor from a previous response's next_token. Omit for the first page.", "schema": { "type": "string", "default": "" } }, { "name": "folder_id", "in": "query", "required": false, "description": "Optional folder filter. Omit to list ALL workspace assets across folders. Pass a folder id to list that folder only, or an empty value (folder_id=) for root-level assets (assets not filed into any folder).", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "assets:read" ] } }, "/v3/assets/{asset_id}": { "get": { "summary": "Get Asset", "description": "Returns metadata for an asset in the caller's workspace \u2014 including owner, upload timestamp, file type, and a publicly accessible URL.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetAssetV3Response" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "asset_not_found", "message": "Asset not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-asset" }, "operationId": "getAsset", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique asset identifier" } ], "x-heygen-required-scopes": [ "assets:read" ] }, "delete": { "summary": "Delete Asset", "description": "Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteAssetV3Response" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "asset_not_found", "message": "Asset not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-asset" }, "operationId": "deleteAsset", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique asset identifier" } ], "x-heygen-required-scopes": [ "assets:write" ] } }, "/v3/assets/direct-uploads": { "post": { "summary": "Create Asset Upload", "description": "Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAssetUploadResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-asset-upload" }, "operationId": "createAssetUpload", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetUploadRequest" } } } }, "x-heygen-required-scopes": [ "assets:write" ] } }, "/v3/assets/{asset_id}/complete": { "post": { "summary": "Complete Asset Upload", "description": "Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset.", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompleteAssetUploadResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "asset_not_found", "message": "Asset not found.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "conflict", "message": "Uploaded object not found yet. Retry after the upload PUT returns 200.", "param": null, "doc_url": null } } } } } }, "x-mcp-idempotent": true, "x-mint": { "href": "/reference/complete-asset-upload" }, "operationId": "completeAssetUpload", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique asset identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteAssetUploadRequest" } } } }, "x-heygen-required-scopes": [ "assets:write" ] } }, "/v3/video-agents/{session_id}": { "get": { "summary": "Get Video Agent Session", "description": "Returns the current status, progress, video_id, and recent chat messages for a session.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetSessionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Session not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video-agent-session" }, "operationId": "getVideoAgentSession", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" } ], "x-heygen-required-scopes": [ "video_agent:read" ] }, "post": { "summary": "Send Video Agent Message", "description": "Submits a conversational or scene-edit turn to an existing session created in either `generate` or `chat` mode. Follow-up turns preserve the session mode: `generate` continues automatically, while `chat` may pause for user input. Provide `message`, `edit_plan`, or both. Send `message` to answer agent questions, add context, or request conversational changes. For deterministic scene-scoped changes, first call GET /v3/videos/{video_id}/scenes, then include that video's ID as `scene_snapshot_video_id`, its `edit_version`, and a public `scene_id` in each `edit_plan` item. Items may reference different scene snapshots from this session, including earlier videos; none identifies the output draft. The server resolves internal Video Agent resource and storyboard scene IDs; clients must not supply them. The complete edit plan is rejected before submission if any scene is invalid or the draft changed before acceptance. Edits are asynchronous: `edit_version` is not a document lock, so two requests created from the same version may both be accepted. A successful edit turn returns the current working draft in `video_id`; further edits reuse it until rendering starts, then the next edit receives a new draft ID. Poll GET /v3/videos/{video_id} directly for status.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendMessageResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "missing_turn_content": { "summary": "No message or edit plan", "value": { "error": { "code": "invalid_parameter", "message": "Provide a message or edit_plan.", "param": "message", "doc_url": null } } }, "invalid_scene": { "summary": "Scene is not in the snapshot", "value": { "error": { "code": "invalid_parameter", "message": "Scene scene_example is not present in the current video draft.", "param": "edit_plan", "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Session or scene snapshot video not found.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `stale_edit_version`, `resource_not_ready`, `request_in_progress`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "stale_edit_version": { "summary": "The scene graph changed", "value": { "error": { "code": "stale_edit_version", "message": "The video changed after its scenes were read. Fetch the scenes again and retry with the new edit_version.", "param": null, "doc_url": null } } }, "resource_not_ready": { "summary": "The editable draft resource is still being prepared", "value": { "error": { "code": "resource_not_ready", "message": "The editable Video Agent resource is not ready yet.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } } }, "x-mint": { "href": "/reference/send-message-or-request-revision" }, "operationId": "sendVideoAgentMessage", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "x-heygen-required-scopes": [ "video_agent:write" ] } }, "/v3/video-agents/{session_id}/resources/{resource_id}": { "get": { "summary": "Get Session Resource", "description": "Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SessionResource" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-session-resource" }, "operationId": "getVideoAgentResource", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" }, { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID" } ], "x-heygen-required-scopes": [ "video_agent:read" ] } }, "/v3/video-agents/{session_id}/videos": { "get": { "summary": "List Session Videos", "description": "Returns all videos produced within a Video Agent session, sorted newest-first.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Session not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/list-session-videos" }, "operationId": "listVideoAgentSessionVideos", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" } ], "x-heygen-required-scopes": [ "video_agent:read" ] } }, "/v3/video-agents/{session_id}/stop": { "post": { "summary": "Stop Video Agent Session", "description": "Halts an active agent run at its next checkpoint. Partial results are preserved.", "tags": [ "Video Agent" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StopSessionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Session not found.", "param": null, "doc_url": null } } } } } }, "x-cli-action": true, "x-mint": { "href": "/reference/stop-video-agent-session" }, "operationId": "stopVideoAgentSession", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopSessionRequest" } } } }, "x-heygen-required-scopes": [ "video_agent:write" ] } }, "/v3/ai-clipping/{job_id}": { "get": { "summary": "Get AI Clipping", "description": "Returns the full job resource including produced clips, statuses, and presigned download URLs.", "tags": [ "AI Clipping" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiClippingDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "AI clip not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-ai-clipping" }, "operationId": "getAiClippingV3", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique AI clip job identifier" } ], "x-heygen-required-scopes": [ "ai_clipping:read" ] }, "delete": { "summary": "Delete AI Clipping", "description": "Soft-deletes an AI clip job and its clips.", "tags": [ "AI Clipping" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteAiClippingResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "AI clip not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/delete-ai-clipping" }, "operationId": "deleteAiClippingV3", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique AI clip job identifier" } ], "x-heygen-required-scopes": [ "ai_clipping:write" ] } }, "/v3/ai-clipping": { "get": { "summary": "List AI Clipping", "description": "Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first.", "tags": [ "AI Clipping" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiClippingDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/list-ai-clipping" }, "operationId": "listAiClippingV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page. Defaults to 10 (lower than other v3 lists) because each item embeds its full clips array.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "ai_clipping:read" ] }, "post": { "summary": "Create AI Clipping", "description": "Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output_settings. Poll GET /v3/ai-clipping/{id} or subscribe to ai_clipping.success / ai_clipping.fail webhooks.", "tags": [ "AI Clipping" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAiClippingResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Source video URL is unsupported or unreachable.", "param": "video", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-ai-clipping" }, "operationId": "createAiClippingV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiClippingRequest" } } } }, "x-heygen-required-scopes": [ "ai_clipping:write" ] } }, "/v3/filler-word-removals": { "post": { "summary": "Create Filler Word Removal", "description": "Submit a video and return a job id immediately. The job runs asynchronously: it transcribes the audio, detects filler words ('um', 'uh', ...), removes them along with overlong silences, and renders one cleaned video \u2014 no review step. If the run changes nothing at all, the job completes with the original video as output and the charge is automatically refunded. Pricing: $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or subscribe to filler_word_removal.success / filler_word_removal.fail webhooks.", "tags": [ "Filler Word Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateFillerWordRemovalResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "invalid_parameter": { "summary": "Unusable source (zero duration / probe timeout)", "value": { "error": { "code": "invalid_parameter", "message": "The input video reports a zero duration \u2014 provide a valid video source.", "param": "video", "doc_url": null } } }, "video_too_long": { "summary": "Source exceeds the 2-hour cap", "value": { "error": { "code": "video_too_long", "message": "The input video is 7305s long; the maximum supported duration is 7200s (2 hours).", "param": "video", "doc_url": null } } }, "no_audio_track": { "summary": "Source has no audio stream", "value": { "error": { "code": "no_audio_track", "message": "The input video has no audio track. Filler removal needs speech audio to transcribe.", "param": "video", "doc_url": null } } }, "download_failed": { "summary": "Source URL unreachable or unreadable", "value": { "error": { "code": "download_failed", "message": "Could not read the input video \u2014 provide a valid, accessible video URL or asset_id.", "param": "video", "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 } } } } }, "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" } } } }, "402": { "description": "Insufficient credit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "insufficient_credit", "message": "Not enough premium credits for Speech Cleanup", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-filler-word-removal" }, "operationId": "createFillerWordRemovalV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFillerWordRemovalRequest" } } } }, "x-heygen-required-scopes": [ "filler_removal:write" ] } }, "/v3/filler-word-removals/{filler_word_removal_id}": { "get": { "summary": "Get Filler Word Removal", "description": "Returns the job resource: lifecycle status, progress, and \u2014 once completed \u2014 the presigned download URL of the cleaned video plus removal statistics (num_cuts, reduction_pct, durations).", "tags": [ "Filler Word Removal" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FillerWordRemovalDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Filler word removal job not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-filler-word-removal" }, "operationId": "getFillerWordRemovalV3", "parameters": [ { "name": "filler_word_removal_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique filler word removal job identifier" } ], "x-heygen-required-scopes": [ "filler_removal:read" ] } }, "/v3/videos/batches": { "post": { "summary": "Create Video Batch", "description": "Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses.", "tags": [ "Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateVideoBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid payload(s) at index 3.", "param": "videos", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-video-batch" }, "operationId": "createVideoBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoBatchRequest" } } } }, "x-heygen-required-scopes": [ "videos:write" ] } }, "/v3/videos/batches/{batch_id}": { "get": { "summary": "Get Video Batch", "description": "Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed.", "tags": [ "Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoBatchDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Batch not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video-batch" }, "operationId": "getVideoBatchV3", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video batch identifier returned by POST /v3/videos/batches" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "videos:read" ] } }, "/v3/videos/statuses": { "get": { "summary": "Bulk Video Statuses", "description": "Returns statuses for up to 100 videos in one request, addressed by comma-separated video_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids.", "tags": [ "Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoStatusEntry" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At most 100 ids per request.", "param": "video_ids", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/bulk-video-statuses" }, "operationId": "bulkVideoStatusesV3", "parameters": [ { "name": "video_ids", "in": "query", "required": false, "description": "Comma-separated video ids to look up.", "schema": { "type": "string" } }, { "name": "batch_ids", "in": "query", "required": false, "description": "Comma-separated batch ids; each expands to its member videos.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "videos:read" ] } }, "/v3/video-translations/batches": { "post": { "summary": "Create Video Translation Batch", "description": "Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe \u2014 the same key returns the same batch.", "tags": [ "Video Translation Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateVideoTranslationBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid payload(s) at index 3.", "param": "video_translations", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-video-translation-batch" }, "operationId": "createVideoTranslationBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoTranslationBatchRequest" } } } }, "x-heygen-required-scopes": [ "translations:write" ] } }, "/v3/video-translations/batches/{batch_id}": { "get": { "summary": "Get Video Translation Batch", "description": "Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).", "tags": [ "Video Translation Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoBatchDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Batch not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-video-translation-batch" }, "operationId": "getVideoTranslationBatchV3", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video-translation batch identifier returned by POST /v3/video-translations/batches" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/video-translations/statuses": { "get": { "summary": "Bulk Video Translation Statuses", "description": "Returns statuses for up to 100 video translations in one request, addressed by comma-separated video_translation_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).", "tags": [ "Video Translation Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoStatusEntry" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At most 100 ids per request.", "param": "video_translation_ids", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/bulk-video-translation-statuses" }, "operationId": "bulkVideoTranslationStatusesV3", "parameters": [ { "name": "video_translation_ids", "in": "query", "required": false, "description": "Comma-separated video translation ids to look up.", "schema": { "type": "string" } }, { "name": "batch_ids", "in": "query", "required": false, "description": "Comma-separated batch ids; each expands to its member video translations.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "translations:read" ] } }, "/v3/lipsyncs/batches": { "post": { "summary": "Create Lipsync Batch", "description": "Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe \u2014 the same key returns the same batch.", "tags": [ "Lipsync Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateLipsyncBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid payload(s) at index 3.", "param": "lipsyncs", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-lipsync-batch" }, "operationId": "createLipsyncBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLipsyncBatchRequest" } } } }, "x-heygen-required-scopes": [ "lipsync:write" ] } }, "/v3/lipsyncs/batches/{batch_id}": { "get": { "summary": "Get Lipsync Batch", "description": "Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).", "tags": [ "Lipsync Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoBatchDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Batch not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-lipsync-batch" }, "operationId": "getLipsyncBatchV3", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique lipsync batch identifier returned by POST /v3/lipsyncs/batches" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "lipsync:read" ] } }, "/v3/lipsyncs/statuses": { "get": { "summary": "Bulk Lipsync Statuses", "description": "Returns statuses for up to 100 lipsyncs in one request, addressed by comma-separated lipsync_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).", "tags": [ "Lipsync Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoStatusEntry" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At most 100 ids per request.", "param": "lipsync_ids", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/bulk-lipsync-statuses" }, "operationId": "bulkLipsyncStatusesV3", "parameters": [ { "name": "lipsync_ids", "in": "query", "required": false, "description": "Comma-separated lipsync ids to look up.", "schema": { "type": "string" } }, { "name": "batch_ids", "in": "query", "required": false, "description": "Comma-separated batch ids; each expands to its member lipsyncs.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "lipsync:read" ] } }, "/v3/assets/direct-uploads/batches": { "post": { "summary": "Create Asset Upload Batch", "description": "Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous \u2014 no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch).", "tags": [ "Asset Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateAssetUploadBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Invalid file(s) at index 3.", "param": "files", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/create-asset-upload-batch" }, "operationId": "createAssetUploadBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetUploadBatchRequest" } } } }, "x-heygen-required-scopes": [ "assets:write" ] } }, "/v3/assets/complete/batches": { "post": { "summary": "Complete Asset Upload Batch", "description": "Finalize every uploaded file in a batch. Call after all upload PUTs return 200. Each file is validated and ingested asynchronously and independently, so one bad file does not fail the rest. Returns 202 with the batch_id; poll GET /v3/assets/batches/{batch_id} for per-item progress. Idempotent: a repeated call re-drives the same batch.", "tags": [ "Asset Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompleteAssetBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Batch not found.", "param": null, "doc_url": null } } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mint": { "href": "/reference/complete-asset-upload-batch" }, "operationId": "completeAssetBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteAssetBatchRequest" } } } }, "x-heygen-required-scopes": [ "assets:write" ] } }, "/v3/assets/batches/{batch_id}": { "get": { "summary": "Get Asset Batch", "description": "Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset_id.", "tags": [ "Asset Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoBatchDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Batch not found.", "param": null, "doc_url": null } } } } } }, "x-mint": { "href": "/reference/get-asset-batch" }, "operationId": "getAssetBatchV3", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique asset batch identifier returned by POST /v3/assets/direct-uploads/batches" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "assets:read" ] } }, "/v3/assets/statuses": { "get": { "summary": "Bulk Asset Statuses", "description": "Returns statuses for up to 100 assets in one request, addressed by comma-separated asset_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).", "tags": [ "Asset Batches" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoStatusEntry" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "At most 100 ids per request.", "param": "asset_ids", "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 } } } } }, "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" } } } } }, "x-mint": { "href": "/reference/bulk-asset-statuses" }, "operationId": "bulkAssetStatusesV3", "parameters": [ { "name": "asset_ids", "in": "query", "required": false, "description": "Comma-separated asset ids to look up.", "schema": { "type": "string" } }, { "name": "batch_ids", "in": "query", "required": false, "description": "Comma-separated batch ids; each expands to its member assets.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "assets:read" ] } }, "/v3/podcasts": { "post": { "summary": "Create Podcast", "description": "Generate a multi-avatar conversational podcast video from a topic and/or source files plus two avatars. Generation is asynchronous \u2014 use the returned podcast_id to poll status via GET /v3/podcasts/{podcast_id}.", "tags": [ "Podcasts" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PodcastCreateResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "Provide at least one of `topic` or `source_files`.", "param": "topic", "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createPodcastV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodcastRequest" } } } }, "x-heygen-required-scopes": [ "podcasts:write" ] }, "get": { "summary": "List Podcasts", "description": "Returns a paginated list of the podcasts in the authenticated workspace, newest first.", "tags": [ "Podcasts" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastDetail" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "invalid_parameter", "message": "'limit' must be between 1 and 100.", "param": "limit", "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listPodcastsV3", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Results per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor token for the next page.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "podcasts:read" ] } }, "/v3/podcasts/{podcast_id}": { "get": { "summary": "Get Podcast", "description": "Returns a podcast's status and, once completed, its video_url, thumbnail_url, and duration.", "tags": [ "Podcasts" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PodcastDetail" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Podcast not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getPodcastV3", "parameters": [ { "name": "podcast_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique podcast identifier" } ], "x-heygen-required-scopes": [ "podcasts:read" ] }, "delete": { "summary": "Delete Podcast", "description": "Soft-deletes a podcast so it no longer appears in the get/list endpoints. Does not cancel in-flight generation or permanently remove files. Idempotent: deleting an already-deleted podcast succeeds.", "tags": [ "Podcasts" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PodcastDeleteResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "not_found", "message": "Podcast not found.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "deletePodcastV3", "parameters": [ { "name": "podcast_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique podcast identifier" } ], "x-heygen-required-scopes": [ "podcasts:write" ] } }, "/v3/workflows": { "post": { "summary": "Create Workflow", "description": "Atomically creates a workflow and publishes its required product graph as immutable version 1: the graph is validated and compiled first, then the workflow, its published version 1, and its `active` status commit together. The response's `latest_version` names the exact version this request published, ready to run. A graph that fails validation (including node types not available for authoring \u2014 see the node-types catalog) returns 422 `graph_invalid` and creates nothing; a name already used in the space returns 409 `conflict` with no partial writes.\n\nIdempotency (authoring contract): send an `Idempotency-Key` and a retry of the SAME request replays the original response body with **HTTP 200** (only the body is cached, not the original 201; the workflow already exists on a replay). Reusing a key with a different name, graph, or metadata returns 409 `conflict` instead of replaying. Keys are held in Redis for 24 hours; if the cache is unavailable the request executes and a duplicate retry converges on the duplicate-name 409. This differs from run creation's idempotency, which is durable (DB-backed, no expiry). A replay is a snapshot of the original response \u2014 later changes (e.g. archival) do not appear in it.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowDefinitionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "422": { "description": "Graph invalid \u2014 the request parsed but the workflow graph is semantically invalid; `error.errors[]` lists every issue found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "graph_invalid", "message": "The workflow graph is invalid. Each entry in errors identifies one problem to fix.", "param": null, "doc_url": null, "errors": [ { "code": "unknown_node_type", "message": "unknown node family 'lmm'", "node_id": "summary" }, { "code": "invalid_config", "message": "Field required", "node_id": "narrate", "path": "config.prompt" } ] } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `conflict`, `request_in_progress`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "workflow_name_conflict": { "summary": "A workflow with this name already exists in the space", "value": { "error": { "code": "conflict", "message": "A workflow named 'Onboarding' already exists in this space.", "param": null, "doc_url": null } } }, "idempotency_key_reused": { "summary": "Idempotency-Key reused with a different request", "value": { "error": { "code": "conflict", "message": "This Idempotency-Key was already used with a different request. Send a new key for a new request.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } }, "200": { "description": "Idempotency-key replay of a previously created workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowDefinitionResponse" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createWorkflow", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] }, "get": { "summary": "List Workflows", "description": "Returns a paginated list of workflow definitions.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDefinitionListItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listWorkflowDefinitions", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max items per page (1-100). Defaults to 10 if omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token from a prior response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflows/{workflow_id}": { "get": { "summary": "Get Workflow", "description": "Returns a single workflow definition, including its current mutable draft graph.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowDefinitionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getWorkflow", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow definition ID" } ], "x-heygen-required-scopes": [ "workflows:read" ] }, "patch": { "summary": "Update Workflow Draft", "description": "Replaces the mutable draft product graph. Rejected (409) if `expected_revision` is stale, and 422 `graph_invalid` if the graph uses node types not available for authoring \u2014 the draft is left unchanged in both cases.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowDefinitionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "422": { "description": "Graph invalid \u2014 the request parsed but the workflow graph is semantically invalid; `error.errors[]` lists every issue found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "graph_invalid", "message": "The workflow graph is invalid. Each entry in errors identifies one problem to fix.", "param": null, "doc_url": null, "errors": [ { "code": "unknown_node_type", "message": "unknown node family 'lmm'", "node_id": "summary" }, { "code": "invalid_config", "message": "Field required", "node_id": "narrate", "path": "config.prompt" } ] } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `stale_workflow_draft`, `workflow_archived`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "stale_workflow_draft": { "summary": "expected_revision no longer matches", "value": { "error": { "code": "stale_workflow_draft", "message": "Definition 'def_abc123' draft_revision is 3, expected 2. Re-read the workflow and reapply the change.", "param": null, "doc_url": null } } }, "workflow_archived": { "summary": "Workflow definition is archived", "value": { "error": { "code": "workflow_archived", "message": "Definition 'def_abc123' is archived and cannot be modified.", "param": null, "doc_url": null } } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "updateWorkflowDraft", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow definition ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowDraftRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] } }, "/v3/workflows/{workflow_id}/versions": { "post": { "summary": "Publish Workflow Version", "description": "Compile the complete product graph in the request body and persist it as the next immutable version. The workflow's internal draft is neither read nor modified. Returns 201 when a new version is created and 200 when the latest version is already identical (republishing the same graph is a no-op that returns it). Republishing an older graph after a newer one creates a NEW version \u2014 version history is append-only, so rollback means republishing the prior graph.\n\nIdempotency (authoring contract): send an `Idempotency-Key` and a retry of the SAME request replays the original response body with **HTTP 200 even if the original call returned 201** \u2014 only the body is cached, not its status. Do not key 'just created' behaviour off the status code alone on a replay; compare `version_number` against what you already hold. Reusing a key with a different graph \u2014 or against a different `workflow_id` \u2014 returns 409 `conflict` instead of replaying. Keys are held in Redis for 24 hours; if the cache is unavailable the request executes and an identical retry converges on the 200-existing-version answer \u2014 provided no different publish landed in between; otherwise the retry creates a new version, since history is append-only. This differs from run creation's idempotency, which is durable (DB-backed, no expiry). A replay is a snapshot of the original response.\n\nA graph that fails validation returns 422 `graph_invalid` with every issue listed in `error.errors[]`, and nothing is published \u2014 the latest version is unchanged.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowVersionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "422": { "description": "Graph invalid \u2014 the request parsed but the workflow graph is semantically invalid; `error.errors[]` lists every issue found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "graph_invalid", "message": "The workflow graph is invalid. Each entry in errors identifies one problem to fix.", "param": null, "doc_url": null, "errors": [ { "code": "unknown_node_type", "message": "unknown node family 'lmm'", "node_id": "summary" }, { "code": "invalid_config", "message": "Field required", "node_id": "narrate", "path": "config.prompt" } ] } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "A concurrent publish on this workflow took the version number. This is safe to retry: repeat the request (with the same Idempotency-Key, a retry after success replays the published version).", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `workflow_archived`, `conflict`, `request_in_progress`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "workflow_archived": { "summary": "Workflow definition is archived", "value": { "error": { "code": "workflow_archived", "message": "Definition 'def_abc123' is archived; nothing was published.", "param": null, "doc_url": null } } }, "idempotency_key_reused": { "summary": "Idempotency-Key reused with a different request or target", "value": { "error": { "code": "conflict", "message": "This Idempotency-Key was already used with a different request. Send a new key for a new request.", "param": null, "doc_url": null } } }, "request_in_progress": { "summary": "Concurrent retry with same Idempotency-Key", "value": { "error": { "code": "request_in_progress", "message": "A request with this Idempotency-Key is already in progress. Retry shortly.", "param": null, "doc_url": null } } } } } } }, "200": { "description": "Existing identical version returned, or an idempotency-key replay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowVersionResponse" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "publishWorkflowVersion", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow definition ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishVersionRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] }, "get": { "summary": "List Workflow Versions", "description": "Returns a paginated list of immutable, compiled versions for a workflow definition.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVersionListItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listWorkflowVersions", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow definition ID" }, { "name": "limit", "in": "query", "required": false, "description": "Max items per page (1-100). Defaults to 10 if omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token from a prior response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflows/{workflow_id}/versions/{version_number}": { "get": { "summary": "Get Workflow Version", "description": "Returns a single immutable, compiled workflow version, including its full plan summary.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowVersionResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getWorkflowVersion", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow definition ID" }, { "name": "version_number", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Version number" } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflows/node-types": { "get": { "summary": "List Workflow Node Types", "description": "Discovery catalog of authorable node types, grouped by family with per-variant config schema and ports. Discovery metadata only: publishing a workflow version remains the authoritative validation of a graph.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeTypeCatalogResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getWorkflowNodeTypes", "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflow-runs": { "post": { "summary": "Start a workflow run", "description": "Starts a run of the workflow named in the request body. Omit `version_number` to run the latest published version: it is resolved exactly once, when the request's `Idempotency-Key` is first accepted, and the response reports the exact `version_number` (and `version_id`) the run is pinned to. Repeating the request with the same key always returns that original run \u2014 including after a newer version is published \u2014 while reusing the key with a different workflow, version, or inputs is rejected with a 409 `conflict` and starts nothing. Validates inputs against the resolved version's frozen plan, creates the run and its pending node runs in a single transaction, and then submits the run for execution. A 201 or 200 means the run has been accepted for execution; if the submission cannot be confirmed the response is a retryable 503 (see below) and the run is left pending. `Idempotency-Key` is REQUIRED on this endpoint, because repeating the request with the same key is how a 503 is recovered. No video is created and nothing is charged by this call. Media inputs accept an asset id (as a bare string or `{\"type\": \"asset_id\"}` object), a publicly accessible HTTPS source URL (`{\"type\": \"url\"}`), or inline base64 content (`{\"type\": \"base64\"}`). URL and inline sources are imported into your asset library before the run executes, so the run is immune to the source changing or expiring afterwards; retries with the same `Idempotency-Key` reuse the already-imported asset. URL sources are fetched with a 16 MB limit for images and 32 MB for audio; inline content is limited to 5 MB for images and 16 MB for audio and must also fit this endpoint's 1 MiB request-body limit \u2014 for anything larger, upload via POST /v3/assets/direct-uploads and pass the asset_id.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "example": { "error": { "code": "resource_not_found", "message": "Workflow not found.", "param": null, "doc_url": null } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "Workflow run admission is temporarily unavailable. This is safe and expected to retry: repeat this request with the same Idempotency-Key to resume this run.", "param": null, "doc_url": null } } } } }, "409": { "description": "Conflict \u2014 `error.code` is one of: `conflict`, `workflow_archived`, `workflow_run_admission_refused`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } }, "examples": { "conflict": { "summary": "Idempotency-Key reused with a different request body", "value": { "error": { "code": "conflict", "message": "An Idempotency-Key was reused with a different request body. Use a new key, or repeat the original request exactly.", "param": null, "doc_url": null } } }, "workflow_archived": { "summary": "Workflow definition is archived", "value": { "error": { "code": "workflow_archived", "message": "Definition 'def_abc123' is archived and cannot start new runs.", "param": null, "doc_url": null } } }, "workflow_run_admission_refused": { "summary": "Run inputs rejected at admission (terminal)", "value": { "error": { "code": "workflow_run_admission_refused", "message": "This run could not be started: its inputs were rejected during workflow scheduling. Retrying will not resolve this; review the run's inputs.", "param": null, "doc_url": null } } } } } } }, "200": { "description": "Existing run returned for a repeated Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createWorkflowRun", "parameters": [ { "$ref": "#/components/parameters/DurableIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRunRequest" } } } }, "x-heygen-required-scopes": [ "workflows:write" ] }, "get": { "summary": "List Workflow Runs", "description": "Returns a paginated list of runs for the workflow named by the required `workflow_id` query parameter, newest first. List items are compact status rows; fetch a single run for its outputs and error detail.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunListItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listWorkflowRuns", "parameters": [ { "name": "workflow_id", "in": "query", "required": true, "description": "Workflow whose runs to list. Required.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max items per page (1-100). Defaults to 10 if omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token from a prior response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflow-runs/{run_id}": { "get": { "summary": "Get Workflow Run", "description": "Returns a single workflow run: the exact version it is pinned to, created/started/completed timestamps, aggregate node progress, a sanitized terminal error (if any), and every declared output. A terminal run's response is self-contained \u2014 media outputs carry a fresh read-time URL (with expiry unless the object is public), and inline JSON outputs carry their value directly, bounded at 64 KiB per output and 256 KiB per response (larger values are delivered as references whose URL serves the value as a JSON document). The response body size does not grow with the run's node count; per-node detail lives under /nodes.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getWorkflowRun", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run ID" } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/workflow-runs/{run_id}/cancel": { "post": { "summary": "Cancel Workflow Run", "description": "Requests cancellation of a run. Idempotent and defined for every run state: a 200 reflects a settled outcome (the run is terminal now \u2014 canceled by this request, or already finished, in which case its terminal status is unchanged and reported as-is). When cancellation cannot be confirmed the response is a retryable 503 and the run is unchanged. A terminal run can never move backward.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "503": { "description": "Temporarily unavailable \u2014 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": "This cancellation could not be confirmed. It is safe to retry this request, or fetch the run to see its current status.", "param": null, "doc_url": null } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "cancelWorkflowRun", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run ID" } ], "x-heygen-required-scopes": [ "workflows:write" ] } }, "/v3/workflow-runs/{run_id}/nodes": { "get": { "summary": "List Workflow Run Nodes", "description": "Paginated per-node diagnostics for one run: node id, status, timestamps, and a sanitized error for failed nodes. Diagnostics only \u2014 a run's declared outputs live on the run resource itself.", "tags": [ "Durable Workflows" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunNodeItem" } }, "has_more": { "type": "boolean", "description": "Whether more pages are available" }, "next_token": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "listWorkflowRunNodes", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run ID" }, { "name": "limit", "in": "query", "required": false, "description": "Max items per page (1-100). Defaults to 10 if omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination token from a prior response's next_token.", "schema": { "type": "string" } } ], "x-heygen-required-scopes": [ "workflows:read" ] } }, "/v3/video-quality/comparisons": { "post": { "summary": "Create Video Quality Comparison", "description": "Submit one pairwise video comparison. The server waits for a bounded synchronous result: completed comparisons return 200, while comparisons that continue asynchronously return 202 and can be polled by comparison_id.", "tags": [ "Video Quality" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoQualityComparisonResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "202": { "description": "Accepted \u2014 comparison continues asynchronously; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoQualityComparisonResponse" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createVideoQualityComparisonV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoQualityComparisonRequest" } } } }, "x-heygen-required-scopes": [ "video_quality:write" ] } }, "/v3/video-quality/comparisons/{comparison_id}": { "get": { "summary": "Get Video Quality Comparison", "description": "Return the latest state and result or terminal error for one comparison.", "tags": [ "Video Quality" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoQualityComparisonResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getVideoQualityComparisonV3", "parameters": [ { "name": "comparison_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video quality comparison identifier" } ], "x-heygen-required-scopes": [ "video_quality:read" ] } }, "/v3/video-quality/comparisons/batches": { "post": { "summary": "Create Video Quality Comparison Batch", "description": "Submit up to 2000 pairwise video comparisons for asynchronous processing.", "tags": [ "Video Quality" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted \u2014 submission acknowledged; poll for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateVideoQualityComparisonBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "createVideoQualityComparisonBatchV3", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoQualityComparisonBatchRequest" } } } }, "x-heygen-required-scopes": [ "video_quality:write" ] } }, "/v3/video-quality/comparisons/batches/{batch_id}": { "get": { "summary": "Get Video Quality Comparison Batch", "description": "Return aggregate batch status and one cursor-paginated page of comparison items.", "tags": [ "Video Quality" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VideoQualityComparisonBatchResponse" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } }, "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 } } } } }, "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" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/StandardAPIError" } } } } } } }, "x-mcp-visible": false, "x-cli-visible": false, "x-excluded": true, "operationId": "getVideoQualityComparisonBatchV3", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique video quality comparison batch identifier" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of ordered batch items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "token", "in": "query", "required": false, "description": "Opaque cursor returned by a previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } } ], "x-heygen-required-scopes": [ "video_quality:read" ] } } }, "components": { "schemas": { "LegacyAPIError": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "example": "invalid_parameter" }, "message": { "type": "string", "description": "Human-readable error message", "example": "prompt is required" } }, "required": [ "code", "message" ] }, "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" ] }, "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" ] }, "V1APIError": { "type": "object", "properties": { "code": { "type": "integer", "description": "API status code", "example": 401 }, "message": { "type": "string", "description": "Human-readable error message", "example": "Unauthorized" } }, "required": [ "code", "message" ] }, "ExternalCreateVideoAgentSessionRequest": { "additionalProperties": false, "description": "Request body for creating a video from a prompt using Video Agent V2A.", "properties": { "prompt": { "description": "The message/prompt for video generation (1-10000 characters)", "maxLength": 10000, "minLength": 1, "title": "Prompt", "type": "string" }, "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific avatar ID to use", "title": "Avatar Id" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific voice ID to use for narration", "title": "Voice Id" }, "orientation": { "anyOf": [ { "enum": [ "landscape", "portrait" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Video orientation. If not provided, auto-detected from content.", "title": "Orientation" }, "duration_sec": { "anyOf": [ { "minimum": 5, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Approximate video duration in seconds (minimum 5)", "title": "Duration Sec" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/VideoAgentConfig" }, { "type": "null" } ], "default": null, "description": "Deprecated. Use top-level avatar_id, orientation, and duration_sec instead. Video generation configuration." }, "files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FileInput" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional file attachments (max 20 files)", "title": "Files" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion/failure notifications", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional callback ID included in webhook payload", "title": "Callback Id" }, "incognito_mode": { "default": false, "description": "When enabled, disables memory injection and extraction for this session", "title": "Incognito Mode", "type": "boolean" } }, "required": [ "prompt" ], "title": "ExternalCreateVideoAgentSessionRequest", "type": "object" }, "FileInput": { "additionalProperties": false, "description": "Input file attachment for video generation.", "properties": { "asset_id": { "description": "HeyGen asset ID (from /v1/asset upload endpoint). Supported types: image (png, jpeg), video (mp4, webm), pdf.", "title": "Asset Id", "type": "string" } }, "required": [ "asset_id" ], "title": "FileInput", "type": "object" }, "VideoAgentConfig": { "additionalProperties": false, "description": "Configuration options for video generation.", "properties": { "duration_sec": { "anyOf": [ { "minimum": 5, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Approximate video duration in seconds (minimum 5)", "title": "Duration Sec" }, "orientation": { "anyOf": [ { "enum": [ "landscape", "portrait" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Video orientation. If not provided, auto-detected from content.", "title": "Orientation" }, "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific avatar ID to use", "title": "Avatar Id" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific voice ID to use for narration", "title": "Voice Id" } }, "title": "VideoAgentConfig", "type": "object" }, "ExternalCreateVideoAgentSessionResponse": { "description": "Response from creating a video.", "properties": { "video_id": { "description": "Video ID. Use with GET /v2/videos/{video_id} for polling", "title": "Video Id", "type": "string" }, "session_id": { "description": "Video Agent session ID", "title": "Session Id", "type": "string" } }, "required": [ "video_id", "session_id" ], "title": "ExternalCreateVideoAgentSessionResponse", "type": "object" }, "CreateVideoAgentRequest": { "additionalProperties": false, "description": "Request body for creating a video from a prompt using Video Agent v3.\n\nAll configuration is flat (no nested config object). Files use the\ntype-discriminated AssetInput union for flexible asset inputs.\n\nSupports two modes:\n- ``generate`` (default): one-shot \u2014 auto-proceeds through storyboard, produces one video.\n- ``chat``: multi-turn \u2014 may pause for user input on real decisions (e.g. pick a voice),\n auto-proceeds on confirmations. Allows follow-up messages, targeted edits, and additional videos.", "properties": { "prompt": { "description": "The message/prompt for video generation (1-10000 characters)", "maxLength": 10000, "minLength": 1, "title": "Prompt", "type": "string" }, "mode": { "$ref": "#/components/schemas/SessionMode", "default": "generate", "description": "Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction \u2014 the agent may pause for decisions and accept follow-up messages." }, "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific avatar ID to use", "title": "Avatar Id" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific voice ID to use for narration", "title": "Voice Id" }, "style_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.", "title": "Style Id" }, "brand_kit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically.", "title": "Brand Kit Id" }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "orientation": { "anyOf": [ { "enum": [ "landscape", "portrait" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Video orientation. If not provided, auto-detected from content.", "title": "Orientation" }, "files": { "anyOf": [ { "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional file attachments (max 20 files)", "title": "Files" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion/failure notifications", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional callback ID included in webhook payload", "title": "Callback Id" }, "visibility": { "default": "team", "description": "Session visibility: private (owner only), team (workspace members), or public (anyone with the link). Defaults to team. Applies to the session and its conversation; does not change existing sessions.", "enum": [ "private", "team", "public" ], "title": "Visibility", "type": "string" }, "incognito_mode": { "default": false, "description": "When enabled, disables memory injection and extraction for this session", "title": "Incognito Mode", "type": "boolean" } }, "required": [ "prompt" ], "title": "CreateVideoAgentRequest", "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 }, "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" }, "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" }, "SessionMode": { "enum": [ "generate", "chat" ], "title": "SessionMode", "type": "string" }, "CreateVideoAgentResponse": { "description": "Response from creating a video agent session.", "properties": { "session_id": { "description": "Session ID \u2014 primary identifier for this video agent session", "examples": [ "sess_012abc345def678" ], "title": "Session Id", "type": "string" }, "status": { "description": "Session status", "enum": [ "generating", "thinking", "completed", "failed" ], "examples": [ "generating" ], "title": "Status", "type": "string" }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video ID for polling via GET /v3/videos/{video_id}, when available.", "examples": [ "v_abc123def456" ], "title": "Video Id" }, "created_at": { "description": "Unix timestamp of session creation", "examples": [ 1711929600 ], "title": "Created At", "type": "integer" } }, "required": [ "session_id", "status", "created_at" ], "title": "CreateVideoAgentResponse", "type": "object" }, "SessionListItem": { "description": "A single session in the list response.", "properties": { "session_id": { "description": "Session ID", "title": "Session Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM-generated session title", "title": "Title" }, "created_at": { "description": "Unix timestamp of session creation", "title": "Created At", "type": "integer" } }, "required": [ "session_id", "created_at" ], "title": "SessionListItem", "type": "object" }, "StyleItem": { "description": "A single style in the listing response.", "properties": { "style_id": { "description": "Unique style identifier. Pass to POST /v3/video-agents as style_id.", "title": "Style Id", "type": "string" }, "name": { "description": "Display name of the style.", "title": "Name", "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Thumbnail image URL (public CDN).", "title": "Thumbnail Url" }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Preview video URL (public CDN, mp4).", "title": "Preview Video Url" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tags (e.g., cinematic, retro-tech, iconic-artist).", "title": "Tags" }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Aspect ratio (e.g., '16:9', '9:16', '1:1').", "title": "Aspect Ratio" } }, "required": [ "style_id", "name" ], "title": "StyleItem", "type": "object" }, "BrandGlossaryItem": { "description": "A single brand glossary entry in the list response.", "properties": { "brand_glossary_id": { "description": "Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.", "title": "Brand Glossary Id", "type": "string" }, "name": { "description": "Display name of the brand glossary.", "title": "Name", "type": "string" }, "created_at": { "description": "Creation timestamp (UTC).", "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "description": "Last update timestamp (UTC).", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "brand_glossary_id", "name", "created_at", "updated_at" ], "title": "BrandGlossaryItem", "type": "object" }, "CreateBrandKitRequest": { "additionalProperties": false, "description": "Request body for POST /v3/brand-kits.", "properties": { "url": { "description": "Public website URL to build the brand kit from. HeyGen visits the site and imports the brand assets it finds there, including logos, colors and font files. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen.", "maxLength": 2048, "title": "Url", "type": "string" }, "name": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "Name for the brand kit, up to 256 characters. Defaults to the brand name detected on the site, or its domain.", "title": "Name" } }, "required": [ "url" ], "title": "CreateBrandKitRequest", "type": "object" }, "CreateBrandKitResponse": { "description": "Response for POST /v3/brand-kits.", "properties": { "brand_kit_id": { "description": "Unique identifier of the newly created brand kit.", "title": "Brand Kit Id", "type": "string" }, "status": { "const": "loading", "description": "Assembly status, always 'loading' on creation: the kit exists and its id is usable immediately, but its assets are gathered in the background. Poll GET /v3/brand-kits/{brand_kit_id} until status is 'completed'.", "title": "Status", "type": "string" } }, "required": [ "brand_kit_id", "status" ], "title": "CreateBrandKitResponse", "type": "object" }, "BrandKitDetail": { "description": "A single brand kit with its colors, logos and fonts.\n\nA brand kit imported from a website is assembled in the background. While `status` is `loading`\nthe collections and role fields are provisional and may be empty or incomplete; the import has\nfinished contributing to them once `status` is `completed`. A kit whose import failed reports\n`error` and keeps whatever was assembled before the failure. A kit can still be edited in the\nHeyGen web app afterwards, so `completed` means the import is done, not that the kit is frozen.", "properties": { "brand_kit_id": { "description": "Unique brand kit identifier.", "title": "Brand Kit Id", "type": "string" }, "name": { "description": "Display name of the brand kit.", "title": "Name", "type": "string" }, "status": { "description": "Assembly status: 'loading' while the kit is still being built, 'completed' when it is ready, or 'error' if the import failed.", "enum": [ "loading", "completed", "error" ], "title": "Status", "type": "string" }, "colors": { "description": "Brand colors as hex values, e.g. '#FF5733'. A color playing a role may sit outside this list \u2014 see color_roles \u2014 so do not treat it as the full set of colors the kit references.", "items": { "type": "string" }, "title": "Colors", "type": "array" }, "color_roles": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitColorRoles" }, { "type": "null" } ], "default": null, "description": "Which color plays which part. May be absent while the kit is still loading." }, "logos": { "description": "Logos belonging to the brand kit.", "items": { "$ref": "#/components/schemas/BrandKitLogo" }, "title": "Logos", "type": "array" }, "logo_roles": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitLogoRoles" }, { "type": "null" } ], "default": null, "description": "Which logo is the main one. May be absent while the kit is still loading." }, "fonts": { "description": "Fonts belonging to the brand kit.", "items": { "$ref": "#/components/schemas/BrandKitFont" }, "title": "Fonts", "type": "array" }, "font_roles": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitFontRoles" }, { "type": "null" } ], "default": null, "description": "Which font plays which typographic part. May be absent while the kit is still loading." } }, "required": [ "brand_kit_id", "name", "status" ], "title": "BrandKitDetail", "type": "object" }, "BrandKitColorRoles": { "description": "Which color plays which part in the brand's visual system, as hex values.\n\nA role may name a color that is not present in `colors`: the palette lists the brand's core\nswatches, while a role such as `tertiary` can point at a supporting surface color outside them.", "properties": { "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary brand color.", "title": "Primary" }, "secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Secondary brand color.", "title": "Secondary" }, "tertiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tertiary brand color.", "title": "Tertiary" }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Accent color, used for highlights and calls to action.", "title": "Accent" } }, "title": "BrandKitColorRoles", "type": "object" }, "BrandKitFont": { "description": "A font belonging to a brand kit.", "properties": { "font_id": { "description": "Unique font identifier. A font_roles entry usually names one of these, but see font_roles for when it does not.", "title": "Font Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Font family name.", "title": "Name" } }, "required": [ "font_id" ], "title": "BrandKitFont", "type": "object" }, "BrandKitFontRole": { "description": "A font assigned to one typographic role.", "properties": { "font_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the assigned font.", "title": "Font Id" }, "weight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Font weight, e.g. 400 for regular or 700 for bold.", "title": "Weight" } }, "title": "BrandKitFontRole", "type": "object" }, "BrandKitFontRoles": { "description": "Which font plays which typographic part.\n\nDeleting a font does not clear the role that named it, so a role's font_id can be absent from\n`fonts`. Match by id and handle the miss rather than assuming a lookup succeeds.", "properties": { "title_text": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitFontRole" }, { "type": "null" } ], "default": null, "description": "Font for headings and titles." }, "body_text": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitFontRole" }, { "type": "null" } ], "default": null, "description": "Font for body copy." } }, "title": "BrandKitFontRoles", "type": "object" }, "BrandKitLogo": { "description": "A logo belonging to a brand kit.", "properties": { "logo_id": { "description": "Unique logo identifier. The logo named by logo_roles.primary is the brand's main logo.", "title": "Logo Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name of the logo.", "title": "Name" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of the logo image. Absent if the logo has no stored file yet.", "title": "Url" } }, "required": [ "logo_id" ], "title": "BrandKitLogo", "type": "object" }, "BrandKitLogoRoles": { "description": "Which logo is the brand's main one.\n\nDeleting a logo does not clear the role that named it, so this can reference a logo_id absent\nfrom `logos`. Match by id and handle the miss rather than assuming a lookup succeeds.", "properties": { "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the primary logo. Names a logo_id in `logos` unless that logo has since been deleted.", "title": "Primary" } }, "title": "BrandKitLogoRoles", "type": "object" }, "UpdateBrandKitRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/brand-kits/{brand_kit_id}.\n\nEvery field is optional and omitting one leaves it unchanged. Sending a role object with no\nfields inside it (`{}`) clears that role, and a cleared role stays cleared \u2014 nothing recomputes\nover a role the caller has deliberately emptied.\n\nClearing is an empty object rather than `null`, and `null` is rejected outright, so each\nintention has exactly one spelling. Generated clients serialise request bodies with\n`exclude_none` and drop a `null` before sending, so honouring `null` as \"clear\" would clear the\nrole for a caller using raw HTTP and silently do nothing for a caller using our own SDK.", "properties": { "name": { "default": null, "description": "New display name for the brand kit, 1-256 characters. Leading and trailing whitespace is trimmed.", "maxLength": 256, "minLength": 1, "title": "Name", "type": "string" }, "color_roles": { "$ref": "#/components/schemas/UpdateBrandKitColorRoles", "default": null, "description": "Which color plays which part, as hex values. Replaces the stored assignment in full: a role you omit from this object is cleared, so send the roles you want to keep. Send `{}` to clear every color role.", "title": "Color Roles" }, "logo_roles": { "$ref": "#/components/schemas/UpdateBrandKitLogoRoles", "default": null, "description": "Which logo is the brand's main one. Replaces the stored assignment in full, like color_roles, so omitting `primary` clears it. Send `{}` to clear the logo role.", "title": "Logo Roles" }, "font_roles": { "$ref": "#/components/schemas/UpdateBrandKitFontRoles", "default": null, "description": "Which font plays which typographic part. Replaces the stored assignment in full, like color_roles.", "title": "Font Roles" } }, "title": "UpdateBrandKitRequest", "type": "object" }, "UpdateBrandKitColorRoles": { "additionalProperties": false, "description": "Color role assignment to write. Unknown keys are rejected.", "properties": { "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary brand color, as a hex value like '#FF5733'.", "title": "Primary" }, "secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Secondary brand color, as a hex value.", "title": "Secondary" }, "tertiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tertiary brand color, as a hex value.", "title": "Tertiary" }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Accent color for highlights and calls to action, as a hex value.", "title": "Accent" } }, "title": "UpdateBrandKitColorRoles", "type": "object" }, "UpdateBrandKitFontRole": { "additionalProperties": false, "description": "One typographic role to write. Unknown keys are rejected.", "properties": { "font_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the font to assign. Not required to appear in the kit's `fonts` list: a role may legitimately name a font variant that the list does not enumerate separately.", "title": "Font Id" }, "weight": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Font weight, 1-1000. E.g. 400 for regular or 700 for bold.", "title": "Weight" } }, "title": "UpdateBrandKitFontRole", "type": "object" }, "UpdateBrandKitFontRoles": { "additionalProperties": false, "description": "Typographic role assignment to write. Unknown keys are rejected.", "properties": { "title_text": { "anyOf": [ { "$ref": "#/components/schemas/UpdateBrandKitFontRole" }, { "type": "null" } ], "default": null, "description": "Font for headings and titles." }, "body_text": { "anyOf": [ { "$ref": "#/components/schemas/UpdateBrandKitFontRole" }, { "type": "null" } ], "default": null, "description": "Font for body copy." } }, "title": "UpdateBrandKitFontRoles", "type": "object" }, "UpdateBrandKitLogoRoles": { "additionalProperties": false, "description": "Logo role assignment to write. Unknown keys are rejected.", "properties": { "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the primary logo. Must be a logo_id belonging to this kit that has finished importing.", "title": "Primary" } }, "title": "UpdateBrandKitLogoRoles", "type": "object" }, "DeleteBrandKitResponse": { "description": "Response for DELETE /v3/brand-kits/{brand_kit_id}.", "properties": { "brand_kit_id": { "description": "Identifier of the deleted brand kit.", "title": "Brand Kit Id", "type": "string" } }, "required": [ "brand_kit_id" ], "title": "DeleteBrandKitResponse", "type": "object" }, "BrandGlossaryDetail": { "description": "A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).", "properties": { "brand_glossary_id": { "description": "Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.", "title": "Brand Glossary Id", "type": "string" }, "name": { "description": "Display name of the brand glossary.", "title": "Name", "type": "string" }, "created_at": { "description": "Creation timestamp (UTC).", "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "description": "Last update timestamp (UTC).", "format": "date-time", "title": "Updated At", "type": "string" }, "terms": { "description": "Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.", "items": { "$ref": "#/components/schemas/BrandGlossaryTerm" }, "title": "Terms", "type": "array" }, "do_not_translate_terms": { "default": null, "description": "Don't Translate rules in this glossary. Omitted when it has none.", "items": { "$ref": "#/components/schemas/DoNotTranslateEntry" }, "title": "Do Not Translate Terms", "type": "array" }, "forced_translations": { "default": null, "description": "Force Translate rules in this glossary. Omitted when it has none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.", "items": { "$ref": "#/components/schemas/ForcedTranslationEntry" }, "title": "Forced Translations", "type": "array" } }, "required": [ "brand_glossary_id", "name", "created_at", "updated_at", "terms" ], "title": "BrandGlossaryDetail", "type": "object" }, "BrandGlossaryTerm": { "description": "One glossary entry: a written term and how it should be spoken.", "properties": { "term": { "description": "The term as written in a script, matched case-insensitively.", "title": "Term", "type": "string" }, "pronunciation": { "description": "Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only \u2014 captions and subtitles keep the original `term` spelling.", "title": "Pronunciation", "type": "string" } }, "required": [ "term", "pronunciation" ], "title": "BrandGlossaryTerm", "type": "object" }, "DoNotTranslateEntry": { "description": "One Don't Translate rule: a term kept untranslated when content is translated.", "properties": { "term": { "description": "A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term \u2014 matched case-insensitively \u2014 is kept untranslated in every target language.", "title": "Term", "type": "string" } }, "required": [ "term" ], "title": "DoNotTranslateEntry", "type": "object" }, "ForcedTranslationEntry": { "description": "One Force Translate rule: a term and the exact translation that replaces it.", "properties": { "term": { "description": "The term to replace, matched in the source text case-insensitively.", "title": "Term", "type": "string" }, "translation": { "description": "The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence.", "title": "Translation", "type": "string" } }, "required": [ "term", "translation" ], "title": "ForcedTranslationEntry", "type": "object" }, "CreateBrandGlossaryRequest": { "additionalProperties": false, "description": "Request body for POST /v3/brand-glossaries.", "properties": { "name": { "description": "Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case.", "maxLength": 64, "minLength": 1, "title": "Name", "type": "string" }, "terms": { "default": [], "description": "Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.", "items": { "$ref": "#/components/schemas/BrandGlossaryTermWrite" }, "title": "Terms", "type": "array" }, "do_not_translate_terms": { "default": [], "description": "Terms to keep untranslated when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none.", "items": { "$ref": "#/components/schemas/DoNotTranslateEntryWrite" }, "title": "Do Not Translate Terms", "type": "array" }, "forced_translations": { "default": [], "description": "Force Translate rules: terms translated into an exact replacement when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.", "items": { "$ref": "#/components/schemas/ForcedTranslationEntryWrite" }, "title": "Forced Translations", "type": "array" } }, "required": [ "name" ], "title": "CreateBrandGlossaryRequest", "type": "object" }, "BrandGlossaryTermWrite": { "description": "One glossary entry as accepted on POST / PATCH: a written term and how it should be spoken.", "properties": { "term": { "description": "The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.", "minLength": 1, "title": "Term", "type": "string" }, "pronunciation": { "description": "Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only \u2014 captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.", "minLength": 1, "title": "Pronunciation", "type": "string" } }, "required": [ "term", "pronunciation" ], "title": "BrandGlossaryTermWrite", "type": "object" }, "DoNotTranslateEntryWrite": { "additionalProperties": false, "description": "One Don't Translate rule as accepted on POST / PATCH bodies.", "properties": { "term": { "description": "A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term \u2014 matched case-insensitively \u2014 is kept untranslated in every target language. Surrounding whitespace is removed and the trimmed value must be non-empty.", "minLength": 1, "title": "Term", "type": "string" } }, "required": [ "term" ], "title": "DoNotTranslateEntryWrite", "type": "object" }, "ForcedTranslationEntryWrite": { "additionalProperties": false, "description": "One Force Translate rule as accepted on POST / PATCH bodies.", "properties": { "term": { "description": "The term to replace, matched in the source text case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.", "minLength": 1, "title": "Term", "type": "string" }, "translation": { "description": "The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence. Surrounding whitespace is removed and the trimmed value must be non-empty.", "minLength": 1, "title": "Translation", "type": "string" } }, "required": [ "term", "translation" ], "title": "ForcedTranslationEntryWrite", "type": "object" }, "UpdateBrandGlossaryRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/brand-glossaries/{brand_glossary_id}.\n\nEach field is replaced independently: a field you omit is left untouched, a field you send\nreplaces that value in full, and an empty array clears that list. There is no way to add a\nsingle entry \u2014 read the glossary, append to the list, and send the whole list back.", "properties": { "name": { "default": null, "description": "New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name.", "maxLength": 64, "minLength": 1, "title": "Name", "type": "string" }, "terms": { "default": null, "description": "Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.", "items": { "$ref": "#/components/schemas/BrandGlossaryTermWrite" }, "title": "Terms", "type": "array" }, "do_not_translate_terms": { "default": null, "description": "Replacement Don't Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all.", "items": { "$ref": "#/components/schemas/DoNotTranslateEntryWrite" }, "title": "Do Not Translate Terms", "type": "array" }, "forced_translations": { "default": null, "description": "Replacement Force Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.", "items": { "$ref": "#/components/schemas/ForcedTranslationEntryWrite" }, "title": "Forced Translations", "type": "array" } }, "title": "UpdateBrandGlossaryRequest", "type": "object" }, "DeleteBrandGlossaryResponse": { "description": "Response for DELETE /v3/brand-glossaries/{brand_glossary_id}.", "properties": { "brand_glossary_id": { "description": "Identifier of the deleted brand glossary.", "title": "Brand Glossary Id", "type": "string" } }, "required": [ "brand_glossary_id" ], "title": "DeleteBrandGlossaryResponse", "type": "object" }, "BrandKitItem": { "description": "A brand kit in the listing response.", "properties": { "brand_kit_id": { "description": "Unique brand kit identifier. Pass to POST /v3/video-agents as brand_kit_id.", "title": "Brand Kit Id", "type": "string" }, "name": { "description": "Display name of the brand kit.", "title": "Name", "type": "string" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary brand logo URL (public CDN).", "title": "Logo Url" }, "colors": { "description": "Brand colors as hex values (e.g., '#FF5733').", "items": { "type": "string" }, "title": "Colors", "type": "array" } }, "required": [ "brand_kit_id", "name" ], "title": "BrandKitItem", "type": "object" }, "CreateAvatarRequestBody": { "description": "Discriminated union for POST /v3/avatars request body.", "discriminator": { "mapping": { "digital_twin": "#/components/schemas/CreateDigitalTwinRequest", "photo": "#/components/schemas/CreatePhotoAvatarRequest", "prompt": "#/components/schemas/CreatePromptAvatarRequest" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CreatePromptAvatarRequest" }, { "$ref": "#/components/schemas/CreateDigitalTwinRequest" }, { "$ref": "#/components/schemas/CreatePhotoAvatarRequest" } ], "title": "CreateAvatarRequestBody" }, "CreateDigitalTwinRequest": { "properties": { "type": { "const": "digital_twin", "description": "Must be 'digital_twin' for digital twin avatars.", "title": "Type", "type": "string" }, "name": { "description": "Name of the avatar.", "title": "Name", "type": "string" }, "file": { "description": "Footage of the avatar \u2014 provide as {\"type\": \"url\", \"url\": \"https://...\"} or {\"type\": \"asset_id\", \"asset_id\": \"...\"}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "File" }, "avatar_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional identity you would like to attach the digital twin to. By default it will create a new identity.", "title": "Avatar Group Id" } }, "required": [ "type", "name", "file" ], "title": "CreateDigitalTwinRequest", "type": "object" }, "CreatePhotoAvatarRequest": { "properties": { "type": { "const": "photo", "description": "Must be 'photo' for photo-based avatars.", "title": "Type", "type": "string" }, "name": { "description": "Name of the avatar.", "title": "Name", "type": "string" }, "file": { "description": "Photo asset of the avatar \u2014 provide as {\"type\": \"url\", \"url\": \"https://...\"} or {\"type\": \"asset_id\", \"asset_id\": \"...\"}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "File" }, "avatar_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional identity you would like to attach the photo avatar to. By default it will create a new identity.", "title": "Avatar Group Id" } }, "required": [ "type", "name", "file" ], "title": "CreatePhotoAvatarRequest", "type": "object" }, "CreatePromptAvatarRequest": { "properties": { "type": { "const": "prompt", "description": "Must be 'prompt' for AI-generated avatars.", "title": "Type", "type": "string" }, "name": { "description": "Name of the avatar.", "title": "Name", "type": "string" }, "prompt": { "description": "Prompt for avatar generation.", "maxLength": 1000, "title": "Prompt", "type": "string" }, "reference_images": { "anyOf": [ { "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "maxItems": 3, "type": "array" }, { "type": "null" } ], "default": null, "description": "Reference images \u2014 each as {\"type\": \"url\", \"url\": \"https://...\"} or {\"type\": \"asset_id\", \"asset_id\": \"...\"}. Max 3.", "title": "Reference Images" }, "avatar_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional identity (group) to save the generated avatar to. By default a new identity is created. If avatar_id is also provided, it must belong to this group.", "title": "Avatar Group Id" }, "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional avatar id to use as the visual reference for the generation. When provided without avatar_group_id, the new avatar is saved to the referenced avatar's group; when provided with avatar_group_id, the avatar must belong to that group and the result is saved there. The referenced avatar must exist and have a usable image, otherwise the request is rejected.", "title": "Avatar Id" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/PromptAvatarAspectRatio" }, { "type": "null" } ], "default": null, "description": "Aspect ratio of the generated avatar image, e.g. '16:9', '9:16', '1:1'. 'auto' and omitting the field are equivalent: the generation model picks, matching the reference image's ratio when one is provided.", "x-cli-default": "auto", "x-mcp-default": "auto" } }, "required": [ "type", "name", "prompt" ], "title": "CreatePromptAvatarRequest", "type": "object" }, "PromptAvatarAspectRatio": { "description": "Aspect ratios supported by prompt-avatar generation.", "enum": [ "auto", "16:9", "9:16", "1:1", "4:5", "5:4" ], "title": "PromptAvatarAspectRatio", "type": "string" }, "CreateAvatarResponse": { "properties": { "avatar_item": { "anyOf": [ { "$ref": "#/components/schemas/AvatarLookItem" }, { "type": "null" } ], "default": null, "description": "The avatar item." }, "avatar_group": { "anyOf": [ { "$ref": "#/components/schemas/AvatarGroupItem" }, { "type": "null" } ], "default": null, "description": "The avatar group." } }, "title": "CreateAvatarResponse", "type": "object" }, "AvatarError": { "description": "Error details for a failed avatar creation.", "properties": { "code": { "description": "Machine-readable error code.", "examples": [ "training_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error description.", "examples": [ "Footage duration must be between 15s and 600s" ], "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "AvatarError", "type": "object" }, "AvatarGroupItem": { "description": "A single avatar group in the list response.\n\nGroups are containers for looks (outfits/styles). To determine avatar type\nand engine compatibility, fetch the looks via GET /v3/avatars/looks.", "properties": { "id": { "description": "Unique avatar group identifier.", "examples": [ "ag_abc123" ], "title": "Id", "type": "string" }, "name": { "description": "Display name of the avatar.", "examples": [ "Anna" ], "title": "Name", "type": "string" }, "preview_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the avatar preview image.", "examples": [ "https://files.heygen.ai/avatar/anna_preview.jpg" ], "title": "Preview Image Url" }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the avatar preview video.", "examples": [ "https://files.heygen.ai/avatar/anna_preview.mp4" ], "title": "Preview Video Url" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Gender of the avatar.", "examples": [ "female" ], "title": "Gender" }, "created_at": { "description": "Unix timestamp (seconds) when the avatar was created.", "examples": [ 1711929600 ], "title": "Created At", "type": "integer" }, "looks_count": { "description": "Number of looks (outfits/styles) available for this avatar.", "examples": [ 3 ], "title": "Looks Count", "type": "integer" }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Default voice ID for this avatar.", "examples": [ "1bd001e7e50f421d891986aad5c8bbd2" ], "title": "Default Voice Id" }, "consent_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The consent status for the group. When null or omitted, no status is recorded; consent may still be required before video generation.", "examples": [ "accepted" ], "title": "Consent Status" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AvatarStatus" }, { "type": "null" } ], "default": null, "description": "Training status of the avatar group. Only present for private avatars.", "examples": [ "completed" ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/AvatarError" }, { "type": "null" } ], "default": null, "description": "Error details. Only present when status is 'failed'." } }, "required": [ "id", "name", "created_at", "looks_count" ], "title": "AvatarGroupItem", "type": "object" }, "AvatarLookItem": { "description": "A single avatar look in the list response.\n\nThe ``id`` field is the look-level identifier to pass as ``avatar_id``\nto POST /v3/videos.", "properties": { "id": { "description": "Unique look identifier. Pass this as avatar_id to POST /v3/videos.", "examples": [ "lk_abc123" ], "title": "Id", "type": "string" }, "name": { "description": "Display name of the look.", "examples": [ "Business Suit" ], "title": "Name", "type": "string" }, "avatar_type": { "$ref": "#/components/schemas/AvatarLookType", "description": "Avatar type \u2014 determines engine and parameter compatibility.", "examples": [ "photo_avatar" ] }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID of the avatar group this look belongs to.", "examples": [ "ag_abc123" ], "title": "Group Id" }, "preview_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the look preview image.", "examples": [ "https://files.heygen.ai/look/business_preview.jpg" ], "title": "Preview Image Url" }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the look preview video.", "examples": [ "https://files.heygen.ai/look/business_preview.mp4" ], "title": "Preview Video Url" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Gender of the avatar.", "examples": [ "female" ], "title": "Gender" }, "tags": { "description": "Tags associated with the look.", "examples": [ [ "business", "formal" ] ], "items": { "type": "string" }, "title": "Tags", "type": "array" }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Default voice ID for this look.", "examples": [ "1bd001e7e50f421d891986aad5c8bbd2" ], "title": "Default Voice Id" }, "supported_api_engines": { "description": "Engine values this look supports for POST /v3/videos. Possible values: 'avatar_v', 'avatar_iv', 'avatar_iii'.", "examples": [ [ "avatar_v", "avatar_iv", "avatar_iii" ] ], "items": { "type": "string" }, "title": "Supported Api Engines", "type": "array" }, "image_width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Native width of the look in pixels.", "examples": [ 1920 ], "title": "Image Width" }, "image_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Native height of the look in pixels.", "examples": [ 1080 ], "title": "Image Height" }, "preferred_orientation": { "anyOf": [ { "enum": [ "portrait", "landscape", "square" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Preferred orientation of the look: 'portrait', 'landscape', or 'square'.", "title": "Preferred Orientation" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AvatarStatus" }, { "type": "null" } ], "default": null, "description": "Training status of the avatar look: 'processing', 'completed', or 'failed'. Only present for private avatars.", "examples": [ "completed" ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/AvatarError" }, { "type": "null" } ], "default": null, "description": "Error details. Only present when status is 'failed'." } }, "required": [ "id", "name", "avatar_type" ], "title": "AvatarLookItem", "type": "object" }, "AvatarLookType": { "description": "Avatar look type \u2014 determines engine compatibility with POST /v3/videos.", "enum": [ "studio_avatar", "digital_twin", "photo_avatar" ], "title": "AvatarLookType", "type": "string" }, "AvatarStatus": { "description": "Training/creation status of an avatar group or look.", "enum": [ "processing", "pending_consent", "failed", "completed" ], "title": "AvatarStatus", "type": "string" }, "CreateAvatarRealtimeRequestBody": { "description": "Discriminated union for POST /v3/avatar-realtime request body.", "discriminator": { "mapping": { "audio": "#/components/schemas/CreateAvatarRealtimeAudio", "text_stream": "#/components/schemas/CreateAvatarRealtimeTextStream", "tts": "#/components/schemas/CreateAvatarRealtimeTTS" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CreateAvatarRealtimeTTS" }, { "$ref": "#/components/schemas/CreateAvatarRealtimeAudio" }, { "$ref": "#/components/schemas/CreateAvatarRealtimeTextStream" } ], "title": "CreateAvatarRealtimeRequestBody" }, "CreateAvatarRealtimeAudio": { "additionalProperties": false, "description": "Create a stream with a pre-existing audio asset.", "properties": { "type": { "const": "audio", "description": "Audio source type: pre-existing audio file.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen photo avatar or motion avatar look ID.", "title": "Avatar Id", "type": "string" }, "audio": { "description": "Audio file input (URL, asset ID, or base64).", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Audio" } }, "required": [ "type", "avatar_id", "audio" ], "title": "CreateAvatarRealtimeAudio", "type": "object" }, "CreateAvatarRealtimeTTS": { "additionalProperties": false, "description": "Create a stream with text-to-speech audio.", "properties": { "type": { "const": "tts", "description": "Audio source type: text-to-speech.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen photo avatar or motion avatar look ID.", "title": "Avatar Id", "type": "string" }, "text": { "description": "Text script for the avatar to speak.", "minLength": 1, "title": "Text", "type": "string" }, "voice_id": { "description": "Voice ID for text-to-speech.", "title": "Voice Id", "type": "string" } }, "required": [ "type", "avatar_id", "text", "voice_id" ], "title": "CreateAvatarRealtimeTTS", "type": "object" }, "CreateAvatarRealtimeTextStream": { "additionalProperties": false, "description": "Create a stream that accepts text deltas pushed over time via the ingest endpoint.\n\nClients POST additional text deltas to /v3/avatar-realtime/{stream_id}/text as they\nbecome available (e.g. as an upstream LLM streams tokens). The session must be\nseeded with a non-empty initial `text` so the avatar has something to start\nspeaking immediately \u2014 otherwise the emitter would idle out before any audio\nis produced.", "properties": { "type": { "const": "text_stream", "description": "Audio source type: streaming text-to-speech.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen photo avatar or motion avatar look ID.", "title": "Avatar Id", "type": "string" }, "voice_id": { "description": "Voice ID for text-to-speech.", "title": "Voice Id", "type": "string" }, "text": { "description": "Initial text seed for the avatar to start speaking. Further text is appended via the ingest endpoint.", "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "type", "avatar_id", "voice_id", "text" ], "title": "CreateAvatarRealtimeTextStream", "type": "object" }, "CreateAvatarRealtimeResponse": { "description": "Response data for POST /v3/avatar-realtime.", "properties": { "stream_id": { "description": "Unique streaming session identifier. Use with GET /v3/avatar-realtime/{stream_id} to poll status.", "title": "Stream Id", "type": "string" } }, "required": [ "stream_id" ], "title": "CreateAvatarRealtimeResponse", "type": "object" }, "AvatarRealtimeStatusResponse": { "description": "Response data for GET /v3/avatar-realtime/{stream_id}.", "properties": { "stream_id": { "description": "Streaming session identifier.", "title": "Stream Id", "type": "string" }, "status": { "description": "Session status: 'pending' (workflow in progress), 'streaming' (HLS URL available), 'completed' (workflow finished \u2014 `end_reason` describes how), or 'error' (workflow failed).", "enum": [ "pending", "streaming", "completed", "error" ], "title": "Status", "type": "string" }, "hls_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HLS streaming session URL. Present only when status is 'streaming'.", "title": "Hls Url" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Present only when status is 'error'.", "title": "Error Message" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "How a 'completed' session terminated. 'final_marker' \u2014 producer sent `final: true`. 'idle_timeout' \u2014 producer went silent and the emitter finalized. Only present for text_stream sessions and only when status is 'completed'.", "title": "End Reason" } }, "required": [ "stream_id", "status" ], "title": "AvatarRealtimeStatusResponse", "type": "object" }, "WordBatch": { "description": "One SSE `data:` payload \u2014 a batch of words that share a ~1s window.", "properties": { "words": { "description": "Words in this batch, ordered by start time.", "items": { "$ref": "#/components/schemas/WordEvent" }, "title": "Words", "type": "array" } }, "required": [ "words" ], "title": "WordBatch", "type": "object" }, "WordEvent": { "description": "One spoken word and its time bounds in the streamed audio.\n\nPunctuation (periods, commas, etc.) is emitted as its own event with its\nown time bounds \u2014 clients that don't care can filter them out. Times are\nin seconds, matching OpenAI Whisper and ElevenLabs alignment APIs.", "properties": { "word": { "description": "The spoken token. May be a word, partial word, or a punctuation mark.", "title": "Word", "type": "string" }, "start": { "description": "Word start time in seconds, measured from the beginning of the streamed audio.", "title": "Start", "type": "number" }, "end": { "description": "Word end time in seconds, measured from the beginning of the streamed audio.", "title": "End", "type": "number" } }, "required": [ "word", "start", "end" ], "title": "WordEvent", "type": "object" }, "AppendTextDeltaRequest": { "additionalProperties": false, "description": "Append one text delta to a streaming session created with type='text_stream'.", "properties": { "delta": { "description": "Text fragment to append. May be a single token or a coalesced batch of tokens. Must be non-empty unless `final: true` (which allows an empty delta to close the stream).", "title": "Delta", "type": "string" }, "final": { "default": false, "description": "If true, this is the last delta \u2014 input is closed after this request. Further POSTs to this stream return 410.", "title": "Final", "type": "boolean" } }, "required": [ "delta" ], "title": "AppendTextDeltaRequest", "type": "object" }, "AppendTextDeltaResponse": { "description": "Response data for POST /v3/avatar-realtime/{stream_id}/text.", "properties": { "ok": { "default": true, "description": "Always true on success.", "title": "Ok", "type": "boolean" }, "buffered_bytes": { "description": "Total bytes of text buffered for this session so far.", "title": "Buffered Bytes", "type": "integer" } }, "required": [ "buffered_bytes" ], "title": "AppendTextDeltaResponse", "type": "object" }, "CancelAvatarRealtimeResponse": { "description": "Response data for POST /v3/avatar-realtime/{stream_id}/cancel.", "properties": { "stream_id": { "description": "Streaming session identifier.", "title": "Stream Id", "type": "string" }, "cancelled": { "description": "True if cancellation was initiated by this request, false if the session was already terminal (completed, failed, or previously cancelled).", "title": "Cancelled", "type": "boolean" } }, "required": [ "stream_id", "cancelled" ], "title": "CancelAvatarRealtimeResponse", "type": "object" }, "TextToSpeechRequest": { "additionalProperties": false, "description": "Request body for text-to-speech generation.", "properties": { "text": { "description": "Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, ); millisecond values are not supported.", "maxLength": 5000, "minLength": 1, "title": "Text", "type": "string" }, "voice_id": { "description": "Voice ID to use. The voice must support the starfish engine. Filter compatible voices by passing engine=starfish to the voice listing endpoint.", "title": "Voice Id", "type": "string" }, "input_type": { "default": "text", "description": "Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.", "title": "Input Type", "type": "string" }, "speed": { "default": 1.0, "description": "Speed multiplier (0.5-2.0).", "maximum": 2.0, "minimum": 0.5, "title": "Speed", "type": "number" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base language code (e.g. 'en', 'pt', 'zh'). Optional \u2014 auto-detected from text when omitted.", "title": "Language" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "BCP-47 locale tag (e.g. 'en-US', 'pt-BR'). When set, language is inferred from locale.", "title": "Locale" } }, "required": [ "text", "voice_id" ], "title": "TextToSpeechRequest", "type": "object" }, "TextToSpeechResponseData": { "description": "Response payload for text-to-speech generation.", "properties": { "audio_url": { "description": "URL of the generated audio file.", "examples": [ "https://files.heygen.ai/audio/tts_abc123.mp3" ], "title": "Audio Url", "type": "string" }, "duration": { "description": "Duration of the audio in seconds.", "examples": [ 4.5 ], "title": "Duration", "type": "number" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unique identifier for this generation request.", "examples": [ "req_abc123" ], "title": "Request Id" }, "word_timestamps": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WordWithTimestamp" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Word-level timing data.", "title": "Word Timestamps" } }, "required": [ "audio_url", "duration" ], "title": "TextToSpeechResponseData", "type": "object" }, "WordWithTimestamp": { "description": "Word-level timing data from TTS generation.", "properties": { "word": { "description": "The word.", "examples": [ "Hello" ], "title": "Word", "type": "string" }, "start": { "description": "Start time in seconds.", "examples": [ 0.0 ], "title": "Start", "type": "number" }, "end": { "description": "End time in seconds.", "examples": [ 0.35 ], "title": "End", "type": "number" } }, "required": [ "word", "start", "end" ], "title": "WordWithTimestamp", "type": "object" }, "AudioVoiceItem": { "description": "A single voice in the listing response.", "properties": { "voice_id": { "description": "Unique voice identifier.", "examples": [ "1bd001e7e50f421d891986aad5c8bbd2" ], "title": "Voice Id", "type": "string" }, "name": { "description": "Display name of the voice.", "examples": [ "Sara" ], "title": "Name", "type": "string" }, "language": { "description": "Primary language of the voice.", "examples": [ "English" ], "title": "Language", "type": "string" }, "gender": { "description": "Gender of the voice.", "examples": [ "female" ], "title": "Gender", "type": "string" }, "preview_audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a short audio preview of the voice.", "examples": [ "https://files.heygen.ai/voice/preview_sara.mp3" ], "title": "Preview Audio Url" }, "support_pause": { "description": "Whether the voice supports SSML pause/break tags.", "examples": [ true ], "title": "Support Pause", "type": "boolean" }, "support_locale": { "description": "Whether the voice supports locale variants.", "examples": [ true ], "title": "Support Locale", "type": "boolean" }, "type": { "$ref": "#/components/schemas/AudioVoiceType", "description": "Whether this is a public or private voice.", "examples": [ "public" ] } }, "required": [ "voice_id", "name", "language", "gender", "support_pause", "support_locale", "type" ], "title": "AudioVoiceItem", "type": "object" }, "AudioVoiceType": { "enum": [ "public", "private" ], "title": "AudioVoiceType", "type": "string" }, "AudioSoundItem": { "description": "A single audio track in the catalog search response.", "properties": { "id": { "description": "Unique identifier for the audio track.", "examples": [ "rev_abc123" ], "title": "Id", "type": "string" }, "name": { "description": "Display name of the audio track.", "examples": [ "Upbeat Lofi Loop" ], "title": "Name", "type": "string" }, "description": { "description": "Semantic description the track was indexed under.", "examples": [ "Jazz, happy, jazzy, upbeat, rhythmic" ], "title": "Description", "type": "string" }, "audio_url": { "description": "Temporary pre-signed URL to download the audio file. Expires; do not cache long-term.", "examples": [ "https://files.heygen.ai/audio/music_abc123.mp3" ], "title": "Audio Url", "type": "string" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Duration of the audio in seconds, when known.", "examples": [ 120.0 ], "title": "Duration" }, "peak_offset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "For sound effects, seconds from clip start to the loudest RMS peak. Null for tracks without placement metadata.", "examples": [ 0.37 ], "title": "Peak Offset" }, "placement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "For sound effects, suggested placement mode: 'hit', 'riser', or 'bed'. Null for tracks without placement metadata.", "examples": [ "hit" ], "title": "Placement" }, "score": { "description": "Semantic similarity score (0-1); higher means a closer match.", "examples": [ 0.83 ], "title": "Score", "type": "number" }, "type": { "$ref": "#/components/schemas/AudioContentType", "description": "Audio content type of this track.", "examples": [ "music" ] } }, "required": [ "id", "name", "description", "audio_url", "score", "type" ], "title": "AudioSoundItem", "type": "object" }, "AudioContentType": { "description": "Audio content type for catalog search. Each value maps to its own Pinecone namespace\n(see music_search._NAMESPACE_BY_TYPE).", "enum": [ "music", "sound_effects" ], "title": "AudioContentType", "type": "string" }, "DesignVoiceRequest": { "additionalProperties": false, "description": "Request body for POST /v3/voices \u2014 design a voice via semantic search.", "properties": { "prompt": { "description": "Natural language description of the desired voice (e.g., 'warm, confident female narrator').", "maxLength": 1000, "minLength": 1, "title": "Prompt", "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Filter by gender: 'male' or 'female'.", "title": "Gender" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "BCP-47 locale tag to filter by (e.g., 'en-US', 'pt-BR').", "title": "Locale" }, "seed": { "default": 0, "description": "Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices.", "minimum": 0, "title": "Seed", "type": "integer" } }, "required": [ "prompt" ], "title": "DesignVoiceRequest", "type": "object" }, "DesignVoiceResponseData": { "description": "Response payload for POST /v3/voices.", "properties": { "voices": { "description": "Matching voices for the given prompt, ordered by relevance.", "items": { "$ref": "#/components/schemas/AudioVoiceItem" }, "title": "Voices", "type": "array" }, "seed": { "description": "The seed used for this request. Increment to get different voices.", "title": "Seed", "type": "integer" } }, "required": [ "voices", "seed" ], "title": "DesignVoiceResponseData", "type": "object" }, "CreateVoiceCloneV3Request": { "additionalProperties": false, "description": "Request body for POST /v3/voices/clone.", "properties": { "audio": { "description": "Audio file for voice cloning. Provide as {type: 'url', url: '...'}, {type: 'asset_id', asset_id: '...'}, or {type: 'base64', media_type: '...', data: '...'}.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Audio" }, "voice_name": { "description": "Display name for the cloned voice.", "maxLength": 100, "minLength": 1, "title": "Voice Name", "type": "string" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Language hint for the voice (e.g., 'en', 'es'). Auto-detected if omitted.", "title": "Language" }, "remove_background_noise": { "default": true, "description": "Remove background noise from the audio before cloning.", "title": "Remove Background Noise", "type": "boolean" } }, "required": [ "audio", "voice_name" ], "title": "CreateVoiceCloneV3Request", "type": "object" }, "VoiceCloneCreateV3Response": { "description": "Response for POST /v3/voices/clone.", "properties": { "voice_clone_id": { "description": "Voice clone ID. Use GET /v3/voices/{voice_clone_id} to poll status.", "title": "Voice Clone Id", "type": "string" } }, "required": [ "voice_clone_id" ], "title": "VoiceCloneCreateV3Response", "type": "object" }, "CreateModelAudioVoiceRequest": { "additionalProperties": false, "description": "Create or retrain one model-backed audio voice.", "properties": { "mode": { "anyOf": [ { "$ref": "#/components/schemas/ModelAudioVoiceMode" }, { "type": "null" } ], "default": null, "description": "Voice operation mode for a new voice. Ignored when `voice_id` is supplied; the existing mode is retained. Currently only `professional` is supported." }, "voice_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^\\S+$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing professional voice to retrain. Omit to create a new voice.", "title": "Voice Id" }, "name": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name for a new voice. Ignored when `voice_id` is supplied; the existing name is retained.", "title": "Name" }, "language": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary language code, such as `en`, for a new voice. Ignored when `voice_id` is supplied; the existing language is retained.", "title": "Language" }, "audio": { "description": "Source recordings of the same speaker. Each item may be a public HTTPS URL, a HeyGen asset ID, or base64-encoded audio. The recordings must contain at least 20 minutes of audio and no more than 1.5 GB (1,500,000,000 bytes) in total.", "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "maxItems": 10, "minItems": 1, "title": "Audio", "type": "array" } }, "required": [ "audio" ], "title": "CreateModelAudioVoiceRequest", "type": "object" }, "ModelAudioVoiceMode": { "description": "Supported audio-voice creation implementations.", "enum": [ "professional" ], "title": "ModelAudioVoiceMode", "type": "string" }, "CreateModelAudioVoiceResponse": { "additionalProperties": false, "description": "Identifier returned after voice creation or retraining is accepted.", "properties": { "voice_id": { "description": "Stable identifier to use when retrieving the voice and its training status.", "title": "Voice Id", "type": "string" } }, "required": [ "voice_id" ], "title": "CreateModelAudioVoiceResponse", "type": "object" }, "CreateSpeechRequest": { "additionalProperties": false, "properties": { "voice_id": { "description": "Identifier of the voice used for speech synthesis.", "minLength": 1, "title": "Voice Id", "type": "string" }, "text": { "description": "Plain text to synthesize. SSML and break tags are not supported.", "maxLength": 5000, "minLength": 1, "title": "Text", "type": "string" }, "language": { "description": "Language code used for speech synthesis, such as `en`.", "minLength": 1, "title": "Language", "type": "string" }, "seed": { "anyOf": [ { "maximum": 4294967295, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional best-effort deterministic generation seed.", "title": "Seed" } }, "required": [ "voice_id", "text", "language" ], "title": "CreateSpeechRequest", "type": "object" }, "CreateSpeechResponseData": { "properties": { "audio_url": { "description": "URL of the generated audio file.", "title": "Audio Url", "type": "string" }, "duration": { "description": "Duration of the generated audio in seconds.", "minimum": 0, "title": "Duration", "type": "number" } }, "required": [ "audio_url", "duration" ], "title": "CreateSpeechResponseData", "type": "object" }, "StreamSpeechRequest": { "additionalProperties": false, "properties": { "voice_id": { "description": "Identifier of the voice used for speech synthesis.", "minLength": 1, "title": "Voice Id", "type": "string" }, "text": { "description": "Plain text to synthesize. SSML and break tags are not supported.", "maxLength": 5000, "minLength": 1, "title": "Text", "type": "string" }, "language": { "description": "Language code used for speech synthesis, such as `en`.", "minLength": 1, "title": "Language", "type": "string" }, "seed": { "anyOf": [ { "maximum": 4294967295, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional best-effort deterministic generation seed.", "title": "Seed" }, "with_timestamps": { "default": false, "description": "Whether to include word-timestamp events in the response stream.", "title": "With Timestamps", "type": "boolean" } }, "required": [ "voice_id", "text", "language" ], "title": "StreamSpeechRequest", "type": "object" }, "SpeechStreamEvent": { "description": "One JSON event carried by the speech SSE stream.", "discriminator": { "mapping": { "alignment": "#/components/schemas/SpeechAlignmentEvent", "audio": "#/components/schemas/SpeechAudioEvent", "error": "#/components/schemas/SpeechErrorEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/SpeechAudioEvent" }, { "$ref": "#/components/schemas/SpeechAlignmentEvent" }, { "$ref": "#/components/schemas/SpeechErrorEvent" } ], "title": "SpeechStreamEvent" }, "SpeechAlignmentEvent": { "properties": { "type": { "const": "alignment", "description": "Event type.", "title": "Type", "type": "string" }, "word_alignments": { "description": "Word-level timing information for the generated speech.", "items": { "$ref": "#/components/schemas/SpeechWordAlignment" }, "minItems": 1, "title": "Word Alignments", "type": "array" } }, "required": [ "type", "word_alignments" ], "title": "SpeechAlignmentEvent", "type": "object" }, "SpeechAudioEvent": { "properties": { "type": { "const": "audio", "description": "Event type.", "title": "Type", "type": "string" }, "part_index": { "description": "Zero-based sequence number of this audio part.", "minimum": 0, "title": "Part Index", "type": "integer" }, "audio": { "description": "Base64-encoded standalone WAV audio part.", "title": "Audio", "type": "string" } }, "required": [ "type", "part_index", "audio" ], "title": "SpeechAudioEvent", "type": "object" }, "SpeechErrorEvent": { "properties": { "type": { "const": "error", "description": "Event type.", "title": "Type", "type": "string" }, "detail": { "description": "Sanitized description of a failure that occurred after streaming began.", "title": "Detail", "type": "string" } }, "required": [ "type", "detail" ], "title": "SpeechErrorEvent", "type": "object" }, "SpeechWordAlignment": { "properties": { "text": { "description": "Word represented by this alignment entry.", "minLength": 1, "title": "Text", "type": "string" }, "start_time": { "description": "Word start time in seconds.", "minimum": 0, "title": "Start Time", "type": "number" }, "end_time": { "description": "Word end time in seconds.", "minimum": 0, "title": "End Time", "type": "number" }, "confidence": { "description": "Alignment confidence from 0 to 1.", "maximum": 1, "minimum": 0, "title": "Confidence", "type": "number" } }, "required": [ "text", "start_time", "end_time", "confidence" ], "title": "SpeechWordAlignment", "type": "object" }, "ModelAudioVoiceResponse": { "additionalProperties": false, "description": "Customer-visible state of one model-backed audio voice.", "properties": { "voice_id": { "description": "Stable identifier for this voice.", "title": "Voice Id", "type": "string" }, "mode": { "$ref": "#/components/schemas/ModelAudioVoiceMode", "description": "Voice creation mode." }, "name": { "description": "Display name of the voice.", "title": "Name", "type": "string" }, "language": { "description": "Primary language code supplied when the voice was created.", "title": "Language", "type": "string" }, "status": { "$ref": "#/components/schemas/VideoTTSVoiceStatus", "description": "Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`." }, "created_at": { "description": "Unix timestamp in seconds when the voice was created.", "title": "Created At", "type": "integer" }, "failure_reason": { "anyOf": [ { "$ref": "#/components/schemas/VideoTTSVoiceFailureReason" }, { "type": "null" } ], "default": null, "description": "Stable failure code. Present only when `status` is `FAILED`." } }, "required": [ "voice_id", "mode", "name", "language", "status", "created_at" ], "title": "ModelAudioVoiceResponse", "type": "object" }, "VideoTTSVoiceFailureReason": { "description": "Stable failure codes persisted for terminal training failures.", "enum": [ "INVALID_AUDIO", "INSUFFICIENT_AUDIO", "PREPROCESSING_FAILED", "TRAINING_FAILED", "DESIGN_FAILED", "ARTIFACT_VALIDATION_FAILED", "INTERNAL_ERROR" ], "title": "VideoTTSVoiceFailureReason", "type": "string" }, "VideoTTSVoiceStatus": { "description": "Values persisted in ``video_tts_voices.status``.", "enum": [ "PENDING", "ACTIVE", "FAILED" ], "title": "VideoTTSVoiceStatus", "type": "string" }, "DeleteModelAudioVoiceResponse": { "additionalProperties": false, "description": "Confirmation returned after an audio voice is deleted.", "properties": { "status": { "const": "ok", "default": "ok", "description": "Always `ok` when the voice was deleted successfully.", "title": "Status", "type": "string" } }, "title": "DeleteModelAudioVoiceResponse", "type": "object" }, "VoiceDetailV3": { "description": "Response payload for GET /v3/voices/{voice_id}.", "properties": { "voice_id": { "description": "Unique voice identifier.", "title": "Voice Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name of the voice. Only present when the voice record exists.", "title": "Name" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary language of the voice. Only present when the voice record exists.", "title": "Language" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Gender of the voice (e.g., 'male', 'female'). Only present when the voice record exists.", "title": "Gender" }, "preview_audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a short preview audio clip. Only present for completed voices.", "title": "Preview Audio Url" }, "status": { "anyOf": [ { "enum": [ "processing", "complete", "failed" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Clone status. Only present for cloned voices.", "title": "Status" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status is 'failed'.", "title": "Failure Message" }, "support_pause": { "description": "Whether the voice supports SSML pause/break tags.", "title": "Support Pause", "type": "boolean" }, "support_interactive_avatar": { "default": false, "description": "Whether the voice supports interactive avatar streaming.", "title": "Support Interactive Avatar", "type": "boolean" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the voice was created.", "title": "Created At" } }, "required": [ "voice_id", "support_pause" ], "title": "VoiceDetailV3", "type": "object" }, "VoiceDeleteV3Response": { "description": "Response for DELETE /v3/voices/{voice_id}.", "properties": { "voice_id": { "description": "ID of the deleted voice.", "title": "Voice Id", "type": "string" } }, "required": [ "voice_id" ], "title": "VoiceDeleteV3Response", "type": "object" }, "CreateAvatarVideoRequest": { "description": "Request body for POST /v2/videos \u2014 unified video creation.", "properties": { "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen avatar ID (photo avatar or video avatar). Mutually exclusive with image_url and image_asset_id.", "title": "Avatar Id" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an image to animate. Mutually exclusive with avatar_id and image_asset_id.", "title": "Image Url" }, "image_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded image. Mutually exclusive with avatar_id and image_url.", "title": "Image Asset Id" }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion. Photo avatars only.", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level: 'high', 'medium', or 'low'. Photo avatars only. Defaults to 'low' when omitted." }, "remove_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Remove the avatar background. Video avatars must be trained with matting enabled.", "title": "Remove Background" }, "background": { "anyOf": [ { "$ref": "#/components/schemas/BackgroundSetting" }, { "type": "null" } ], "default": null, "description": "Background settings for the video." }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically \u2014 the caller does not need to set 'remove_background'." } }, "title": "CreateAvatarVideoRequest", "type": "object" }, "BackgroundSetting": { "description": "Background configuration for the generated video.", "properties": { "type": { "description": "Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.", "enum": [ "color", "image" ], "title": "Type", "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Hex color code (e.g. '#ff0000'). Required when type is 'color'.", "title": "Value" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.", "title": "Url" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.", "title": "Asset Id" } }, "required": [ "type" ], "title": "BackgroundSetting", "type": "object" }, "CaptionFileFormat": { "description": "Supported caption file output formats.", "enum": [ "srt" ], "title": "CaptionFileFormat", "type": "string" }, "CaptionSetting": { "description": "Caption generation settings for video creation.\n\nA sidecar subtitle file is always generated and returned via ``subtitle_url``\nin the chosen ``file_format``. When ``style`` is also set, captions are\nadditionally burned into the rendered video \u2014 the sidecar is still delivered.", "properties": { "file_format": { "$ref": "#/components/schemas/CaptionFileFormat", "default": "srt", "description": "Output format for the sidecar caption file." }, "style": { "anyOf": [ { "$ref": "#/components/schemas/CaptionStyle" }, { "type": "null" } ], "default": null, "description": "Visual style for burning captions into the rendered video. Omit for sidecar-only captions." } }, "title": "CaptionSetting", "type": "object" }, "CaptionStyle": { "description": "Visual style applied when burning captions into the rendered video.", "enum": [ "default" ], "title": "CaptionStyle", "type": "string" }, "ElevenLabsEngineSettings": { "description": "Engine-specific voice settings for ElevenLabs-backed voices.\n\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\nWhen using eleven_v3, stability must be 0, 0.5, or 1.", "properties": { "model": { "anyOf": [ { "$ref": "#/components/schemas/ElevenLabsModel" }, { "type": "null" } ], "default": null, "description": "The model ID to use for ElevenLabs." }, "similarity_boost": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "The similarity boost parameter for ElevenLabs.", "title": "Similarity Boost" }, "stability": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "The stability parameter for ElevenLabs.", "title": "Stability" }, "style": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "The style parameter for ElevenLabs.", "title": "Style" }, "use_speaker_boost": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether to use speaker boost for ElevenLabs.", "title": "Use Speaker Boost" }, "engine_type": { "const": "elevenlabs", "description": "Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.", "title": "Engine Type", "type": "string" } }, "required": [ "engine_type" ], "title": "ElevenLabsEngineSettings", "type": "object" }, "ElevenLabsModel": { "description": "ElevenLabs model IDs exposed on the public API.\n\nOnly current models are included \u2014 deprecated models (monolingual_v1, multilingual_v1,\nturbo_v2) are not accepted.", "enum": [ "eleven_multilingual_v2", "eleven_turbo_v2_5", "eleven_flash_v2_5", "eleven_v3" ], "title": "ElevenLabsModel", "type": "string" }, "Expressiveness": { "description": "Avatar expressiveness level for photo avatars.", "enum": [ "high", "medium", "low" ], "title": "Expressiveness", "type": "string" }, "FishEngineSettings": { "description": "Engine-specific voice settings for Fish Audio-backed voices.\n\nInherits Fish's tuning fields (model, stability, similarity).", "properties": { "model": { "anyOf": [ { "$ref": "#/components/schemas/FishModel" }, { "type": "null" } ], "default": null, "description": "Fish Audio model version (default 's1')." }, "stability": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Stability parameter; higher is more consistent.", "title": "Stability" }, "similarity": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Similarity parameter; how closely to match the source voice.", "title": "Similarity" }, "engine_type": { "const": "fish", "description": "Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.", "title": "Engine Type", "type": "string" } }, "required": [ "engine_type" ], "title": "FishEngineSettings", "type": "object" }, "FishModel": { "description": "Fish Audio model version.", "enum": [ "s1", "s2-pro" ], "title": "FishModel", "type": "string" }, "StarfishEngineSettings": { "description": "Engine-selection for Starfish-backed voices.\n\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\nStarfish routing on voices that support multiple engines.", "properties": { "engine_type": { "const": "starfish", "description": "Engine type discriminator. Must be 'starfish' for Starfish-backed voices.", "title": "Engine Type", "type": "string" } }, "required": [ "engine_type" ], "title": "StarfishEngineSettings", "type": "object" }, "VideoAspectRatio": { "description": "Output video aspect ratio.\n\n- ``16:9`` / ``9:16``: classic landscape / portrait.\n- ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to\n the requested resolution (e.g. ``1080p`` 1:1 \u2192 1080x1080, ``1080p`` 4:5 \u2192 1080x1350).\n- ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's\n source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``),\n short-edge anchored to the requested resolution and capped at the tier's long edge.\n Falls back to ``16:9`` when source dimensions can't be read.", "enum": [ "16:9", "9:16", "4:5", "5:4", "1:1", "auto" ], "title": "VideoAspectRatio", "type": "string" }, "VideoOutputFormat": { "description": "Output container for the generated video.", "enum": [ "mp4", "webm" ], "title": "VideoOutputFormat", "type": "string" }, "VideoResolution": { "description": "Output video resolution.\n\nAvatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is\ncomposited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III\ndigital twins and studio avatars.", "enum": [ "4k", "1080p", "720p" ], "title": "VideoResolution", "type": "string" }, "VoiceSettingsInput": { "description": "Voice tuning parameters for text-to-speech.\n\nApplies only when 'script' + 'voice_id' are provided \u2014 not when audio_url/audio_asset_id\nis used (uploaded audio bypasses TTS).", "properties": { "speed": { "default": 1.0, "description": "Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).", "maximum": 1.5, "minimum": 0.5, "title": "Speed", "type": "number" }, "pitch": { "default": 0.0, "description": "Pitch adjustment in semitones. -50 to +50.", "maximum": 50.0, "minimum": -50.0, "title": "Pitch", "type": "number" }, "volume": { "default": 1.0, "description": "Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.", "maximum": 1.0, "minimum": 0.0, "title": "Volume", "type": "number" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Locale/accent hint for multi-lingual voices (e.g. 'en-US').", "title": "Locale" }, "engine_settings": { "anyOf": [ { "discriminator": { "mapping": { "elevenlabs": "#/components/schemas/ElevenLabsEngineSettings", "fish": "#/components/schemas/FishEngineSettings", "starfish": "#/components/schemas/StarfishEngineSettings" }, "propertyName": "engine_type" }, "oneOf": [ { "$ref": "#/components/schemas/ElevenLabsEngineSettings" }, { "$ref": "#/components/schemas/FishEngineSettings" }, { "$ref": "#/components/schemas/StarfishEngineSettings" } ] }, { "type": "null" } ], "default": null, "description": "Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.", "title": "Engine Settings" } }, "title": "VoiceSettingsInput", "type": "object" }, "CreateAvatarVideoResponse": { "properties": { "video_id": { "description": "Unique identifier for the created video.", "examples": [ "v_abc123def456" ], "title": "Video Id", "type": "string" }, "status": { "description": "Initial video status (e.g. 'waiting').", "examples": [ "waiting" ], "title": "Status", "type": "string" }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Resolved output format for the video." } }, "required": [ "video_id", "status" ], "title": "CreateAvatarVideoResponse", "type": "object" }, "VideoDetail": { "description": "Video resource returned by list and detail endpoints.\n\nIf ``output_language`` is present the video is a translated video;\notherwise it is a generated video.", "properties": { "id": { "description": "Unique video identifier", "examples": [ "v_abc123def456" ], "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video title", "examples": [ "My Generated Video" ], "title": "Title" }, "status": { "$ref": "#/components/schemas/VideoStatus", "description": "Current video status", "examples": [ "completed" ] }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp of creation", "examples": [ 1711929600 ], "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when video generation finished", "examples": [ 1711930200 ], "title": "Completed At" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned URL to download the video file", "examples": [ "https://files.heygen.ai/video/abc123.mp4" ], "title": "Video Url" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to video thumbnail image", "examples": [ "https://files.heygen.ai/thumb/abc123.jpg" ], "title": "Thumbnail Url" }, "gif_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to animated GIF preview", "examples": [ "https://files.heygen.ai/gif/abc123.gif" ], "title": "Gif Url" }, "captioned_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned URL to download the video file with captions burned in", "examples": [ "https://files.heygen.ai/video/abc123_captioned.mp4" ], "title": "Captioned Video Url" }, "subtitle_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned URL to download the SRT subtitle file", "examples": [ "https://files.heygen.ai/srt/abc123.srt" ], "title": "Subtitle Url" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds", "examples": [ 30.5 ], "title": "Duration" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID of containing folder", "examples": [ "folder_abc123" ], "title": "Folder Id" }, "output_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "BCP-47 output language code. Present only for translated videos.", "examples": [ "en-US" ], "title": "Output Language" }, "failure_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Machine-readable failure reason. Only present when status is failed.", "examples": [ "rendering_failed" ], "title": "Failure Code" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable failure description. Only present when status is failed.", "examples": [ "Avatar rendering timed out" ], "title": "Failure Message" }, "video_page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the video page in the HeyGen app", "examples": [ "https://app.heygen.com/video/abc123" ], "title": "Video Page Url" } }, "required": [ "id", "status" ], "title": "VideoDetail", "type": "object" }, "VideoStatus": { "enum": [ "pending", "processing", "completed", "failed" ], "title": "VideoStatus", "type": "string" }, "DeleteVideoResponse": { "properties": { "id": { "description": "ID of the deleted video", "examples": [ "v_abc123def456" ], "title": "Id", "type": "string" }, "deleted": { "default": true, "description": "Always true on success", "examples": [ true ], "title": "Deleted", "type": "boolean" } }, "required": [ "id" ], "title": "DeleteVideoResponse", "type": "object" }, "CreateVideoV3RequestBody": { "description": "Discriminated union for POST /v3/videos request body.", "discriminator": { "mapping": { "avatar": "#/components/schemas/CreateVideoFromAvatar", "cinematic_avatar": "#/components/schemas/CreateVideoFromCinematicAvatar", "image": "#/components/schemas/CreateVideoFromImage", "studio": "#/components/schemas/CreateVideoFromStudio" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CreateVideoFromAvatar" }, { "$ref": "#/components/schemas/CreateVideoFromImage" }, { "$ref": "#/components/schemas/CreateVideoFromCinematicAvatar" }, { "$ref": "#/components/schemas/CreateVideoFromStudio" } ], "title": "CreateVideoV3RequestBody" }, "AvatarFit": { "description": "How the avatar is scaled to the output canvas.", "enum": [ "contain", "cover" ], "title": "AvatarFit", "type": "string" }, "AvatarIIIEngineConfig": { "additionalProperties": false, "description": "Avatar III engine configuration.\n\nA single engine value that resolves to the right product by the avatar's\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\navatars):\n\n- video avatar looks (``digital_twin``, ``studio_avatar``) -> Digital Twin\n (supports 4K)\n- ``photo_avatar`` look -> Photo Avatar (no 4K output)\n\nNot supported for raw image input (``type: \"image\"``).\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.", "properties": { "type": { "const": "avatar_iii", "description": "Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.", "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "AvatarIIIEngineConfig", "type": "object" }, "AvatarIVEngineConfig": { "additionalProperties": false, "description": "Avatar IV engine configuration (default behavior).", "properties": { "type": { "const": "avatar_iv", "description": "Engine type discriminator. Must be 'avatar_iv'.", "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "AvatarIVEngineConfig", "type": "object" }, "AvatarVEngineConfig": { "additionalProperties": false, "description": "Avatar V engine configuration with cross-reference-driven animation.", "properties": { "type": { "const": "avatar_v", "description": "Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.", "title": "Type", "type": "string" }, "reference_look_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.", "title": "Reference Look Id" } }, "required": [ "type" ], "title": "AvatarVEngineConfig", "type": "object" }, "AvatarVideoScene": { "additionalProperties": false, "description": "A whole-frame speaking scene backed by an avatar.", "properties": { "type": { "const": "avatar_video", "description": "Must be 'avatar_video' for an avatar speaking scene.", "title": "Type", "type": "string" }, "input": { "$ref": "#/components/schemas/StudioAvatarInput", "description": "Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look \u2014 video avatars and photo avatars alike (pass a photo avatar's look id to get a talking photo). The scene duration is derived server-side from the audio." } }, "required": [ "type", "input" ], "title": "AvatarVideoScene", "type": "object" }, "CreateVideoFromAvatar": { "additionalProperties": false, "description": "Create a video from a HeyGen avatar (video or photo avatar).\n\nProvide an avatar_id to use a previously created avatar. Supports all\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\nserver defaults to Avatar IV.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.", "title": "Folder Id" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "fit": { "anyOf": [ { "$ref": "#/components/schemas/AvatarFit" }, { "type": "null" } ], "default": null, "description": "How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations." }, "background": { "anyOf": [ { "$ref": "#/components/schemas/BackgroundSetting" }, { "type": "null" } ], "default": null, "description": "Background settings for the video." }, "remove_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Remove the avatar background. Video avatars must be trained with matting enabled.", "title": "Remove Background" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically \u2014 the caller does not need to set 'remove_background'." }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "type": { "const": "avatar", "description": "Must be 'avatar' for avatar-based video creation.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen avatar ID (video avatar or photo avatar look ID).", "title": "Avatar Id", "type": "string" }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'." }, "engine": { "anyOf": [ { "discriminator": { "mapping": { "avatar_iii": "#/components/schemas/AvatarIIIEngineConfig", "avatar_iv": "#/components/schemas/AvatarIVEngineConfig", "avatar_v": "#/components/schemas/AvatarVEngineConfig" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AvatarVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIIIEngineConfig" } ] }, { "type": "null" } ], "default": null, "description": "Engine configuration for video generation. Pass {\"type\": \"avatar_v\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.", "title": "Engine" } }, "required": [ "type", "avatar_id" ], "title": "CreateVideoFromAvatar", "type": "object" }, "CreateVideoFromCinematicAvatar": { "additionalProperties": false, "description": "Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\n\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\nreference content: one to three avatar looks and optional reference assets\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\nno script or voice \u2014 motion and speech are driven entirely by the prompt and\nthe supplied references. Backed by the Seedance generation pipeline.", "properties": { "type": { "const": "cinematic_avatar", "description": "Must be 'cinematic_avatar' for prompt-and-reference video creation.", "title": "Type", "type": "string" }, "prompt": { "description": "Natural-language prompt describing the video to generate.", "maxLength": 10000, "minLength": 1, "title": "Prompt", "type": "string" }, "avatar_id": { "description": "Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.", "items": { "type": "string" }, "title": "Avatar Id", "type": "array" }, "references": { "anyOf": [ { "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.", "title": "References" }, "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.", "enum": [ "16:9", "9:16", "1:1" ], "title": "Aspect Ratio", "type": "string" }, "resolution": { "default": "720p", "description": "Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.", "enum": [ "720p", "1080p" ], "title": "Resolution", "type": "string" }, "auto_duration": { "default": false, "description": "Let the model choose the video length. When true, omit duration.", "title": "Auto Duration", "type": "boolean" }, "duration": { "anyOf": [ { "maximum": 15, "minimum": 4, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Video length in seconds (4\u201315). Defaults to 10. Omit when auto_duration is true.", "title": "Duration" }, "enhance_prompt": { "default": false, "description": "Enable server-side prompt enhancement.", "title": "Enhance Prompt", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.", "title": "Folder Id" } }, "required": [ "type", "prompt", "avatar_id" ], "title": "CreateVideoFromCinematicAvatar", "type": "object" }, "CreateVideoFromImage": { "additionalProperties": false, "description": "Create a video by animating an arbitrary image.\n\nProvide an image via URL, asset ID, or inline base64. The image will be\nanimated with lip-sync to the provided audio or generated speech.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.", "title": "Folder Id" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "fit": { "anyOf": [ { "$ref": "#/components/schemas/AvatarFit" }, { "type": "null" } ], "default": null, "description": "How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations." }, "background": { "anyOf": [ { "$ref": "#/components/schemas/BackgroundSetting" }, { "type": "null" } ], "default": null, "description": "Background settings for the video." }, "remove_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Remove the avatar background. Video avatars must be trained with matting enabled.", "title": "Remove Background" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically \u2014 the caller does not need to set 'remove_background'." }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "type": { "const": "image", "description": "Must be 'image' for image-based video creation.", "title": "Type", "type": "string" }, "image": { "description": "Image to animate. Accepts URL, asset ID, or base64-encoded data.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Image" }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion. Photo avatars only.", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted." } }, "required": [ "type", "image" ], "title": "CreateVideoFromImage", "type": "object" }, "CreateVideoFromStudio": { "additionalProperties": false, "description": "Create a single video by composing an ordered list of whole-frame scenes.\n\nThe server owns layout and center-crops each scene to the global output\ncanvas. Output settings are global (one per request); a single video_id is\nreturned and rendering is all-or-nothing. MP4 only in v1 \u2014 the output\ncontainer is fixed and ``output_format`` is not exposed.", "properties": { "type": { "const": "studio", "description": "Must be 'studio' for scene-composition video creation.", "title": "Type", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.", "title": "Folder Id" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Global output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "scenes": { "description": "Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.", "items": { "discriminator": { "mapping": { "avatar_video": "#/components/schemas/AvatarVideoScene", "image": "#/components/schemas/ImageScene", "video": "#/components/schemas/VideoScene" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AvatarVideoScene" }, { "$ref": "#/components/schemas/ImageScene" }, { "$ref": "#/components/schemas/VideoScene" } ] }, "title": "Scenes", "type": "array" } }, "required": [ "type", "scenes" ], "title": "CreateVideoFromStudio", "type": "object" }, "ImageScene": { "additionalProperties": false, "description": "A whole-frame still-image scene: either silent (held for ``duration``) or narrated.\n\nExactly one mode must be chosen:\n- silent: set ``duration`` (seconds) and no audio source.\n- narrated: set exactly one audio source (script + voice_id, audio_url, or\n audio_asset_id) and omit ``duration`` \u2014 the scene length follows the audio.", "properties": { "type": { "const": "image", "description": "Must be 'image' for a still-image scene.", "title": "Type", "type": "string" }, "source": { "description": "Still image to display. Accepts URL, asset ID, or base64-encoded data.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Source" }, "duration": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 300.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be > 0 and <= 300.", "title": "Duration" }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided.", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." } }, "required": [ "type", "source" ], "title": "ImageScene", "type": "object" }, "PlaybackInput": { "additionalProperties": false, "description": "Playback and audio capability for a video-clip scene.\n\n``mode`` controls how a narrated clip is reconciled to the voiceover-driven\nscene duration. ``volume`` must be between 0.0 and 1.0.", "properties": { "mode": { "anyOf": [ { "enum": [ "freeze", "loop", "fit_to_scene" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "How a narrated clip aligns to the voiceover-driven scene duration. 'freeze' plays once and holds the last frame; 'loop' repeats the clip; 'fit_to_scene' adjusts playback speed to exactly match the scene. Defaults to 'freeze' when omitted. Requires a video-scene voiceover.", "title": "Mode" }, "volume": { "default": 1.0, "description": "Clip audio volume. 1.0 = source level (default), 0.0 = silent.", "maximum": 1.0, "minimum": 0.0, "title": "Volume", "type": "number" }, "mute": { "default": false, "description": "If True, force the clip silent regardless of 'volume'.", "title": "Mute", "type": "boolean" } }, "title": "PlaybackInput", "type": "object" }, "StudioAvatarInput": { "additionalProperties": false, "description": "Avatar-driven source for an ``avatar_video`` studio scene.\n\nMirrors the standalone ``avatar`` creation mode (``CreateVideoFromAvatar``)\nminus the output settings, which are global on the studio request. An audio\nsource is required: exactly one of (script + voice_id), audio_url, or\naudio_asset_id.", "properties": { "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "type": { "const": "avatar", "description": "Must be 'avatar' for an avatar-driven scene source.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen avatar ID (video avatar or photo avatar look ID).", "title": "Avatar Id", "type": "string" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'." }, "engine": { "anyOf": [ { "discriminator": { "mapping": { "avatar_iii": "#/components/schemas/AvatarIIIEngineConfig", "avatar_iv": "#/components/schemas/AvatarIVEngineConfig", "avatar_v": "#/components/schemas/AvatarVEngineConfig" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AvatarVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIIIEngineConfig" } ] }, { "type": "null" } ], "default": null, "description": "Engine configuration for video generation. Pass {\"type\": \"avatar_v\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.", "title": "Engine" }, "background": { "anyOf": [ { "discriminator": { "mapping": { "color": "#/components/schemas/StudioColorBackgroundInput" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/StudioColorBackgroundInput" } ] }, { "type": "null" } ], "default": null, "description": "Optional scene background composited behind the avatar. Color-only in v1: pass {\"type\": \"color\", \"color\": \"#RRGGBB\"}. Other background types are not yet supported.", "title": "Background" } }, "required": [ "type", "avatar_id" ], "title": "StudioAvatarInput", "type": "object" }, "StudioColorBackgroundInput": { "additionalProperties": false, "description": "Solid-color background for an ``avatar_video`` studio scene.\n\nStudio v1 supports solid-color backgrounds.", "properties": { "type": { "const": "color", "description": "Background type discriminator. Must be 'color'.", "title": "Type", "type": "string" }, "color": { "description": "Background color as a 6-digit hex string, e.g. '#1a2b3c'.", "pattern": "^#[0-9a-fA-F]{6}$", "title": "Color", "type": "string" } }, "required": [ "type", "color" ], "title": "StudioColorBackgroundInput", "type": "object" }, "VideoScene": { "additionalProperties": false, "description": "A whole-frame scene backed by an existing video clip.\n\nOptional ``playback`` exposes the audio volume / mute capability; when\nomitted the clip plays at its source volume.\n\nFor optional voiceover / narration, supply at most one audio source\n(``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) \u2014 the *same*\naudio inputs a narrated ``image`` scene accepts. When present, the narration\ndrives the scene length and ``playback.mode`` controls whether the clip\nfreezes, loops, or changes speed to fit that duration. When omitted the clip\nplays full-length as before. The clip's own audio level is still governed by\n``playback`` (the two compose).", "properties": { "type": { "const": "video", "description": "Must be 'video' for a video-clip scene.", "title": "Type", "type": "string" }, "source": { "description": "Video clip to include. Accepts URL, asset ID, or base64-encoded data.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Source" }, "playback": { "anyOf": [ { "$ref": "#/components/schemas/PlaybackInput" }, { "type": "null" } ], "default": null, "description": "Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0\u20131.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume." }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided.", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale) for a script voiceover." } }, "required": [ "type", "source" ], "title": "VideoScene", "type": "object" }, "WatermarkInput": { "additionalProperties": false, "description": "Watermark configuration for video creation.", "properties": { "image": { "description": "Image asset to use as the watermark overlay (PNG or JPEG).", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Image" }, "scale": { "default": 1.0, "description": "Scale multiplier for the watermark image. 1.0 renders at native size.", "exclusiveMinimum": 0.0, "maximum": 2.0, "title": "Scale", "type": "number" }, "opacity": { "default": 1.0, "description": "Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.", "maximum": 1.0, "minimum": 0.0, "title": "Opacity", "type": "number" }, "placement": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkPlacement" }, { "type": "null" } ], "default": null, "description": "Watermark placement. Defaults to bottom-right with standard margins when omitted." } }, "required": [ "image" ], "title": "WatermarkInput", "type": "object" }, "WatermarkPlacement": { "additionalProperties": false, "description": "Watermark placement configuration.", "properties": { "position": { "$ref": "#/components/schemas/WatermarkPosition", "default": "bottom_right", "description": "Anchor corner for the watermark." }, "offset_x": { "anyOf": [ { "maximum": 1.0, "minimum": -1.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.", "title": "Offset X" }, "offset_y": { "anyOf": [ { "maximum": 1.0, "minimum": -1.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.", "title": "Offset Y" } }, "title": "WatermarkPlacement", "type": "object" }, "WatermarkPosition": { "description": "Anchor corner for a custom watermark overlay.", "enum": [ "top_left", "top_right", "bottom_left", "bottom_right" ], "title": "WatermarkPosition", "type": "string" }, "VideoScenesResponse": { "additionalProperties": false, "description": "The composite document: one video's context and every one of its scenes.", "properties": { "video_id": { "description": "The video these scenes belong to.", "title": "Video Id", "type": "string" }, "edit_version": { "description": "Opaque version of the editor document returned by this request. Pass it unchanged when requesting an edit so the server can reject a document that changed before submission. This submission-time check does not lock the document while the asynchronous agent applies the edit.", "title": "Edit Version", "type": "string" }, "video": { "$ref": "#/components/schemas/VideoContext", "description": "Video-level context for the scenes." }, "scenes": { "description": "Every scene in the video, in the video's own order, which is playback order unless the video branches. Never paginated.", "items": { "$ref": "#/components/schemas/Scene" }, "title": "Scenes", "type": "array" } }, "required": [ "video_id", "edit_version", "video" ], "title": "VideoScenesResponse", "type": "object" }, "AudioScriptEntry": { "additionalProperties": false, "description": "Uploaded audio played as the scene's speech.", "properties": { "id": { "description": "Identifier of this script entry within the video.", "title": "Id", "type": "string" }, "type": { "const": "audio", "default": "audio", "description": "Script entry type discriminator.", "title": "Type", "type": "string" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of the audio. Present when the video records a link for this entry 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.", "title": "Audio Url" } }, "required": [ "id" ], "title": "AudioScriptEntry", "type": "object" }, "AvatarElement": { "additionalProperties": false, "description": "An avatar performing the scene's speech.\n\nCarries what a v3 create request can set per avatar, so what is read back here is what can be\nsent back. Fields are added as callers need them, and a new one is not a breaking change.\n\nOutput resolution is a whole-video setting, reported on the video rather than per avatar.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "const": "avatar", "default": "avatar", "description": "Element type discriminator.", "title": "Type", "type": "string" }, "avatar_id": { "description": "The avatar look performing this scene.", "title": "Avatar Id", "type": "string" }, "engine": { "anyOf": [ { "$ref": "#/components/schemas/AvatarEngineTier" }, { "type": "null" } ], "default": null, "description": "Generation engine for this avatar. Absent when the video does not record one and none can be determined." }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Expressiveness level. Absent when left at the default." }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Motion description authored for this avatar.", "title": "Motion Prompt" } }, "required": [ "id", "avatar_id" ], "title": "AvatarElement", "type": "object" }, "AvatarEngineTier": { "description": "Coarse UI-facing tier. This is what the user sees in the engine dropdown.", "enum": [ "avatar_v", "avatar_iv", "avatar_iii" ], "title": "AvatarEngineTier", "type": "string" }, "ColorBackground": { "additionalProperties": false, "description": "A solid colour filling the frame behind the scene's elements.", "properties": { "type": { "const": "color", "default": "color", "description": "Background type discriminator.", "title": "Type", "type": "string" }, "color": { "description": "Hex colour, e.g. '#f6f6fc'.", "title": "Color", "type": "string" } }, "required": [ "color" ], "title": "ColorBackground", "type": "object" }, "ContainerElement": { "additionalProperties": false, "description": "An element that holds other elements: a group, or a mask.\n\nA scene lists the container, not its contents, so a scene holding one group of five images\nlists a single element while five things render. Walking a scene's composition means recursing\ninto ``children``.\n\nA mask matters more here than a group: a group conveys linkage this response does not express,\nwhile a mask conveys clipping, so treating a masked image as a plain image asserts a\ncomposition that renders differently in kind.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "description": "The container's category, e.g. 'group' or 'mask'.", "title": "Type", "type": "string" }, "children": { "description": "The elements this container holds, each described exactly as a top-level element would be.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AvatarElement" }, { "$ref": "#/components/schemas/ImageElement" }, { "$ref": "#/components/schemas/VideoElement" }, { "$ref": "#/components/schemas/PlaceholderElement" }, { "$ref": "#/components/schemas/ContainerElement" } ] }, "title": "Children", "type": "array" } }, "required": [ "id", "type" ], "title": "ContainerElement", "type": "object" }, "ImageBackground": { "additionalProperties": false, "description": "A whole-frame image.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "const": "image", "default": "image", "description": "Background type discriminator.", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "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.", "title": "Url" } }, "required": [ "id" ], "title": "ImageBackground", "type": "object" }, "ImageElement": { "additionalProperties": false, "description": "An image placed in the scene.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "const": "image", "default": "image", "description": "Element type discriminator.", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of the image. Present when the video records a link for this element 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; the element is still reported either way, so an image with no URL is one this read could not link to rather than an element this API does not describe. 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.", "title": "Url" } }, "required": [ "id" ], "title": "ImageElement", "type": "object" }, "PlaceholderElement": { "additionalProperties": false, "description": "An element this version names but does not describe.\n\nExists so a scene's ``elements`` array is never a filtered view presented as a complete one: a\ncaller iterating it sees every element the scene places. Carries exactly two fields: which\nelement this is, and what kind of thing it is.\n\n**Absence of content is not by itself proof that an element is undescribed.** A described\ncategory can serialize with nothing but an id and a type when every optional field happens to be\nunavailable, and one case is reachable today: an image with no usable link carries no ``url``,\nleaving ``{id, type}``. Read the ``type`` to tell them apart.\n``avatar``, ``image`` and ``video`` are described, so a bare one of those is a described element\nmissing an optional value rather than an unexpanded node.\n\nThe ``id`` matters most here. Two masked elements in one scene are otherwise identical on the\nwire, so without it a caller can see that the scene places two things and nothing else about\neither.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "description": "The element's category. An **open set**: new values may be added, so treat an unrecognized one as an element to skip rather than an error. Several kinds of element can share one value, so a category says what an element is rather than naming a single underlying kind. Every value is permanent except 'other', which means 'a kind of element this API does not yet categorise' and may be replaced by a more specific category later.", "title": "Type", "type": "string" } }, "required": [ "id", "type" ], "title": "PlaceholderElement", "type": "object" }, "Scene": { "additionalProperties": false, "description": "One scene, in the video's own order.\n\nThat is playback order for a linear video, which is the ordinary case. A branching video plays as\na walk over branch targets instead, so its scenes are still all here and still ordered, but the\norder is not the sequence a viewer sees. Branching is not otherwise described by this version.\n\nThe three content fields split by the role a thing plays rather than by its kind:\n``background`` fills the frame, ``elements`` are placed within it, ``script`` carries\nthe speech delivered over it. The background is visual too, so ``elements`` means \"the\nones the scene places\", not \"the visual ones\".", "properties": { "id": { "description": "Identifier of this scene within the video.", "title": "Id", "type": "string" }, "background": { "anyOf": [ { "discriminator": { "mapping": { "color": "#/components/schemas/ColorBackground", "image": "#/components/schemas/ImageBackground", "video": "#/components/schemas/VideoBackground" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ColorBackground" }, { "$ref": "#/components/schemas/ImageBackground" }, { "$ref": "#/components/schemas/VideoBackground" } ] }, { "type": "null" } ], "default": null, "description": "What fills the frame behind this scene's elements.", "title": "Background" }, "elements": { "description": "Every element this scene places, in the video's own order.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AvatarElement" }, { "$ref": "#/components/schemas/ImageElement" }, { "$ref": "#/components/schemas/VideoElement" }, { "$ref": "#/components/schemas/PlaceholderElement" }, { "$ref": "#/components/schemas/ContainerElement" } ] }, "title": "Elements", "type": "array" }, "script": { "description": "This scene's audio sources in order, each one synthesized speech, uploaded audio, or a silence. The create API's per-scene `script` is narrower: it is the text of a single one of these entries.", "items": { "anyOf": [ { "$ref": "#/components/schemas/TextScriptEntry" }, { "$ref": "#/components/schemas/AudioScriptEntry" }, { "$ref": "#/components/schemas/SilenceScriptEntry" } ] }, "title": "Script", "type": "array" } }, "required": [ "id" ], "title": "Scene", "type": "object" }, "ScriptVoiceSettings": { "additionalProperties": false, "description": "The voice tuning applied to this script.\n\nA value here can fall outside the range the create API accepts, so validating it against a\ncreate request's schema will reject videos it should accept.", "properties": { "speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Playback speed multiplier.", "title": "Speed" }, "pitch": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Pitch adjustment in semitones.", "title": "Pitch" }, "volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Voice audio volume. 1.0 = full, 0.0 = silent.", "title": "Volume" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Locale/accent hint for multi-lingual voices (e.g. 'en-US').", "title": "Locale" }, "engine_settings": { "anyOf": [ { "discriminator": { "mapping": { "elevenlabs": "#/components/schemas/ElevenLabsEngineSettings", "fish": "#/components/schemas/FishEngineSettings", "starfish": "#/components/schemas/StarfishEngineSettings" }, "propertyName": "engine_type" }, "oneOf": [ { "$ref": "#/components/schemas/ElevenLabsEngineSettings" }, { "$ref": "#/components/schemas/FishEngineSettings" }, { "$ref": "#/components/schemas/StarfishEngineSettings" } ] }, { "type": "null" } ], "default": null, "description": "Engine-specific voice tuning, discriminated by 'engine_type'. Present only when the video pins an engine this API exposes; absent when the engine is left for the server to pick.", "title": "Engine Settings" } }, "title": "ScriptVoiceSettings", "type": "object" }, "SilenceScriptEntry": { "additionalProperties": false, "description": "A held silence, with no words spoken over the scene.", "properties": { "id": { "description": "Identifier of this script entry within the video.", "title": "Id", "type": "string" }, "type": { "const": "silence", "default": "silence", "description": "Script entry type discriminator.", "title": "Type", "type": "string" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "How long the silence is held, in seconds. Absent where the number does not describe what renders \u2014 on a scene whose video clip plays in full, the clip's own length governs the scene.", "title": "Duration" } }, "required": [ "id" ], "title": "SilenceScriptEntry", "type": "object" }, "TextScriptEntry": { "additionalProperties": false, "description": "Synthesized speech: a script delivered by a voice.", "properties": { "id": { "description": "Opaque identifier of this script entry within the video. Not to be parsed, sorted, or assumed to encode anything. The same id under two scenes means one entry is shared between them: its text belongs to both, and concatenating both scenes' scripts would synthesize the shared words twice.", "title": "Id", "type": "string" }, "type": { "const": "text", "default": "text", "description": "Script entry type discriminator.", "title": "Type", "type": "string" }, "text": { "description": "The script, verbatim, including inline markup. Empty when the scene was left unfinished.", "title": "Text", "type": "string" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The voice delivering this script.", "title": "Voice Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/ScriptVoiceSettings" }, { "type": "null" } ], "default": null, "description": "Voice tuning applied to this script." }, "trim_to_speech": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether leading and trailing silence is trimmed to the spoken window.", "title": "Trim To Speech" } }, "required": [ "id", "text" ], "title": "TextScriptEntry", "type": "object" }, "VideoBackground": { "additionalProperties": false, "description": "A whole-frame video clip.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "const": "video", "default": "video", "description": "Background type discriminator.", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "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.", "title": "Url" }, "playback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "How the clip is reconciled to the scene. Same values as a video element's playback.", "title": "Playback" }, "trim": { "anyOf": [ { "$ref": "#/components/schemas/VideoTrim" }, { "type": "null" } ], "default": null, "description": "Seconds trimmed from each end of the clip." }, "volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Clip audio volume. 1.0 = source level, 0.0 = silent.", "title": "Volume" }, "speed_multiplier": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Playback speed multiplier. 2.0 = twice as fast.", "title": "Speed Multiplier" } }, "required": [ "id" ], "title": "VideoBackground", "type": "object" }, "VideoCaption": { "additionalProperties": false, "description": "Whether the video involves captions.", "properties": { "enabled": { "description": "Whether captions are enabled for this video.", "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "VideoCaption", "type": "object" }, "VideoContext": { "additionalProperties": false, "description": "Video-level facts needed to make sense of the scenes.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The video's current title. Editor saves update it.", "title": "Title" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": null, "description": "The video's aspect ratio." }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "The video's output resolution, in the same values a create request accepts. Absent when the video's size matches none of them, which is a size a create request could not have asked for and cannot reproduce." }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/VideoCaption" }, { "type": "null" } ], "default": null, "description": "Caption configuration for the video." }, "brand_glossary_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary applied to this video's speech.", "title": "Brand Glossary Id" } }, "title": "VideoContext", "type": "object" }, "VideoElement": { "additionalProperties": false, "description": "A video clip placed in the scene.", "properties": { "id": { "description": "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.", "title": "Id", "type": "string" }, "type": { "const": "video", "default": "video", "description": "Element type discriminator.", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of the clip. Present when the video records a link for this element 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.", "title": "Url" }, "playback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "How the clip is reconciled to the scene: 'freeze' holds the last frame, 'loop' repeats it, 'fit_to_scene' changes speed to match, 'full_video' plays it whole and drives the scene's length.", "title": "Playback" }, "trim": { "anyOf": [ { "$ref": "#/components/schemas/VideoTrim" }, { "type": "null" } ], "default": null, "description": "Seconds trimmed from each end of the clip." }, "volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Clip audio volume. 1.0 = source level, 0.0 = silent.", "title": "Volume" }, "speed_multiplier": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Playback speed multiplier. 2.0 = twice as fast.", "title": "Speed Multiplier" } }, "required": [ "id" ], "title": "VideoElement", "type": "object" }, "VideoTrim": { "additionalProperties": false, "description": "Seconds trimmed from each end of a clip.", "properties": { "start_offset": { "description": "Seconds trimmed from the start of the clip.", "title": "Start Offset", "type": "number" }, "end_offset": { "description": "Seconds trimmed from the end of the clip.", "title": "End Offset", "type": "number" } }, "required": [ "start_offset", "end_offset" ], "title": "VideoTrim", "type": "object" }, "TemplateListItemV3": { "description": "Template summary returned by the list endpoint.", "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" } }, "required": [ "id", "name" ], "title": "TemplateListItemV3", "type": "object" }, "TemplateDetailV3": { "description": "Template detail including its variable schema and scenes.", "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": "#/components/schemas/TemplateAudioVariable", "character": "#/components/schemas/TemplateCharacterVariable", "image": "#/components/schemas/TemplateImageVariable", "text": "#/components/schemas/TemplateTextVariable", "video": "#/components/schemas/TemplateVideoVariable", "voice": "#/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" }, "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" } }, "required": [ "id", "name" ], "title": "TemplateDetailV3", "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": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/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" }, "character_id": { "description": "Avatar ID or talking photo ID to place", "minLength": 1, "title": "Character Id", "type": "string" }, "character_type": { "default": "avatar", "description": "Kind of character the character_id refers to", "enum": [ "avatar", "talking_photo" ], "title": "Character Type", "type": "string" } }, "required": [ "type", "character_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": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/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" }, "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" }, "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" }, "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": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/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.0, "description": "Audio volume of the video track, 0.0 (muted) to 1.0", "maximum": 1.0, "minimum": 0.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" }, "GenerateFromTemplateV3Request": { "description": "Request body for POST /v3/templates/{template_id}.", "properties": { "variables": { "additionalProperties": { "discriminator": { "mapping": { "audio": "#/components/schemas/TemplateAudioVariable", "character": "#/components/schemas/TemplateCharacterVariable", "image": "#/components/schemas/TemplateImageVariable", "text": "#/components/schemas/TemplateTextVariable", "video": "#/components/schemas/TemplateVideoVariable", "voice": "#/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": "Template variable replacements, keyed by the variable name defined in the template. Supply every text variable you want filled: an omitted text variable is not substituted, so its literal `{{variable_name}}` placeholder remains in the text it is bound to, whether that is a spoken script or an on-screen text element. Omitting an image, video, audio, character or voice variable is safe and keeps the value the template already holds. The defaults returned by `GET /v3/templates/{template_id}` are the template's current values, not fallbacks applied at generation time.", "title": "Variables", "type": "object" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title for the generated video", "title": "Title" }, "caption": { "default": false, "description": "Whether to burn captions into the video", "title": "Caption", "type": "boolean" }, "subtitles": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSubtitleSettings" }, { "type": "null" } ], "default": null, "description": "Subtitle style settings. Implies captions when provided." }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque ID echoed back in webhook events for this video", "title": "Callback Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL called with the video result in addition to registered webhook endpoints", "title": "Callback Url" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Folder to place the generated video in", "title": "Folder Id" }, "brand_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Legacy field name for `brand_glossary_id`. Both are accepted and resolve to the same workspace record. Prefer `brand_glossary_id`.", "title": "Brand Voice Id" }, "brand_glossary_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "dimension": { "anyOf": [ { "$ref": "#/components/schemas/TemplateVideoDimension" }, { "type": "null" } ], "default": null, "description": "Output resolution override. Must match the template's aspect ratio." }, "fps": { "default": 25.0, "description": "Output frame rate. One of 25, 30, or 60.", "title": "Fps", "type": "number" }, "scene_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order.", "title": "Scene Ids" }, "reorder_music": { "default": true, "description": "When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.", "title": "Reorder Music", "type": "boolean" }, "keep_text_vertically_centered": { "default": false, "description": "When true, replaced text elements are vertically re-centered based on their rendered height", "title": "Keep Text Vertically Centered", "type": "boolean" }, "include_gif": { "default": false, "description": "Whether to include a GIF preview in the webhook payload", "title": "Include Gif", "type": "boolean" }, "enable_sharing": { "default": false, "description": "Whether the generated video's share page is publicly accessible", "title": "Enable Sharing", "type": "boolean" } }, "required": [ "variables" ], "title": "GenerateFromTemplateV3Request", "type": "object" }, "TemplateSubtitlePosition": { "additionalProperties": false, "description": "Subtitle position override.", "properties": { "x": { "default": 0.0, "description": "Horizontal subtitle position", "title": "X", "type": "number" }, "y": { "default": 0.0, "description": "Vertical subtitle position", "title": "Y", "type": "number" } }, "title": "TemplateSubtitlePosition", "type": "object" }, "TemplateSubtitleSettings": { "additionalProperties": false, "description": "Output subtitle style settings (mirrors the /v3/videos subtitles input).", "properties": { "preset_name": { "description": "Subtitle preset name, e.g. 'classic', 'bold', 'bright'", "title": "Preset Name", "type": "string" }, "alignment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 2, "description": "Subtitle alignment", "title": "Alignment" }, "disable_highlight": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Override the preset's word-highlight style", "title": "Disable Highlight" }, "font_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Font size override for the preset", "title": "Font Size" }, "position": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSubtitlePosition" }, { "type": "null" } ], "default": null, "description": "Subtitle position override" } }, "required": [ "preset_name" ], "title": "TemplateSubtitleSettings", "type": "object" }, "TemplateVideoDimension": { "additionalProperties": false, "description": "Output resolution override. Must keep the template's aspect ratio.", "properties": { "width": { "description": "Output video width in pixels (even number, 128-4096)", "maximum": 4096, "minimum": 128, "title": "Width", "type": "integer" }, "height": { "description": "Output video height in pixels (even number, 128-4096)", "maximum": 4096, "minimum": 128, "title": "Height", "type": "integer" } }, "required": [ "width", "height" ], "title": "TemplateVideoDimension", "type": "object" }, "CreateBackgroundRemovalRequest": { "additionalProperties": false, "properties": { "video": { "description": "Input video to remove the background from (url, asset_id, or base64).", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Video" }, "layers": { "description": "Output layers to return. Any of: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), 'background' (the scene with the subject removed). Defaults to all three.", "items": { "type": "string" }, "title": "Layers", "type": "array" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional human-readable title for the job.", "title": "Title" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Client-provided idempotency key \u2014 *the* idempotency mechanism for this endpoint. Re-sending the same `request_id` returns the *original* job (same `id`, same `status`, same charge) instead of creating a new one \u2014 the dedup is over (`space_id`, `request_id`), not over the response body, so a duplicate `request_id` with different content still collides on the original job. The HTTP `Idempotency-Key` header is *not* honored here; pick a per-content `request_id` if you need per-content dedup.", "title": "Request Id" } }, "required": [ "video" ], "title": "CreateBackgroundRemovalRequest", "type": "object" }, "BackgroundRemovalJob": { "properties": { "id": { "description": "Background removal job id. Use it to poll GET /v3/background-removals/{id}.", "title": "Id", "type": "string" }, "status": { "description": "Job status: 'pending' | 'processing' | 'completed' | 'failed' | 'deleted'.", "title": "Status", "type": "string" }, "layers": { "additionalProperties": { "type": "string" }, "description": "Map of produced layer name to a presigned download URL. Populated once status is 'completed'.", "title": "Layers", "type": "object" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Processed video duration in seconds.", "title": "Duration" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp (seconds) when the job was created.", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp (seconds) when the job completed. Present once completed.", "title": "Completed At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Failure reason. Present only when status is 'failed'.", "title": "Error" } }, "required": [ "id", "status" ], "title": "BackgroundRemovalJob", "type": "object" }, "BackgroundRemovalDeleteResponse": { "properties": { "id": { "description": "The deleted background removal job id.", "title": "Id", "type": "string" }, "deleted": { "description": "Always true on success.", "title": "Deleted", "type": "boolean" } }, "required": [ "id", "deleted" ], "title": "BackgroundRemovalDeleteResponse", "type": "object" }, "MCPVideoTranslateCreateRequest": { "additionalProperties": false, "description": "Request body for creating a video translation job via the MCP server.", "properties": { "video_url": { "description": "URL of the source video to translate", "title": "Video Url", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title for the translation job", "title": "Title" }, "output_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Single target language code. Mutually exclusive with output_languages.", "title": "Output Language" }, "output_languages": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Multiple target language codes for batch translation. Mutually exclusive with output_language.", "title": "Output Languages" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Custom audio URL for audio dubbing", "title": "Audio Url" }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source language code (auto-detected if omitted)", "title": "Input Language" }, "translate_audio_only": { "default": false, "description": "Only translate audio, keep original video", "title": "Translate Audio Only", "type": "boolean", "x-mcp-visible": false }, "speaker_num": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of speakers (improves speaker separation)", "title": "Speaker Num" }, "mode": { "default": "speed", "description": "Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)", "enum": [ "speed", "precision" ], "title": "Mode", "type": "string" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion notifications", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID included in webhook payload", "title": "Callback Id" }, "enable_caption": { "default": false, "deprecated": true, "description": "Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.", "title": "Enable Caption", "type": "boolean" }, "keep_the_same_format": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Preserve the source video's encoding specs (resolution, bitrate). Defaults to True for enterprise/team/pro API users with audio_url.", "title": "Keep The Same Format" }, "enable_dynamic_duration": { "default": true, "description": "Allow dynamic duration adjustment", "title": "Enable Dynamic Duration", "type": "boolean" }, "disable_music_track": { "default": false, "description": "Remove background music", "title": "Disable Music Track", "type": "boolean" }, "enable_speech_enhancement": { "default": false, "description": "Enhance speech quality", "title": "Enable Speech Enhancement", "type": "boolean" }, "enable_watermark": { "default": false, "description": "Add watermark to output", "title": "Enable Watermark", "type": "boolean" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Start time in seconds for partial translation", "title": "Start Time" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "End time in seconds for partial translation", "title": "End Time" }, "brand_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID for custom term translations. The legacy field name for `brand_glossary_id` \u2014 both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Voice Id" }, "brand_glossary_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "stock_voice_config": { "anyOf": [ { "$ref": "#/components/schemas/StockVoiceConfig" }, { "type": "null" } ], "default": null, "description": "Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request \u2014 contact your HeyGen account team." }, "srt_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Custom subtitle file URL.", "title": "Srt Url" }, "srt_role": { "anyOf": [ { "enum": [ "input", "output" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Which video the SRT applies to. Used with srt_url.", "title": "Srt Role" }, "fps_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Frame rate mode: 'vfr', 'cfr', or 'passthrough'. Only valid with audio_url.", "title": "Fps Mode" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project/folder ID to organize translation into", "title": "Folder Id" } }, "required": [ "video_url" ], "title": "MCPVideoTranslateCreateRequest", "type": "object" }, "StockVoiceConfig": { "additionalProperties": false, "description": "Stock-voice options for a video translation request.\n\nUse a preset HeyGen voice for the translation instead of recreating the original\nspeaker's voice. Enterprise feature, available for selected accounts and languages\nby request. See the ``stock_voice_config`` request field for usage.", "properties": { "use_stock_voice": { "default": false, "description": "Set to true to use a preset stock voice instead of cloning the original speaker.", "title": "Use Stock Voice", "type": "boolean" }, "preferred_stock_voice_ids": { "description": "Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used.", "items": { "type": "string" }, "title": "Preferred Stock Voice Ids", "type": "array" } }, "title": "StockVoiceConfig", "type": "object" }, "VideoTranslateCreateResponse": { "properties": { "video_translate_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "examples": [ "vt_abc123" ], "title": "Video Translate Id" }, "video_translate_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "examples": [ [ "vt_abc123", "vt_def456" ] ], "title": "Video Translate Ids" } }, "title": "VideoTranslateCreateResponse", "type": "object" }, "ListTargetLanguageResponse": { "properties": { "languages": { "examples": [ [ "en", "es", "fr", "de", "ja", "zh" ] ], "items": { "type": "string" }, "title": "Languages", "type": "array" } }, "required": [ "languages" ], "title": "ListTargetLanguageResponse", "type": "object" }, "VideoTranslateCaptionGetResponse": { "properties": { "caption_url": { "examples": [ "https://files.heygen.ai/captions/abc123.srt" ], "title": "Caption Url", "type": "string" } }, "required": [ "caption_url" ], "title": "VideoTranslateCaptionGetResponse", "type": "object" }, "CreateVideoTranslationRequest": { "additionalProperties": false, "description": "Request body for POST /v3/video-translations.", "properties": { "video": { "description": "Source video \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Video" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title for the translation job", "title": "Title" }, "output_languages": { "description": "Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.", "items": { "type": "string" }, "minItems": 1, "title": "Output Languages", "type": "array" }, "audio": { "anyOf": [ { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ] }, { "type": "null" } ], "default": null, "description": "Custom audio for dubbing \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "title": "Audio" }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source language code (auto-detected if omitted)", "title": "Input Language" }, "translate_audio_only": { "default": false, "description": "Only translate audio, keep original video", "title": "Translate Audio Only", "type": "boolean" }, "speaker_num": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of speakers (improves speaker separation)", "title": "Speaker Num" }, "mode": { "$ref": "#/components/schemas/VideoTranslationMode", "default": "speed", "description": "Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion notifications", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID included in webhook payload", "title": "Callback Id" }, "enable_caption": { "default": false, "deprecated": true, "description": "Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.", "title": "Enable Caption", "type": "boolean" }, "keep_the_same_format": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Preserve the source video's encoding specs (resolution, bitrate).", "title": "Keep The Same Format" }, "enable_dynamic_duration": { "default": true, "description": "Allow dynamic duration adjustment", "title": "Enable Dynamic Duration", "type": "boolean" }, "disable_music_track": { "default": false, "description": "Remove background music", "title": "Disable Music Track", "type": "boolean" }, "enable_speech_enhancement": { "default": false, "description": "Enhance speech quality", "title": "Enable Speech Enhancement", "type": "boolean" }, "enable_watermark": { "default": false, "description": "Add watermark to output", "title": "Enable Watermark", "type": "boolean" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Start time in seconds for partial translation", "title": "Start Time" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "End time in seconds for partial translation", "title": "End Time" }, "brand_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` \u2014 both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Voice Id" }, "brand_glossary_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "stock_voice_config": { "anyOf": [ { "$ref": "#/components/schemas/StockVoiceConfig" }, { "type": "null" } ], "default": null, "description": "Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request \u2014 contact your HeyGen account team." }, "srt": { "anyOf": [ { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ] }, { "type": "null" } ], "default": null, "description": "Custom subtitle file \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.", "title": "Srt" }, "srt_role": { "anyOf": [ { "enum": [ "input", "output" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Which video the subtitle applies to: 'input' (source) or 'output' (translated).", "title": "Srt Role" }, "fps_mode": { "anyOf": [ { "enum": [ "vfr", "cfr", "passthrough" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.", "title": "Fps Mode" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project/folder ID to organize translation into", "title": "Folder Id" } }, "required": [ "video", "output_languages" ], "title": "CreateVideoTranslationRequest", "type": "object" }, "VideoTranslationMode": { "enum": [ "speed", "precision" ], "title": "VideoTranslationMode", "type": "string" }, "VideoTranslationCreateResponse": { "description": "Response for POST /v3/video-translations.", "properties": { "video_translation_ids": { "description": "Video translation IDs, one per target language", "items": { "type": "string" }, "title": "Video Translation Ids", "type": "array" } }, "required": [ "video_translation_ids" ], "title": "VideoTranslationCreateResponse", "type": "object" }, "VideoTranslationDetail": { "description": "Detailed video translation resource.", "properties": { "id": { "description": "Unique video translation identifier", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title of the translation job", "title": "Title" }, "status": { "$ref": "#/components/schemas/VideoTranslationStatus", "description": "Current status of the translation" }, "output_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target language code", "title": "Output Language" }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Detected or specified source language code", "title": "Input Language" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds", "title": "Duration" }, "translate_audio_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether only the audio was translated, keeping the original video", "title": "Translate Audio Only" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the translated video. Only present when status is completed.", "title": "Video Url" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the translated audio. Only present when status is completed.", "title": "Audio Url" }, "srt_caption_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the SRT caption file. Present when status is completed.", "title": "Srt Caption Url" }, "vtt_caption_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the VTT caption file. Present when status is completed.", "title": "Vtt Caption Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Client-provided callback ID", "title": "Callback Id" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the translation was created", "title": "Created At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status is failed.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "VideoTranslationDetail", "type": "object" }, "VideoTranslationStatus": { "enum": [ "pending", "running", "completed", "failed" ], "title": "VideoTranslationStatus", "type": "string" }, "UpdateVideoTranslationRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/video-translations/{id}.", "properties": { "title": { "description": "New title for the video translation", "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "UpdateVideoTranslationRequest", "type": "object" }, "VideoTranslationDeleteResponse": { "description": "Response for DELETE /v3/video-translations/{id}.", "properties": { "id": { "description": "ID of the deleted video translation", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "VideoTranslationDeleteResponse", "type": "object" }, "VideoTranslationLanguagesResponse": { "description": "Response for GET /v3/video-translations/languages.", "properties": { "languages": { "description": "List of supported target language codes", "items": { "type": "string" }, "title": "Languages", "type": "array" } }, "required": [ "languages" ], "title": "VideoTranslationLanguagesResponse", "type": "object" }, "CreateProofreadRequest": { "additionalProperties": false, "description": "Request body for POST /v3/video-translations/proofreads.", "properties": { "video": { "description": "Source video \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Video" }, "output_languages": { "description": "Target language codes. Use one for single proofread, multiple for batch.", "items": { "type": "string" }, "minItems": 1, "title": "Output Languages", "type": "array" }, "title": { "description": "Title for the proofread job", "title": "Title", "type": "string" }, "brand_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` \u2014 both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Voice Id" }, "brand_glossary_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "speaker_num": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of speakers (improves speaker separation)", "title": "Speaker Num" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project/folder ID to organize proofread into", "title": "Folder Id" }, "enable_video_stretching": { "default": false, "description": "Allow dynamic duration adjustment", "title": "Enable Video Stretching", "type": "boolean" }, "disable_music_track": { "default": false, "description": "Remove background music", "title": "Disable Music Track", "type": "boolean" }, "enable_speech_enhancement": { "default": false, "description": "Enhance speech quality", "title": "Enable Speech Enhancement", "type": "boolean" }, "srt": { "anyOf": [ { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ] }, { "type": "null" } ], "default": null, "description": "Initial SRT file \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "title": "Srt" }, "mode": { "$ref": "#/components/schemas/VideoTranslationMode", "default": "speed", "description": "Translation quality mode: 'speed' (faster) or 'precision' (higher quality)" }, "keep_the_same_format": { "default": false, "description": "Preserve the source video's encoding specs (resolution, bitrate)", "title": "Keep The Same Format", "type": "boolean" } }, "required": [ "video", "output_languages", "title" ], "title": "CreateProofreadRequest", "type": "object" }, "CreateProofreadResponse": { "description": "Response for POST /v3/video-translations/proofreads.", "properties": { "proofread_ids": { "description": "Proofread IDs, one per target language", "items": { "type": "string" }, "title": "Proofread Ids", "type": "array" }, "status": { "$ref": "#/components/schemas/ProofreadStatus", "description": "Initial status (always processing)" } }, "required": [ "proofread_ids", "status" ], "title": "CreateProofreadResponse", "type": "object" }, "ProofreadStatus": { "enum": [ "processing", "completed", "failed" ], "title": "ProofreadStatus", "type": "string" }, "ProofreadDetail": { "description": "Detailed proofread resource.", "properties": { "id": { "description": "Unique proofread identifier", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title of the proofread job", "title": "Title" }, "status": { "$ref": "#/components/schemas/ProofreadStatus", "description": "Current status" }, "output_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target language code", "title": "Output Language" }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Detected or specified source language code", "title": "Input Language" }, "submitted_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the proofread has been submitted for review", "title": "Submitted For Review" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the proofread was created", "title": "Created At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status is failed.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "ProofreadDetail", "type": "object" }, "ProofreadDeleteResponse": { "description": "Response for DELETE /v3/video-translations/proofreads/{id}.", "properties": { "id": { "description": "ID of the deleted proofread session", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "ProofreadDeleteResponse", "type": "object" }, "DownloadSRTResponse": { "description": "Response for GET /v3/video-translations/proofreads/{id}/srt.", "properties": { "srt_url": { "description": "Presigned URL to download the edited SRT file", "title": "Srt Url", "type": "string" }, "original_srt_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned URL for the original SRT file (if provided at creation)", "title": "Original Srt Url" } }, "required": [ "srt_url" ], "title": "DownloadSRTResponse", "type": "object" }, "UploadSRTRequest": { "additionalProperties": false, "description": "Request body for PUT /v3/video-translations/proofreads/{id}/srt.", "properties": { "srt": { "description": "SRT file \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Srt" } }, "required": [ "srt" ], "title": "UploadSRTRequest", "type": "object" }, "GenerateVideoRequest": { "additionalProperties": false, "description": "Request body for POST /v3/video-translations/proofreads/{id}/generate.", "properties": { "captions": { "default": false, "deprecated": true, "description": "Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.", "title": "Captions", "type": "boolean" }, "translate_audio_only": { "default": false, "description": "Only translate audio, keep original video", "title": "Translate Audio Only", "type": "boolean" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID included in webhook payload", "title": "Callback Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion notifications", "title": "Callback Url" } }, "title": "GenerateVideoRequest", "type": "object" }, "GenerateVideoResponse": { "description": "Response for POST /v3/video-translations/proofreads/{id}/generate.", "properties": { "video_translation_id": { "description": "Video translation ID \u2014 use GET /v3/video-translations/{id} to poll status", "title": "Video Translation Id", "type": "string" }, "status": { "$ref": "#/components/schemas/ProofreadStatus", "description": "Initial status (always processing)" } }, "required": [ "video_translation_id", "status" ], "title": "GenerateVideoResponse", "type": "object" }, "CreateLipsyncRequest": { "additionalProperties": false, "description": "Request body for POST /v3/lipsyncs.", "properties": { "video": { "description": "Source video \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Video" }, "audio": { "description": "Replacement audio \u2014 provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Audio" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title for the lipsync job", "title": "Title" }, "mode": { "$ref": "#/components/schemas/VideoTranslationMode", "default": "speed", "description": "Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL for completion notifications", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID included in webhook payload", "title": "Callback Id" }, "enable_caption": { "default": false, "deprecated": true, "description": "Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.", "title": "Enable Caption", "type": "boolean" }, "keep_the_same_format": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Preserve the source video's encoding specs (resolution, bitrate).", "title": "Keep The Same Format" }, "enable_dynamic_duration": { "default": true, "description": "Allow dynamic duration adjustment", "title": "Enable Dynamic Duration", "type": "boolean" }, "disable_music_track": { "default": false, "description": "Remove background music", "title": "Disable Music Track", "type": "boolean" }, "enable_speech_enhancement": { "default": false, "description": "Enhance speech quality", "title": "Enable Speech Enhancement", "type": "boolean" }, "enable_watermark": { "default": false, "description": "Add watermark to output", "title": "Enable Watermark", "type": "boolean" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Start time in seconds for partial lipsync", "title": "Start Time" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "End time in seconds for partial lipsync", "title": "End Time" }, "fps_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Frame rate mode: 'vfr', 'cfr', or 'passthrough'.", "title": "Fps Mode" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project/folder ID to organize lipsync into", "title": "Folder Id" } }, "required": [ "video", "audio" ], "title": "CreateLipsyncRequest", "type": "object" }, "LipsyncCreateResponse": { "description": "Response for POST /v3/lipsyncs.", "properties": { "lipsync_id": { "description": "Lipsync ID \u2014 use GET /v3/lipsyncs/{id} to poll status", "title": "Lipsync Id", "type": "string" } }, "required": [ "lipsync_id" ], "title": "LipsyncCreateResponse", "type": "object" }, "LipsyncDetail": { "description": "Detailed lipsync resource.", "properties": { "id": { "description": "Unique lipsync identifier", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title of the lipsync job", "title": "Title" }, "status": { "$ref": "#/components/schemas/VideoTranslationStatus", "description": "Current status" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds", "title": "Duration" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the output video. Only present when status is completed.", "title": "Video Url" }, "caption_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the SRT caption file. Only present when completed.", "title": "Caption Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Client-provided callback ID", "title": "Callback Id" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the lipsync was created", "title": "Created At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status is failed.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "LipsyncDetail", "type": "object" }, "UpdateLipsyncRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/lipsyncs/{id}.", "properties": { "title": { "description": "New title for the lipsync", "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "UpdateLipsyncRequest", "type": "object" }, "LipsyncDeleteResponse": { "description": "Response for DELETE /v3/lipsyncs/{id}.", "properties": { "id": { "description": "ID of the deleted lipsync", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "LipsyncDeleteResponse", "type": "object" }, "CreateHyperframesRenderRequest": { "additionalProperties": false, "description": "Request body for POST /v3/hyperframes/renders.", "properties": { "project": { "description": "HyperFrames composition .zip \u2014 provide as {type: 'url', url: '...'}, {type: 'asset_id', asset_id: '...'} (pre-uploaded via POST /v3/assets), or {type: 'base64', media_type: 'application/zip', data: '...'}. Zip must contain index.html at the root (or the path you set in `composition`).", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Project" }, "fps": { "anyOf": [ { "maximum": 240, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 30, "description": "Output frames per second. Defaults to 30 if not provided.", "title": "Fps" }, "quality": { "default": "standard", "description": "Render quality preset; higher quality is slower.", "enum": [ "draft", "standard", "high" ], "title": "Quality", "type": "string" }, "format": { "default": "mp4", "description": "Output container/codec.", "enum": [ "mp4", "webm", "mov" ], "title": "Format", "type": "string" }, "resolution": { "$ref": "#/components/schemas/HyperframesResolution", "default": "1080p", "description": "Output resolution tier. Defaults to '1080p'. Pass '4k' for 4K renders (billed at 1.5x)." }, "aspect_ratio": { "$ref": "#/components/schemas/HyperframesAspectRatio", "default": "16:9", "description": "Output aspect ratio. Defaults to '16:9' (landscape). Pass '9:16' for portrait or '1:1' for square." }, "composition": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "description": "Entry HTML file relative to the project root (e.g. compositions/intro.html). Defaults to index.html when omitted.", "title": "Composition" }, "variables": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional overrides for the composition's data-composition-variables. Use this to parameterise a single composition across multiple renders.", "title": "Variables" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-text label for the render; echoed back in detail responses.", "title": "Title" }, "callback_id": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque client tracking ID, echoed back in webhook payloads.", "title": "Callback Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Per-request HTTPS webhook URL the render fires when it terminates.", "title": "Callback Url" } }, "required": [ "project" ], "title": "CreateHyperframesRenderRequest", "type": "object" }, "HyperframesAspectRatio": { "description": "Output aspect ratio.\n\nSupported ratios are ``16:9`` (landscape), ``9:16`` (portrait), and\n``1:1`` (square).", "enum": [ "16:9", "9:16", "1:1" ], "title": "HyperframesAspectRatio", "type": "string" }, "HyperframesResolution": { "description": "Output resolution tier.\n\n4K output uses a 1.5x pricing multiplier.", "enum": [ "1080p", "4k" ], "title": "HyperframesResolution", "type": "string" }, "CreateHyperframesRenderResponse": { "description": "Response for POST /v3/hyperframes/renders.", "properties": { "render_id": { "description": "HyperFrames render identifier \u2014 poll GET /v3/hyperframes/renders/{render_id} for status.", "title": "Render Id", "type": "string" } }, "required": [ "render_id" ], "title": "CreateHyperframesRenderResponse", "type": "object" }, "HyperframesRenderDetail": { "description": "Detailed HyperFrames render resource.", "properties": { "render_id": { "description": "Unique render identifier.", "title": "Render Id", "type": "string" }, "status": { "$ref": "#/components/schemas/HyperframesRenderStatus", "description": "Current lifecycle state." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied free-text label.", "title": "Title" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-supplied client tracking ID.", "title": "Callback Id" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the rendered video. Present only when status is 'completed'.", "title": "Video Url" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned download URL for the auto-generated thumbnail.", "title": "Thumbnail Url" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds; null until completed.", "title": "Duration" }, "fps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Frames per second the render was created at.", "title": "Fps" }, "quality": { "anyOf": [ { "enum": [ "draft", "standard", "high" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Render quality preset.", "title": "Quality" }, "format": { "description": "Output container/codec.", "enum": [ "mp4", "webm", "mov" ], "title": "Format", "type": "string" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/HyperframesResolution" }, { "type": "null" } ], "default": null, "description": "Resolution tier, if one was set." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/HyperframesAspectRatio" }, { "type": "null" } ], "default": null, "description": "Aspect ratio, if one was set." }, "composition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Composition entry file path.", "title": "Composition" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the render was created.", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the render terminated. Null until status is 'completed' or 'failed'.", "title": "Completed At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Present only when status is 'failed'.", "title": "Failure Message" } }, "required": [ "render_id", "status", "format" ], "title": "HyperframesRenderDetail", "type": "object" }, "HyperframesRenderStatus": { "description": "Lifecycle status of a HyperFrames render.", "enum": [ "queued", "rendering", "completed", "failed" ], "title": "HyperframesRenderStatus", "type": "string" }, "DeleteHyperframesRenderResponse": { "description": "Response for DELETE /v3/hyperframes/renders/{render_id}.", "properties": { "render_id": { "description": "ID of the deleted render.", "title": "Render Id", "type": "string" } }, "required": [ "render_id" ], "title": "DeleteHyperframesRenderResponse", "type": "object" }, "CustomAgentListResponse": { "description": "200 response body for GET /v3/custom-agents.", "properties": { "agents": { "items": { "$ref": "#/components/schemas/CustomAgentDetail" }, "title": "Agents", "type": "array" } }, "required": [ "agents" ], "title": "CustomAgentListResponse", "type": "object" }, "CustomAgentDetail": { "description": "One registered custom agent.", "properties": { "id": { "description": "Agent id used in the URL path (e.g. `chiron`).", "title": "Id", "type": "string" }, "name": { "description": "Human-readable name.", "title": "Name", "type": "string" }, "description": { "description": "What the agent produces.", "title": "Description", "type": "string" }, "workflow_type": { "description": "Internal Temporal workflow type executed for this agent.", "title": "Workflow Type", "type": "string" } }, "required": [ "id", "name", "description", "workflow_type" ], "title": "CustomAgentDetail", "type": "object" }, "CustomAgentVideoCreateRequest": { "description": "Body for POST /v3/custom-agents/{agent_id}/videos.\n\nAssets (screen recording, still, wallpaper, presenter background) come from the caller \u2014\nupload via `POST /v3/assets/direct-uploads`, then pass the resulting URL in the matching\n`*_url` field here. This endpoint does NOT accept multipart file uploads.", "properties": { "topic": { "description": "What the video should be about.", "maxLength": 512, "minLength": 1, "title": "Topic", "type": "string" }, "lane": { "anyOf": [ { "enum": [ "mac", "iphone", "watch" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Device lane. Agent infers from the topic when omitted.", "title": "Lane" }, "wallpaper": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "`neo-green` / `neo-purple` / `neo-pink` / `wwdc26`, or a user-supplied HTTP(S) URL.", "title": "Wallpaper" }, "avatar_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen avatar id for the on-camera presenter.", "title": "Avatar Id" }, "avatar_still_url": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of a still image (from `/v3/assets/direct-uploads`) for talking-photo inference.", "title": "Avatar Still Url" }, "voice_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice id for narration (HeyGen or ElevenLabs).", "title": "Voice Id" }, "watch_model": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "Watch lane only: ` + ` selector.", "title": "Watch Model" }, "script": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "default": null, "description": "Verbatim voice-over script; agent generates one when omitted.", "title": "Script" }, "screen_recording_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of a screen-recording MP4 (from `/v3/assets/direct-uploads` or your own S3).", "title": "Screen Recording Url" }, "screenshot_urls": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "default": null, "description": "Ordered list of screenshot URLs (from `/v3/assets/direct-uploads` or your own S3). The agent views each in list order via `view_image` and authors one beat per screenshot in that order. Cap 8. When set, takes priority over `screen_recording_url` and the curated `capture_screen` reference library for beats it covers.", "title": "Screenshot Urls" }, "presenter_background_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of an image to composite behind the matted avatar.", "title": "Presenter Background Url" }, "presenter_background_video_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL of a looping video to composite behind the matted avatar.", "title": "Presenter Background Video Url" } }, "required": [ "topic" ], "title": "CustomAgentVideoCreateRequest", "type": "object" }, "CustomAgentVideoCreateResponse": { "description": "202 response body for POST /v3/custom-agents/{agent_id}/videos.", "properties": { "video_id": { "description": "Opaque id; poll GET /v3/custom-agents/{agent_id}/videos/{video_id}.", "title": "Video Id", "type": "string" }, "status": { "default": "RUNNING", "description": "Initial workflow status.", "title": "Status", "type": "string" } }, "required": [ "video_id" ], "title": "CustomAgentVideoCreateResponse", "type": "object" }, "CustomAgentVideoStatusResponse": { "description": "200 response body for GET /v3/custom-agents/{agent_id}/videos/{video_id}.", "properties": { "video_id": { "title": "Video Id", "type": "string" }, "status": { "description": "RUNNING | COMPLETED | FAILED | CANCELED | TIMED_OUT | TERMINATED.", "title": "Status", "type": "string" }, "output_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned MP4 URL when status=COMPLETED.", "title": "Output Video Url" }, "output_snapshot_s3_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Agent workspace snapshot (debug/replay).", "title": "Output Snapshot S3 Uri" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" } }, "required": [ "video_id", "status" ], "title": "CustomAgentVideoStatusResponse", "type": "object" }, "UserInfoResponse": { "properties": { "username": { "examples": [ "user_abc123" ], "title": "Username", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "user@example.com" ], "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Jane" ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Doe" ], "title": "Last Name" }, "billing_type": { "anyOf": [ { "$ref": "#/components/schemas/BillingType" }, { "type": "null" } ], "default": null, "examples": [ "wallet" ] }, "wallet": { "anyOf": [ { "$ref": "#/components/schemas/WalletInfo" }, { "type": "null" } ], "default": null }, "subscription": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionInfo" }, { "type": "null" } ], "default": null }, "usage_based": { "anyOf": [ { "$ref": "#/components/schemas/UsageBasedInfo" }, { "type": "null" } ], "default": null } }, "required": [ "username", "email", "first_name", "last_name" ], "title": "UserInfoResponse", "type": "object" }, "AutoReloadInfo": { "properties": { "enabled": { "examples": [ true ], "title": "Enabled", "type": "boolean" }, "threshold_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 10.0 ], "title": "Threshold Usd" }, "amount_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 50.0 ], "title": "Amount Usd" } }, "required": [ "enabled" ], "title": "AutoReloadInfo", "type": "object" }, "BillingType": { "description": "Discriminator for billing fields. Exactly one of wallet / subscription /\nusage_based is populated depending on this value.\n- wallet: prepaid balance in USD (or credits for Enterprise), API key auth\n- subscription: per-pool credit balances, OAuth integration apps\n- usage_based: metered billing with optional spending cap", "enum": [ "wallet", "subscription", "usage_based" ], "title": "BillingType", "type": "string" }, "CreditPool": { "properties": { "remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "examples": [ 500 ], "title": "Remaining" }, "resets_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "examples": [ "2024-05-01T00:00:00Z" ], "title": "Resets At" } }, "title": "CreditPool", "type": "object" }, "SubscriptionCredits": { "properties": { "premium_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditPool" }, { "type": "null" } ], "default": null }, "add_on_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditPool" }, { "type": "null" } ], "default": null } }, "title": "SubscriptionCredits", "type": "object" }, "SubscriptionInfo": { "properties": { "plan": { "$ref": "#/components/schemas/SubscriptionTier", "examples": [ "team" ] }, "credits": { "$ref": "#/components/schemas/SubscriptionCredits" } }, "required": [ "plan", "credits" ], "title": "SubscriptionInfo", "type": "object" }, "SubscriptionTier": { "enum": [ "free", "starter", "creator", "pro", "team", "enterprise", "business_plus" ], "title": "SubscriptionTier", "type": "string" }, "UsageBasedInfo": { "properties": { "spending_current_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 42.5 ], "title": "Spending Current Usd" }, "spending_cap_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 100.0 ], "title": "Spending Cap Usd" }, "included_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 4444.0 ], "title": "Included Credits" }, "remaining_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 4426.9 ], "title": "Remaining Credits" } }, "title": "UsageBasedInfo", "type": "object" }, "WalletCurrency": { "enum": [ "usd", "credits" ], "title": "WalletCurrency", "type": "string" }, "WalletInfo": { "properties": { "currency": { "$ref": "#/components/schemas/WalletCurrency", "examples": [ "usd" ] }, "remaining_balance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "examples": [ 125.5 ], "title": "Remaining Balance" }, "auto_reload": { "anyOf": [ { "$ref": "#/components/schemas/AutoReloadInfo" }, { "type": "null" } ], "default": null } }, "required": [ "currency" ], "title": "WalletInfo", "type": "object" }, "CurrentAPIKeyResponse": { "properties": { "key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable identifier for this key, matching the key_id shown in the dashboard. Null for legacy keys issued before key identifiers existed.", "title": "Key Id" }, "key_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable name assigned to this API key.", "title": "Key Name" }, "status": { "const": "active", "description": "Current key status. A successful response always means the key is active.", "title": "Status", "type": "string" }, "scope_mode": { "description": "Permission mode applied to this key: full access, read-only access, or an explicit custom allowlist.", "enum": [ "full", "read_only", "custom" ], "title": "Scope Mode", "type": "string" }, "scopes": { "description": "Permission grants held by this key, always present and never empty. Custom keys list their explicit grants. Full-access keys report the wildcard '*:*' and read-only keys report '*:read'; both wildcards also cover permissions added to the catalog after the key was issued, which an expanded list could not express. Match these against an operation's x-heygen-required-scopes in the published OpenAPI spec to decide whether this key may call it.", "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "created_at": { "description": "UTC timestamp when this key was created.", "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "description": "UTC timestamp when this key was last edited.", "format": "date-time", "title": "Updated At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC expiration timestamp, or null when this key never expires.", "title": "Expires At" }, "expires_in_seconds": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Whole seconds until expiration, or null when this key never expires.", "title": "Expires In Seconds" } }, "required": [ "key_id", "key_name", "status", "scope_mode", "scopes", "created_at", "updated_at", "expires_at", "expires_in_seconds" ], "title": "CurrentAPIKeyResponse", "type": "object" }, "CreateWorkflowExecutionRequest": { "additionalProperties": false, "description": "Request body for single-workflow execution via POST /v1/workflows/executions.", "properties": { "workflow_type": { "description": "The workflow type to execute (e.g., 'GenerateImageNode', 'GenerateVideoNode')", "title": "Workflow Type", "type": "string" }, "input": { "additionalProperties": true, "description": "Workflow-specific input matching the workflow's input schema", "title": "Input", "type": "object" } }, "required": [ "workflow_type", "input" ], "title": "CreateWorkflowExecutionRequest", "type": "object" }, "WorkflowExecutionResponse": { "description": "Response after submitting a workflow execution (POST /v1/workflows/executions).", "properties": { "execution_id": { "description": "The execution ID to poll for results", "examples": [ "exec_abc123def456" ], "title": "Execution Id", "type": "string" }, "status": { "default": "submitted", "description": "Initial status of the submission", "examples": [ "submitted" ], "title": "Status", "type": "string" } }, "required": [ "execution_id" ], "title": "WorkflowExecutionResponse", "type": "object" }, "CreateGraphExecutionRequest": { "additionalProperties": false, "description": "Request body for multi-workflow graph execution via POST /v1/workflows/graph-executions.", "properties": { "workflows": { "description": "Workflows to execute as a DAG", "items": { "$ref": "#/components/schemas/WorkflowRequestEntry" }, "maxItems": 20, "minItems": 1, "title": "Workflows", "type": "array" } }, "required": [ "workflows" ], "title": "CreateGraphExecutionRequest", "type": "object" }, "WorkflowRequestEntry": { "additionalProperties": false, "description": "A single workflow within a multi-workflow graph submission.", "properties": { "type": { "description": "The workflow type (e.g., 'TTSNode', 'TrimVideoNode')", "title": "Type", "type": "string" }, "id": { "description": "Unique identifier for this workflow within the graph", "title": "Id", "type": "string" }, "parent": { "description": "IDs of parent workflows this depends on", "items": { "type": "string" }, "title": "Parent", "type": "array" }, "input": { "additionalProperties": true, "description": "Workflow-specific input. Use NodeRef objects to reference parent outputs.", "title": "Input", "type": "object" } }, "required": [ "type", "id", "input" ], "title": "WorkflowRequestEntry", "type": "object" }, "WorkflowExecutionDetailResponse": { "description": "Response for polling a workflow execution (GET /v1/workflows/executions/).", "properties": { "execution_id": { "description": "The execution ID", "examples": [ "exec_abc123def456" ], "title": "Execution Id", "type": "string" }, "status": { "description": "Execution status: submitted | running | completed | failed | not_found", "examples": [ "completed" ], "title": "Status", "type": "string" }, "output": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Workflow output when completed (single-workflow executions)", "examples": [ { "url": "https://files.heygen.ai/output.mp4" } ], "title": "Output" }, "outputs": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "All workflow outputs keyed by workflow ID (multi-workflow graph executions)", "examples": [ { "node_1": { "url": "https://files.heygen.ai/output.mp4" } } ], "title": "Outputs" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowExecutionError" }, { "type": "null" } ], "default": null, "description": "Error details when failed" } }, "required": [ "execution_id", "status" ], "title": "WorkflowExecutionDetailResponse", "type": "object" }, "WorkflowExecutionError": { "description": "Structured error detail for a workflow execution.", "properties": { "code": { "description": "Machine-readable error code", "examples": [ "workflow_timeout" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error message", "examples": [ "Workflow execution timed out after 300s" ], "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "WorkflowExecutionError", "type": "object" }, "WorkflowCatalogEntry": { "description": "Schema information for a single exposed workflow.", "properties": { "workflow_type": { "description": "The workflow type identifier", "examples": [ "GenerateVideoNode" ], "title": "Workflow Type", "type": "string" }, "name": { "description": "Human-readable name", "examples": [ "Generate Video" ], "title": "Name", "type": "string" }, "description": { "description": "What this workflow does", "examples": [ "Generate a video from text and avatar" ], "title": "Description", "type": "string" }, "category": { "description": "Workflow category: content_ai, media_generation, utility", "examples": [ "content_ai" ], "title": "Category", "type": "string" }, "input_schema": { "additionalProperties": true, "description": "JSON Schema for the workflow's input", "examples": [ { "properties": { "text": { "type": "string" } }, "type": "object" } ], "title": "Input Schema", "type": "object" }, "output_schema": { "additionalProperties": true, "description": "JSON Schema for the workflow's output", "examples": [ { "properties": { "url": { "type": "string" } }, "type": "object" } ], "title": "Output Schema", "type": "object" } }, "required": [ "workflow_type", "name", "description", "category", "input_schema", "output_schema" ], "title": "WorkflowCatalogEntry", "type": "object" }, "UpdateAvatarGroupRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/avatars/{group_id}.", "properties": { "default_voice_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID to set as the avatar's default voice, replacing the current one. The voice is also linked to the avatar group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own.", "examples": [ "1bd001e7e50f421d891986aad5c8bbd2" ], "title": "Default Voice Id" } }, "title": "UpdateAvatarGroupRequest", "type": "object" }, "CreateAvatarConsentRequest": { "description": "Request body for POST /v3/avatars/{group_id}/consent.", "properties": { "reroute_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Callback URL where the user is redirected after completing consent. Defaults to HeyGen's consent completion page.", "title": "Reroute Url" }, "consent_text": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Custom consent text rendered on the consent page in place of the default HeyGen text. Available as a premium option for select Enterprise customers \u2014 e.g. to display co-branded language like \"I, (Name), hereby allow HeyGen and {Company} to use footage of me...\". Plain text only; rendered as text (not HTML). The characters `<` and `>` are rejected to prevent stored-HTML injection. To request access, please contact our support team.", "title": "Consent Text", "x-cli-visible": false, "x-mcp-visible": false }, "consent_video": { "anyOf": [ { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, { "type": "null" } ], "default": null, "description": "Pre-recorded consent video to submit directly instead of visiting the browser consent page \u2014 provide as {\"type\": \"url\", \"url\": \"https://...\"} or {\"type\": \"asset_id\", \"asset_id\": \"...\"}. When supplied, no consent URL is returned and the video is submitted immediately for review; reroute_url and consent_text do not apply and cannot be combined with this field. Available only to enterprise API customers \u2014 contact support to request access.", "title": "Consent Video", "x-cli-visible": false, "x-mcp-visible": false } }, "title": "CreateAvatarConsentRequest", "type": "object" }, "CreateAvatarConsentResponse": { "description": "Response body for POST /v3/avatars/{group_id}/consent.", "properties": { "avatar_group": { "$ref": "#/components/schemas/AvatarGroupItem", "description": "The avatar group associated with this consent." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the consent page. The link expires 24 hours after creation and is valid for one successful consent submission. A recording submitted after expiry fails and the group stays in pending consent status, and an expired link cannot be revived, so create a new consent link if the subject has not recorded within 24 hours. Omitted when consent_video was submitted directly.", "title": "Url" } }, "required": [ "avatar_group" ], "title": "CreateAvatarConsentResponse", "type": "object" }, "AvatarGroupDeleteResponse": { "description": "Response for DELETE /v3/avatars/{group_id}.", "properties": { "id": { "description": "ID of the deleted avatar group.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "AvatarGroupDeleteResponse", "type": "object" }, "CreateAvatarLooksRequestBody": { "description": "Request body for POST /v3/avatars/looks.", "discriminator": { "mapping": { "look_pack": "#/components/schemas/CreateLookPackLooksRequest", "template": "#/components/schemas/CreateTemplateLooksRequest" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CreateLookPackLooksRequest" }, { "$ref": "#/components/schemas/CreateTemplateLooksRequest" } ], "title": "CreateAvatarLooksRequestBody" }, "CreateLookPackLooksRequest": { "additionalProperties": false, "description": "Generate a Look Pack's looks into the avatar an existing look belongs to.", "properties": { "type": { "const": "look_pack", "description": "Generation method. 'look_pack' applies a Look Pack template.", "title": "Type", "type": "string" }, "reference_look_id": { "description": "An existing avatar look used as the identity reference. The new looks are added to its avatar.", "maxLength": 128, "minLength": 1, "title": "Reference Look Id", "type": "string" }, "template_id": { "description": "The Look Pack template to apply: a public template, or an enterprise custom pack assigned to your workspace.", "maxLength": 128, "minLength": 1, "title": "Template Id", "type": "string" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/LookPackAspectRatio" }, { "type": "null" } ], "default": null, "description": "Output aspect ratio, '16:9' by default. Generation is always 16:9; '9:16' center-crops the delivered frames to portrait as the final step." } }, "required": [ "type", "reference_look_id", "template_id" ], "title": "CreateLookPackLooksRequest", "type": "object" }, "CreateTemplateLooksRequest": { "additionalProperties": false, "description": "Restyle an existing avatar look into a single look template; the results are added to its avatar.", "properties": { "type": { "const": "template", "description": "Generation method. 'template' restyles the reference look into a single look template, producing two looks in the template's aspect ratio.", "title": "Type", "type": "string" }, "reference_look_id": { "description": "An existing avatar look used as the identity reference. The new looks are added to its avatar.", "maxLength": 128, "minLength": 1, "title": "Reference Look Id", "type": "string" }, "template_id": { "description": "The single look template to apply: a public template, or an enterprise custom template assigned to your workspace. A Look Pack is applied with type 'look_pack' instead.", "maxLength": 128, "minLength": 1, "title": "Template Id", "type": "string" } }, "required": [ "type", "reference_look_id", "template_id" ], "title": "CreateTemplateLooksRequest", "type": "object" }, "LookPackAspectRatio": { "enum": [ "16:9", "9:16" ], "title": "LookPackAspectRatio", "type": "string" }, "CreateAvatarLooksResponse": { "description": "Response for POST /v3/avatars/looks.", "properties": { "group_id": { "description": "The avatar group the looks were added to. Pass it as the group_id filter of GET /v3/avatars/looks to list them all.", "title": "Group Id", "type": "string" }, "looks": { "description": "The new looks, one per generated image, in output order.", "items": { "$ref": "#/components/schemas/CreatedLookRef" }, "title": "Looks", "type": "array" } }, "required": [ "group_id", "looks" ], "title": "CreateAvatarLooksResponse", "type": "object" }, "CreatedLookRef": { "properties": { "id": { "description": "ID of a new look. Poll GET /v3/avatars/looks/{id}: its status stays 'processing' until it is either 'completed' (preview available, and the id is usable as avatar_id for POST /v3/videos) or 'failed' (see its error).", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "CreatedLookRef", "type": "object" }, "LookTemplateItem": { "description": "One template the caller may pass as ``template_id`` to POST /v3/avatars/looks.", "properties": { "id": { "description": "Template identifier. Pass it as template_id to POST /v3/avatars/looks, with the type this item reports.", "examples": [ "5a8e6be843ee4321a014946bf62aa322" ], "title": "Id", "type": "string" }, "type": { "$ref": "#/components/schemas/LookTemplateType", "description": "The type to send on POST /v3/avatars/looks to apply this template.", "examples": [ "look_pack" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name of the template.", "examples": [ "Modern Corporate" ], "title": "Name" }, "gender": { "anyOf": [ { "$ref": "#/components/schemas/LookTemplateGender" }, { "type": "null" } ], "default": null, "description": "Gender the template's looks are built for. Null when the template suits any avatar.", "examples": [ "female" ] }, "preview_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Cover image for the template, showing what the generated looks resemble.", "examples": [ "https://resource2.heygen.ai/avatar_remix_template/modern_corporate_female/profile.png" ], "title": "Preview Image Url" }, "looks_count": { "description": "How many looks applying this template generates. A Look Pack's size varies by pack; a single look template generates two.", "examples": [ 5 ], "title": "Looks Count", "type": "integer" } }, "required": [ "id", "type", "looks_count" ], "title": "LookTemplateItem", "type": "object" }, "LookTemplateGender": { "description": "Gender a template's curated looks are built for.", "enum": [ "male", "female" ], "title": "LookTemplateGender", "type": "string" }, "LookTemplateType": { "description": "What a template is, named by the ``type`` that applies it on POST /v3/avatars/looks.\n\nDeliberately NOT the ``avatar_remix_templates.template_type`` wire values ('pack' / 'single'):\nthe whole point of the listing is that the value you read is the value you send back.", "enum": [ "look_pack", "template" ], "title": "LookTemplateType", "type": "string" }, "UpdateAvatarLookRequest": { "description": "Request body for PATCH /v3/avatars/looks/.", "properties": { "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "New display name for the look.", "title": "Name" } }, "title": "UpdateAvatarLookRequest", "type": "object" }, "AvatarLookDeleteResponse": { "description": "Response for DELETE /v3/avatars/looks/{look_id}.", "properties": { "id": { "description": "ID of the deleted avatar look.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "AvatarLookDeleteResponse", "type": "object" }, "WebhookEventTypeItem": { "description": "A webhook event type with its description.", "properties": { "event_type": { "description": "The event type identifier, e.g. 'avatar_video.success'.", "examples": [ "avatar_video.success" ], "title": "Event Type", "type": "string" }, "description": { "description": "Human-readable description of when this event fires.", "examples": [ "Fired when an avatar video completes rendering successfully." ], "title": "Description", "type": "string" } }, "required": [ "event_type", "description" ], "title": "WebhookEventTypeItem", "type": "object" }, "WebhookEndpointResponse": { "description": "A registered webhook endpoint.", "properties": { "endpoint_id": { "description": "Unique identifier for this webhook endpoint.", "examples": [ "ep_abc123def456" ], "title": "Endpoint Id", "type": "string" }, "url": { "description": "The URL that receives webhook POST requests.", "examples": [ "https://example.com/webhook" ], "title": "Url", "type": "string" }, "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Event types this endpoint subscribes to. Null means all events.", "examples": [ [ "avatar_video.success", "avatar_video.fail" ] ], "title": "Events" }, "status": { "description": "Endpoint status: 'enabled' or 'disabled'.", "examples": [ "enabled" ], "title": "Status", "type": "string" }, "created_at": { "description": "ISO 8601 timestamp when the endpoint was created.", "examples": [ "2024-04-01T12:00:00Z" ], "title": "Created At", "type": "string" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The signing secret for verifying webhook payloads. Only returned on create and rotate-secret.", "examples": [ "whsec_abc123def456" ], "title": "Secret" } }, "required": [ "endpoint_id", "url", "status", "created_at" ], "title": "WebhookEndpointResponse", "type": "object" }, "CreateWebhookEndpointRequest": { "additionalProperties": false, "description": "Request body for POST /v3/webhooks/endpoints.", "properties": { "url": { "description": "Publicly accessible HTTPS URL that will receive webhook POST requests.", "title": "Url", "type": "string" }, "events": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Event types to subscribe to. Omit or set to null to receive all events.", "title": "Events" }, "entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project).", "title": "Entity Id" } }, "required": [ "url" ], "title": "CreateWebhookEndpointRequest", "type": "object" }, "WebhookEventType": { "enum": [ "avatar_video.success", "avatar_video.fail", "avatar_video_gif.success", "avatar_video_gif.fail", "video_translate.success", "video_translate.fail", "video_translate.preflight.validation_failed", "video_translate.preflight.download_failed", "personalized_video", "instant_avatar.success", "instant_avatar.fail", "photo_avatar_generation.success", "photo_avatar_generation.fail", "photo_avatar_train.success", "photo_avatar_train.fail", "photo_avatar_add_motion.success", "photo_avatar_add_motion.fail", "proofread_creation.success", "proofread_creation.fail", "live_avatar.success", "live_avatar.fail", "avatar_video_caption.success", "avatar_video_caption.fail", "video_agent.success", "video_agent.fail", "hyperframes_video.success", "hyperframes_video.fail", "ai_clipping.success", "ai_clipping.fail", "filler_word_removal.success", "filler_word_removal.fail", "podcast.success", "podcast.fail", "batch.finished" ], "title": "WebhookEventType", "type": "string" }, "UpdateWebhookEndpointRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/webhooks/endpoints/{endpoint_id}.", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "New URL for the endpoint. Must be publicly accessible HTTPS.", "title": "Url" }, "events": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "New list of event types to subscribe to. Replaces the existing list.", "title": "Events" } }, "title": "UpdateWebhookEndpointRequest", "type": "object" }, "RotateSecretResponseData": { "description": "Response from rotating a webhook endpoint's signing secret.", "properties": { "endpoint_id": { "description": "The endpoint whose secret was rotated.", "examples": [ "ep_abc123def456" ], "title": "Endpoint Id", "type": "string" }, "secret": { "description": "The new signing secret. Store it securely \u2014 it will not be shown again.", "examples": [ "whsec_new_abc123def456" ], "title": "Secret", "type": "string" } }, "required": [ "endpoint_id", "secret" ], "title": "RotateSecretResponseData", "type": "object" }, "WebhookEventResponse": { "description": "A delivered webhook event.", "properties": { "event_id": { "description": "Unique identifier for this event delivery.", "examples": [ "evt_abc123def456" ], "title": "Event Id", "type": "string" }, "event_type": { "description": "The event type, e.g. 'avatar_video.success'.", "examples": [ "avatar_video.success" ], "title": "Event Type", "type": "string" }, "event_data": { "additionalProperties": true, "description": "The event payload data.", "examples": [ { "status": "completed", "video_id": "v_abc123" } ], "title": "Event Data", "type": "object" }, "created_at": { "description": "ISO 8601 timestamp when the event was created.", "examples": [ "2024-04-01T12:00:00Z" ], "title": "Created At", "type": "string" } }, "required": [ "event_id", "event_type", "event_data", "created_at" ], "title": "WebhookEventResponse", "type": "object" }, "AssetSearchItem": { "discriminator": { "mapping": { "icon": "#/components/schemas/IconAssetItem", "image": "#/components/schemas/ImageAssetItem" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ImageAssetItem" }, { "$ref": "#/components/schemas/IconAssetItem" } ] }, "IconAssetItem": { "description": "An icon result \u2014 typically a transparent vector cutout.", "properties": { "id": { "description": "Opaque identifier for this search result.", "examples": [ "9f8a3c1bd4e2f6a7.png" ], "title": "Id", "type": "string" }, "url": { "description": "Direct URL to the asset. For the current public-library results this is a stable, long-lived URL.", "examples": [ "https://static.example.com/assets/9f8a3c1bd4e2f6a7.png" ], "title": "Url", "type": "string" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pixel width, when known.", "examples": [ 1024 ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pixel height, when known.", "examples": [ 768 ], "title": "Height" }, "orientation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "'landscape', 'portrait', or 'square', when known.", "examples": [ "landscape" ], "title": "Orientation" }, "is_transparent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the asset has visible transparency (e.g. an icon or cut-out), when known.", "examples": [ true ], "title": "Is Transparent" }, "type": { "const": "icon", "default": "icon", "description": "Result type discriminator. Always 'icon'.", "title": "Type", "type": "string" } }, "required": [ "id", "url" ], "title": "IconAssetItem", "type": "object" }, "ImageAssetItem": { "description": "A photographic image result.", "properties": { "id": { "description": "Opaque identifier for this search result.", "examples": [ "9f8a3c1bd4e2f6a7.png" ], "title": "Id", "type": "string" }, "url": { "description": "Direct URL to the asset. For the current public-library results this is a stable, long-lived URL.", "examples": [ "https://static.example.com/assets/9f8a3c1bd4e2f6a7.png" ], "title": "Url", "type": "string" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pixel width, when known.", "examples": [ 1024 ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pixel height, when known.", "examples": [ 768 ], "title": "Height" }, "orientation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "'landscape', 'portrait', or 'square', when known.", "examples": [ "landscape" ], "title": "Orientation" }, "is_transparent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the asset has visible transparency (e.g. an icon or cut-out), when known.", "examples": [ true ], "title": "Is Transparent" }, "type": { "const": "image", "default": "image", "description": "Result type discriminator. Always 'image'.", "title": "Type", "type": "string" } }, "required": [ "id", "url" ], "title": "ImageAssetItem", "type": "object" }, "UploadAssetV3Response": { "description": "Response from uploading an asset via POST /v3/assets.", "properties": { "asset_id": { "description": "Unique asset identifier for use in other endpoints like POST /v3/video-agents", "title": "Asset Id", "type": "string" }, "url": { "description": "Public URL of the uploaded asset", "title": "Url", "type": "string" }, "mime_type": { "description": "Detected MIME type of the file", "title": "Mime Type", "type": "string" }, "size_bytes": { "description": "File size in bytes", "title": "Size Bytes", "type": "integer" } }, "required": [ "asset_id", "url", "mime_type", "size_bytes" ], "title": "UploadAssetV3Response", "type": "object" }, "GetAssetV3Response": { "description": "Response payload for GET /v3/assets/{asset_id} and items of GET /v3/assets.", "properties": { "id": { "description": "Unique asset identifier.", "title": "Id", "type": "string" }, "name": { "description": "Display name of the asset \u2014 the original filename for API uploads.", "title": "Name", "type": "string" }, "type": { "description": "Asset file type (e.g. 'image', 'video', 'audio', 'font').", "title": "Type", "type": "string" }, "owner": { "description": "Username of the asset owner.", "title": "Owner", "type": "string" }, "space_id": { "description": "Identifier of the space the asset belongs to.", "title": "Space Id", "type": "string" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the folder the asset is stored in. Null if the asset is at the space root.", "title": "Folder Id" }, "uploaded_at": { "description": "Unix timestamp (seconds) of when the asset was uploaded.", "title": "Uploaded At", "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Publicly accessible URL for the asset. Null if no URL can be generated.", "title": "Url" } }, "required": [ "id", "name", "type", "owner", "space_id", "uploaded_at" ], "title": "GetAssetV3Response", "type": "object" }, "DeleteAssetV3Response": { "description": "Response for DELETE /v3/assets/{asset_id}.", "properties": { "id": { "description": "ID of the deleted asset.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "DeleteAssetV3Response", "type": "object" }, "CreateAssetUploadRequest": { "description": "Request to begin a presigned direct-to-S3 upload (POST /v3/assets/direct-uploads).", "properties": { "filename": { "description": "Original filename for reference/metadata. The stored object's extension is derived from content_type.", "title": "Filename", "type": "string" }, "content_type": { "description": "Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf', 'application/zip'). Verified against the stored bytes at completion.", "title": "Content Type", "type": "string" }, "size_bytes": { "description": "Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.", "title": "Size Bytes", "type": "integer" }, "checksum_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.", "title": "Checksum Sha256" } }, "required": [ "filename", "content_type", "size_bytes" ], "title": "CreateAssetUploadRequest", "type": "object" }, "CreateAssetUploadResponse": { "description": "Presigned upload instructions.", "properties": { "asset_id": { "description": "Reusable asset identifier. Becomes usable after POST /v3/assets/{asset_id}/complete.", "title": "Asset Id", "type": "string" }, "upload_url": { "description": "Presigned S3 URL. PUT the raw file bytes here.", "title": "Upload Url", "type": "string" }, "upload_headers": { "additionalProperties": { "type": "string" }, "description": "Headers that must be sent verbatim on the PUT request.", "title": "Upload Headers", "type": "object" }, "expires_in_seconds": { "description": "Seconds until the upload URL expires.", "title": "Expires In Seconds", "type": "integer" }, "max_bytes": { "description": "Maximum allowed upload size in bytes for this content type: 1.5 GB (1,500,000,000 bytes) per audio file and 200 MiB (209,715,200 bytes) for other supported files.", "title": "Max Bytes", "type": "integer" }, "status": { "const": "pending_upload", "description": "Upload lifecycle status. Always 'pending_upload' here.", "title": "Status", "type": "string" } }, "required": [ "asset_id", "upload_url", "upload_headers", "expires_in_seconds", "max_bytes", "status" ], "title": "CreateAssetUploadResponse", "type": "object" }, "CompleteAssetUploadRequest": { "description": "Finalize a presigned upload (POST /v3/assets/{asset_id}/complete).", "properties": { "checksum_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional SHA256 (hex) cross-check.", "title": "Checksum Sha256" } }, "title": "CompleteAssetUploadRequest", "type": "object" }, "CompleteAssetUploadResponse": { "description": "Result of finalizing an upload.", "properties": { "asset_id": { "description": "The reusable asset identifier.", "title": "Asset Id", "type": "string" }, "url": { "description": "Public URL of the finalized asset.", "title": "Url", "type": "string" }, "mime_type": { "description": "MIME type detected from the stored bytes.", "title": "Mime Type", "type": "string" }, "size_bytes": { "description": "Size of the stored object in bytes.", "title": "Size Bytes", "type": "integer" }, "status": { "const": "processing", "description": "Asset status, e.g. 'processing'.", "title": "Status", "type": "string" } }, "required": [ "asset_id", "url", "mime_type", "size_bytes", "status" ], "title": "CompleteAssetUploadResponse", "type": "object" }, "GetSessionResponse": { "description": "Response from getting a video agent session.", "properties": { "session_id": { "description": "Session ID", "title": "Session Id", "type": "string" }, "status": { "description": "Session status. If a generate session pauses for input before creating its reserved video, the session is waiting_for_input while the reserved video is failed.", "enum": [ "thinking", "waiting_for_input", "reviewing", "generating", "completed", "failed" ], "title": "Status", "type": "string" }, "progress": { "default": 0, "description": "Progress 0-100", "title": "Progress", "type": "integer" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM-generated session title", "title": "Title" }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video ID once generation starts", "title": "Video Id" }, "created_at": { "description": "Unix timestamp of session creation", "title": "Created At", "type": "integer" }, "messages": { "description": "Most recent visible messages (max 40, newest-first)", "items": { "$ref": "#/components/schemas/SessionMessage" }, "title": "Messages", "type": "array" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/SessionError" }, { "type": "null" } ], "default": null, "description": "Error details when a failed session has a specific, caller-actionable reason (e.g. a billing paywall). Absent for generic failures with no surfaced reason." } }, "required": [ "session_id", "status", "created_at" ], "title": "GetSessionResponse", "type": "object" }, "SessionError": { "description": "Error details for a failed video agent session: a machine-readable code plus a\nhuman-readable message.", "properties": { "code": { "description": "Machine-readable error code.", "examples": [ "free_tier_quota_exceeded", "paid_tier_quota_exceeded" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error description.", "examples": [ "You've reached your plan's video generation quota. Upgrade your plan to continue generating videos." ], "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "SessionError", "type": "object" }, "SessionMessage": { "description": "Simplified chat message for external consumers.", "properties": { "role": { "description": "Message author: 'user' or 'model'", "title": "Role", "type": "string" }, "content": { "description": "Message text content", "title": "Content", "type": "string" }, "type": { "$ref": "#/components/schemas/SessionMessageType", "description": "Message type: text, resource, or error" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp of message creation", "title": "Created At" }, "resource_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Resource IDs referenced in this message", "title": "Resource Ids" } }, "required": [ "role", "content", "type" ], "title": "SessionMessage", "type": "object" }, "SessionMessageType": { "description": "Public message types exposed to external consumers.", "enum": [ "text", "resource", "error" ], "title": "SessionMessageType", "type": "string" }, "SendMessageRequest": { "additionalProperties": false, "anyOf": [ { "properties": { "message": { "minLength": 1, "type": "string" } }, "required": [ "message" ] }, { "properties": { "edit_plan": { "minItems": 1, "type": "array" } }, "required": [ "edit_plan" ] } ], "description": "One conversational or scene-edit turn in an existing Video Agent session.", "properties": { "message": { "default": "", "description": "Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided.", "maxLength": 10000, "title": "Message", "type": "string" }, "avatar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Override avatar for this message", "title": "Avatar Id" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Override voice for this message", "title": "Voice Id" }, "brand_kit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted.", "title": "Brand Kit Id" }, "files": { "anyOf": [ { "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional file attachments (max 20 files)", "title": "Files" }, "edit_plan": { "anyOf": [ { "items": { "$ref": "#/components/schemas/VideoAgentSceneEdit" }, "maxItems": 50, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "description": "Scene-scoped natural-language edits to validate and submit atomically. Required when message is omitted or empty.", "title": "Edit Plan" } }, "title": "SendMessageRequest", "type": "object" }, "VideoAgentSceneEdit": { "additionalProperties": false, "description": "A public scene edit tied to the editor snapshot that supplied its scene ID.", "properties": { "scene_id": { "description": "Scene ID returned by GET /v3/videos/{scene_snapshot_video_id}/scenes", "maxLength": 255, "minLength": 1, "title": "Scene Id", "type": "string" }, "text": { "description": "Natural-language change to apply to this scene", "maxLength": 10000, "minLength": 1, "title": "Text", "type": "string" }, "scene_snapshot_video_id": { "description": "Video ID whose GET /v3/videos/{video_id}/scenes response supplied this scene ID", "minLength": 1, "title": "Scene Snapshot Video Id", "type": "string" }, "edit_version": { "description": "Opaque edit version returned with that video snapshot", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "title": "Edit Version", "type": "string" } }, "required": [ "scene_id", "text", "scene_snapshot_video_id", "edit_version" ], "title": "VideoAgentSceneEdit", "type": "object" }, "SendMessageResponse": { "description": "Response from submitting a turn to a session.", "properties": { "session_id": { "description": "Session ID", "title": "Session Id", "type": "string" }, "run_id": { "description": "Run ID for this message processing", "title": "Run Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM-generated session title", "title": "Title" }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working draft video ID for an edit turn; poll GET /v3/videos/{video_id} for status", "title": "Video Id" } }, "required": [ "session_id", "run_id" ], "title": "SendMessageResponse", "type": "object" }, "SessionResource": { "description": "Simplified session resource for external consumers.", "properties": { "resource_id": { "description": "Resource identifier", "title": "Resource Id", "type": "string" }, "resource_type": { "description": "Resource type: image, video, draft, avatar, voice, etc.", "title": "Resource Type", "type": "string" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source: generated or user_uploaded", "title": "Source Type" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary media URL", "title": "Url" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Thumbnail URL", "title": "Thumbnail Url" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Preview URL", "title": "Preview Url" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp of resource creation", "title": "Created At" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Type-specific metadata", "title": "Metadata" } }, "required": [ "resource_id", "resource_type" ], "title": "SessionResource", "type": "object" }, "StopSessionRequest": { "additionalProperties": false, "description": "Request body for stopping a session (empty \u2014 no fields required).", "properties": {}, "title": "StopSessionRequest", "type": "object" }, "StopSessionResponse": { "description": "Response from stopping a session.", "properties": { "session_id": { "description": "Session ID", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "StopSessionResponse", "type": "object" }, "AiClippingDetail": { "description": "Full job resource returned by Get, List, and webhook payloads.", "properties": { "id": { "description": "Unique job identifier.", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title.", "title": "Title" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "Job lifecycle status." }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Detected or supplied source language code.", "title": "Input Language" }, "source_duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Duration of the source video in seconds.", "title": "Source Duration" }, "output_settings": { "anyOf": [ { "$ref": "#/components/schemas/HighlightOutputSettings" }, { "type": "null" } ], "default": null, "description": "Currently omitted from Get, List, and webhook responses." }, "clips": { "description": "Produced clips. Empty until the job's first clip is rendered.", "items": { "$ref": "#/components/schemas/Clip" }, "title": "Clips", "type": "array" }, "progress": { "default": 0, "description": "Approximate progress (0-100). 100 when all clips completed. GET /v3/ai-clipping/{id} returns live in-flight progress; the list endpoint reports a coarse value (0 until completed, then 100). Poll the single-get endpoint for granular progress.", "maximum": 100, "minimum": 0, "title": "Progress", "type": "integer" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Client-provided callback ID.", "title": "Callback Id" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp (seconds) of job creation.", "title": "Created At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status=failed.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "AiClippingDetail", "type": "object" }, "CaptionStylePreset": { "description": "Available caption style presets.", "enum": [ "subtle_gray", "shadow_mint", "subtle_cyan", "stamp_red", "retro_gold", "block_dark", "racing", "modern_dark", "modern_boxed", "chunky", "clean", "shadow_lime", "tag_yellow", "pop_purple", "spotlight", "outline_classic", "exotic", "golden", "simple", "pop_single", "energy", "bold", "elegant", "neon_pink" ], "title": "CaptionStylePreset", "type": "string" }, "Clip": { "description": "A single produced clip. Returned inline inside AiClippingDetail.", "properties": { "id": { "description": "Unique clip identifier.", "title": "Id", "type": "string" }, "status": { "$ref": "#/components/schemas/ClipStatus", "description": "Per-clip status." }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Final clip duration in seconds. Null until status=completed.", "title": "Duration Seconds" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/OutputAspectRatio" }, { "type": "null" } ], "default": null, "description": "Clip aspect ratio. Null until status=completed." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Model-generated clip title.", "title": "Title" }, "virality_score": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Model-predicted virality score (0-100). Null until status=completed.", "title": "Virality Score" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned thumbnail URL. Null until status=completed.", "title": "Thumbnail Url" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned MP4 download URL. Null until status=completed.", "title": "Video Url" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Per-clip failure description. Currently always null.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "Clip", "type": "object" }, "ClipStatus": { "description": "Per-clip lifecycle. A job can produce N clips, each completing separately.", "enum": [ "pending", "completed", "failed" ], "title": "ClipStatus", "type": "string" }, "HighlightOutputSettings": { "additionalProperties": false, "description": "Configuration for the clips the job will produce.", "properties": { "duration_types": { "description": "One or more target clip durations to produce. Each produces a separate clip.", "items": { "$ref": "#/components/schemas/OutputDuration" }, "maxItems": 4, "minItems": 1, "title": "Duration Types", "type": "array" }, "aspect_ratio": { "$ref": "#/components/schemas/OutputAspectRatio", "default": "portrait", "description": "Aspect ratio for all produced clips. Default 'portrait' (9:16, social-ready)." }, "captions": { "default": true, "description": "Burn captions into the clips. Set false to disable.", "title": "Captions", "type": "boolean" }, "caption_style": { "$ref": "#/components/schemas/CaptionStylePreset", "default": "outline_classic", "description": "Named caption style preset (e.g. 'outline_classic', 'bold'). Defaults to 'outline_classic'. Null or unrecognized values fall back to the default." }, "prompt": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional editorial guidance for the highlight model. Max 500 characters.", "title": "Prompt" } }, "title": "HighlightOutputSettings", "type": "object" }, "JobStatus": { "description": "Public job lifecycle.", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "JobStatus", "type": "string" }, "OutputAspectRatio": { "description": "Output aspect ratio for produced clips.", "enum": [ "landscape", "portrait", "square" ], "title": "OutputAspectRatio", "type": "string" }, "OutputDuration": { "description": "Target clip duration. ``long`` returns the model's choice >180s.", "enum": [ "30", "60", "180", "long" ], "title": "OutputDuration", "type": "string" }, "DeleteAiClippingResponse": { "description": "Response for DELETE /v3/ai-clipping/{id}.", "properties": { "id": { "description": "ID of the deleted AI clip job.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "DeleteAiClippingResponse", "type": "object" }, "CreateAiClippingRequest": { "additionalProperties": false, "description": "Request body for POST /v3/ai-clipping.", "properties": { "video": { "description": "Source video. Either a URL or an asset_id from POST /v1/asset.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Video" }, "title": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Title for the job. Defaults to the source video's title if omitted.", "title": "Title" }, "input_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-639-1 source language code (e.g. 'en', 'es'). Omit for auto-detect.", "title": "Input Language" }, "output_settings": { "$ref": "#/components/schemas/HighlightOutputSettings", "description": "Configuration for the produced clips (duration mix, aspect ratio, captions, etc.)." }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTTPS URL to receive per-job webhook callbacks. Mirrors /v3/video-translations callback_url. Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret (the signature header is sent only to registered endpoints).", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque client identifier echoed verbatim in webhook payloads. Mirrors /v3/video-translations callback_id.", "title": "Callback Id" } }, "required": [ "video" ], "title": "CreateAiClippingRequest", "type": "object" }, "CreateAiClippingResponse": { "description": "Response for POST /v3/ai-clipping. Mirrors the v3 single-ID create shape.", "properties": { "ai_clipping_id": { "description": "Unique job identifier. Use with all other endpoints.", "title": "Ai Clipping Id", "type": "string" } }, "required": [ "ai_clipping_id" ], "title": "CreateAiClippingResponse", "type": "object" }, "CreateFillerWordRemovalRequest": { "additionalProperties": false, "description": "Request body for POST /v3/filler-word-removals.", "properties": { "video": { "description": "Source video to clean. Either a URL or an asset_id from POST /v1/asset.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ], "title": "Video" }, "title": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the job. Defaults to 'Filler Removal' if omitted.", "title": "Title" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTTPS URL to receive per-job webhook callbacks (filler_word_removal.success / filler_word_removal.fail). Delivery is best-effort with limited retries \u2014 poll GET /v3/filler-word-removals/{id} as the source of truth (a terminal GET may precede its webhook). Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret via /v3/webhooks/endpoints.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque client identifier echoed verbatim in webhook payloads.", "title": "Callback Id" } }, "required": [ "video" ], "title": "CreateFillerWordRemovalRequest", "type": "object" }, "CreateFillerWordRemovalResponse": { "description": "Response for POST /v3/filler-word-removals. Mirrors the v3 single-ID create shape.", "properties": { "filler_word_removal_id": { "description": "Unique job identifier. Use with GET /v3/filler-word-removals/{id}.", "title": "Filler Word Removal Id", "type": "string" } }, "required": [ "filler_word_removal_id" ], "title": "CreateFillerWordRemovalResponse", "type": "object" }, "FillerWordRemovalDetail": { "description": "Full job resource returned by GET /v3/filler-word-removals/{id}.\n\nInvariant: ``status=completed`` always carries a ``video_url`` \u2014 when the\nrun changes nothing (no filler cuts and no silence trims) the output is a\nbyte-copy of the original and the charge is auto-refunded, so polling\nscripts never need a special no-op branch. Note ``num_cuts`` counts filler\nsegments only; a run may report ``num_cuts=0`` yet still be billed when it\ntrimmed long silences (``reduction_pct > 0``).", "properties": { "id": { "description": "Unique job identifier.", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title.", "title": "Title" }, "status": { "$ref": "#/components/schemas/FillerWordRemovalDetailJobStatus", "description": "Job lifecycle status." }, "progress": { "default": 0, "description": "Approximate progress (0-100). 100 when completed.", "maximum": 100, "minimum": 0, "title": "Progress", "type": "integer" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned MP4 download URL of the cleaned video. Present when status=completed. Expires \u2014 re-fetch this endpoint for a fresh link.", "title": "Video Url" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned thumbnail URL. Only present when status=completed and a thumbnail was generated.", "title": "Thumbnail Url" }, "original_duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Duration of the source video in seconds. Present when status=completed.", "title": "Original Duration" }, "output_duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Duration of the cleaned video in seconds. Present when status=completed.", "title": "Output Duration" }, "num_cuts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of filler segments removed (silence-only trims are not counted \u2014 compare reduction_pct). The charge auto-refunds only when the run changed nothing at all. Present when status=completed.", "title": "Num Cuts" }, "reduction_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Percentage of the source duration removed. Present when status=completed.", "title": "Reduction Pct" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Client-provided callback ID echoed from the create request.", "title": "Callback Id" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp (seconds) of job creation.", "title": "Created At" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Only present when status=failed.", "title": "Failure Message" } }, "required": [ "id", "status" ], "title": "FillerWordRemovalDetail", "type": "object" }, "FillerWordRemovalDetailJobStatus": { "description": "Public job lifecycle.", "enum": [ "pending", "running", "completed", "failed" ], "title": "JobStatus", "type": "string" }, "CreateVideoBatchRequest": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name for the batch, shown in the HeyGen app.", "title": "Title" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root.", "title": "Folder Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL invoked once when every item in the batch reaches a terminal state.", "title": "Callback Url" }, "videos": { "description": "Video creation requests (avatar / image / cinematic_avatar). Set folder_id once on the batch request, not on individual videos. Max 100 per batch.", "items": { "discriminator": { "mapping": { "avatar": "#/components/schemas/CreateBatchVideoFromAvatar", "cinematic_avatar": "#/components/schemas/CreateBatchVideoFromCinematicAvatar", "image": "#/components/schemas/CreateBatchVideoFromImage", "studio": "#/components/schemas/CreateBatchVideoFromStudio" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CreateBatchVideoFromAvatar" }, { "$ref": "#/components/schemas/CreateBatchVideoFromImage" }, { "$ref": "#/components/schemas/CreateBatchVideoFromCinematicAvatar" }, { "$ref": "#/components/schemas/CreateBatchVideoFromStudio" } ] }, "maxItems": 100, "minItems": 1, "title": "Videos", "type": "array" } }, "required": [ "videos" ], "title": "CreateVideoBatchRequest", "type": "object" }, "CreateBatchVideoFromAvatar": { "additionalProperties": false, "description": "Create a video from a HeyGen avatar (video or photo avatar).\n\nProvide an avatar_id to use a previously created avatar. Supports all\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\nserver defaults to Avatar IV.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "fit": { "anyOf": [ { "$ref": "#/components/schemas/AvatarFit" }, { "type": "null" } ], "default": null, "description": "How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations." }, "background": { "anyOf": [ { "$ref": "#/components/schemas/BackgroundSetting" }, { "type": "null" } ], "default": null, "description": "Background settings for the video." }, "remove_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Remove the avatar background. Video avatars must be trained with matting enabled.", "title": "Remove Background" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically \u2014 the caller does not need to set 'remove_background'." }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "type": { "const": "avatar", "description": "Must be 'avatar' for avatar-based video creation.", "title": "Type", "type": "string" }, "avatar_id": { "description": "HeyGen avatar ID (video avatar or photo avatar look ID).", "title": "Avatar Id", "type": "string" }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'." }, "engine": { "anyOf": [ { "discriminator": { "mapping": { "avatar_iii": "#/components/schemas/AvatarIIIEngineConfig", "avatar_iv": "#/components/schemas/AvatarIVEngineConfig", "avatar_v": "#/components/schemas/AvatarVEngineConfig" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AvatarVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIVEngineConfig" }, { "$ref": "#/components/schemas/AvatarIIIEngineConfig" } ] }, { "type": "null" } ], "default": null, "description": "Engine configuration for video generation. Pass {\"type\": \"avatar_v\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.", "title": "Engine" } }, "required": [ "type", "avatar_id" ], "title": "CreateBatchVideoFromAvatar", "type": "object" }, "CreateBatchVideoFromCinematicAvatar": { "additionalProperties": false, "description": "Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\n\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\nreference content: one to three avatar looks and optional reference assets\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\nno script or voice \u2014 motion and speech are driven entirely by the prompt and\nthe supplied references. Backed by the Seedance generation pipeline.", "properties": { "type": { "const": "cinematic_avatar", "description": "Must be 'cinematic_avatar' for prompt-and-reference video creation.", "title": "Type", "type": "string" }, "prompt": { "description": "Natural-language prompt describing the video to generate.", "maxLength": 10000, "minLength": 1, "title": "Prompt", "type": "string" }, "avatar_id": { "description": "Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.", "items": { "type": "string" }, "title": "Avatar Id", "type": "array" }, "references": { "anyOf": [ { "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ] }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.", "title": "References" }, "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.", "enum": [ "16:9", "9:16", "1:1" ], "title": "Aspect Ratio", "type": "string" }, "resolution": { "default": "720p", "description": "Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.", "enum": [ "720p", "1080p" ], "title": "Resolution", "type": "string" }, "auto_duration": { "default": false, "description": "Let the model choose the video length. When true, omit duration.", "title": "Auto Duration", "type": "boolean" }, "duration": { "anyOf": [ { "maximum": 15, "minimum": 4, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Video length in seconds (4\u201315). Defaults to 10. Omit when auto_duration is true.", "title": "Duration" }, "enhance_prompt": { "default": false, "description": "Enable server-side prompt enhancement.", "title": "Enhance Prompt", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" } }, "required": [ "type", "prompt", "avatar_id" ], "title": "CreateBatchVideoFromCinematicAvatar", "type": "object" }, "CreateBatchVideoFromImage": { "additionalProperties": false, "description": "Create a video by animating an arbitrary image.\n\nProvide an image via URL, asset ID, or inline base64. The image will be\nanimated with lip-sync to the provided audio or generated speech.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "fit": { "anyOf": [ { "$ref": "#/components/schemas/AvatarFit" }, { "type": "null" } ], "default": null, "description": "How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations." }, "background": { "anyOf": [ { "$ref": "#/components/schemas/BackgroundSetting" }, { "type": "null" } ], "default": null, "description": "Background settings for the video." }, "remove_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Remove the avatar background. Video avatars must be trained with matting enabled.", "title": "Remove Background" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "output_format": { "$ref": "#/components/schemas/VideoOutputFormat", "default": "mp4", "description": "Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically \u2014 the caller does not need to set 'remove_background'." }, "script": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.", "title": "Script" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).", "title": "Voice Id" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script.", "title": "Audio Url" }, "audio_asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.", "title": "Audio Asset Id" }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSettingsInput" }, { "type": "null" } ], "default": null, "description": "Voice tuning parameters (speed, pitch, locale)." }, "type": { "const": "image", "description": "Must be 'image' for image-based video creation.", "title": "Type", "type": "string" }, "image": { "description": "Image to animate. Accepts URL, asset ID, or base64-encoded data.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Image" }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "motion_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Natural-language prompt controlling avatar body motion. Photo avatars only.", "title": "Motion Prompt" }, "expressiveness": { "anyOf": [ { "$ref": "#/components/schemas/Expressiveness" }, { "type": "null" } ], "default": null, "description": "Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted." } }, "required": [ "type", "image" ], "title": "CreateBatchVideoFromImage", "type": "object" }, "CreateBatchVideoFromStudio": { "additionalProperties": false, "description": "Create a single video by composing an ordered list of whole-frame scenes.\n\nThe server owns layout and center-crops each scene to the global output\ncanvas. Output settings are global (one per request); a single video_id is\nreturned and rendering is all-or-nothing. MP4 only in v1 \u2014 the output\ncontainer is fixed and ``output_format`` is not exposed.", "properties": { "type": { "const": "studio", "description": "Must be 'studio' for scene-composition video creation.", "title": "Type", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display title for the video in the HeyGen dashboard.", "title": "Title" }, "aspect_ratio": { "anyOf": [ { "$ref": "#/components/schemas/VideoAspectRatio" }, { "type": "null" } ], "default": "16:9", "description": "Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.", "x-cli-default": "auto", "x-mcp-default": "auto" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/VideoResolution" }, { "type": "null" } ], "default": null, "description": "Global output video resolution. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars." }, "brand_glossary_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.", "title": "Brand Glossary Id" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL to receive a POST notification when the video is ready.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload.", "title": "Callback Id" }, "caption": { "anyOf": [ { "$ref": "#/components/schemas/CaptionSetting" }, { "type": "null" } ], "default": null, "description": "Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video." }, "watermark": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkInput" }, { "type": "null" } ], "default": null, "description": "Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.", "x-cli-visible": false, "x-mcp-visible": false }, "scenes": { "description": "Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.", "items": { "discriminator": { "mapping": { "avatar_video": "#/components/schemas/AvatarVideoScene", "image": "#/components/schemas/ImageScene", "video": "#/components/schemas/VideoScene" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AvatarVideoScene" }, { "$ref": "#/components/schemas/ImageScene" }, { "$ref": "#/components/schemas/VideoScene" } ] }, "title": "Scenes", "type": "array" } }, "required": [ "type", "scenes" ], "title": "CreateBatchVideoFromStudio", "type": "object" }, "CreateVideoBatchResponse": { "properties": { "batch_id": { "description": "Identifier of the created batch. Poll GET /v3/videos/batches/{batch_id} for progress.", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "CreateVideoBatchResponse", "type": "object" }, "VideoBatchDetail": { "properties": { "batch_id": { "description": "Batch identifier.", "title": "Batch Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Batch display name.", "title": "Title" }, "status": { "$ref": "#/components/schemas/BatchStatus", "description": "Aggregate batch status derived from item states." }, "total_items": { "description": "Number of items submitted in this batch.", "title": "Total Items", "type": "integer" }, "counts_by_status": { "additionalProperties": { "type": "integer" }, "description": "Item counts keyed by item status.", "title": "Counts By Status", "type": "object" }, "created_at": { "description": "Batch creation time as a unix timestamp.", "title": "Created At", "type": "integer" }, "items": { "description": "One page of batch items ordered by item_index.", "items": { "$ref": "#/components/schemas/VideoBatchItem" }, "title": "Items", "type": "array" }, "has_more": { "description": "Whether more items exist beyond this page.", "title": "Has More", "type": "boolean" }, "next_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque cursor for the next page of items.", "title": "Next Token" } }, "required": [ "batch_id", "status", "total_items", "counts_by_status", "created_at", "items", "has_more" ], "title": "VideoBatchDetail", "type": "object" }, "BatchItemStatus": { "enum": [ "queued", "processing", "completed", "failed" ], "title": "BatchItemStatus", "type": "string" }, "BatchStatus": { "enum": [ "processing", "completed", "failed" ], "title": "BatchStatus", "type": "string" }, "VideoBatchItem": { "properties": { "item_index": { "description": "Zero-based position of this item in the submitted videos array.", "title": "Item Index", "type": "integer" }, "status": { "$ref": "#/components/schemas/BatchItemStatus", "description": "Item status: queued | processing | completed | failed." }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video id, present once the underlying video has been created.", "title": "Video Id" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Failure details when status is failed.", "title": "Error" } }, "required": [ "item_index", "status" ], "title": "VideoBatchItem", "type": "object" }, "VideoStatusEntry": { "properties": { "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video id. Null for batch items whose video has not been created yet.", "title": "Video Id" }, "status": { "description": "Video status (same values as GET /v1/video_status.get), or not_found for unknown/unowned ids.", "title": "Status", "type": "string" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Failure details when status is failed.", "title": "Error" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set for entries expanded from a batch_id.", "title": "Batch Id" }, "item_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Set for entries expanded from a batch_id, to correlate items without a video_id yet.", "title": "Item Index" } }, "required": [ "status" ], "title": "VideoStatusEntry", "type": "object" }, "CreateVideoTranslationBatchRequest": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name for the batch, shown in the HeyGen app.", "title": "Title" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL invoked once when every item in the batch reaches a terminal state.", "title": "Callback Url" }, "video_translations": { "description": "Video-translation payloads, identical in shape to POST /v3/video-translations. A single entry targeting multiple output_languages expands to one batch item per language; the expanded item count is capped at 100.", "items": { "$ref": "#/components/schemas/CreateVideoTranslationRequest" }, "maxItems": 100, "minItems": 1, "title": "Video Translations", "type": "array" } }, "required": [ "video_translations" ], "title": "CreateVideoTranslationBatchRequest", "type": "object" }, "CreateVideoTranslationBatchResponse": { "properties": { "batch_id": { "description": "Identifier of the created batch. Poll GET /v3/video-translations/batches/{batch_id} for progress.", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "CreateVideoTranslationBatchResponse", "type": "object" }, "CreateLipsyncBatchRequest": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name for the batch, shown in the HeyGen app.", "title": "Title" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Webhook URL invoked once when every item in the batch reaches a terminal state.", "title": "Callback Url" }, "lipsyncs": { "description": "Lipsync payloads, identical in shape to POST /v3/lipsyncs. Each entry becomes exactly one batch item (no expansion); the item count is capped at 100.", "items": { "$ref": "#/components/schemas/CreateLipsyncRequest" }, "maxItems": 100, "minItems": 1, "title": "Lipsyncs", "type": "array" } }, "required": [ "lipsyncs" ], "title": "CreateLipsyncBatchRequest", "type": "object" }, "CreateLipsyncBatchResponse": { "properties": { "batch_id": { "description": "Identifier of the created batch. Poll GET /v3/lipsyncs/batches/{batch_id} for progress.", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "CreateLipsyncBatchResponse", "type": "object" }, "CreateAssetUploadBatchRequest": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name for the batch, shown in the HeyGen app.", "title": "Title" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reserved. Asset completion does not emit a webhook.", "title": "Callback Url" }, "files": { "description": "Files to presign, same shape as POST /v3/assets/direct-uploads. Max 100 per batch.", "items": { "$ref": "#/components/schemas/AssetUploadItem" }, "maxItems": 100, "minItems": 1, "title": "Files", "type": "array" } }, "required": [ "files" ], "title": "CreateAssetUploadBatchRequest", "type": "object" }, "AssetUploadItem": { "additionalProperties": false, "description": "One requested file in a create-upload-batch call.", "properties": { "filename": { "description": "Original filename for reference/metadata. The stored object's extension is derived from content_type.", "title": "Filename", "type": "string" }, "content_type": { "description": "Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf'). Verified against the stored bytes when the batch is completed.", "title": "Content Type", "type": "string" }, "size_bytes": { "description": "Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.", "title": "Size Bytes", "type": "integer" }, "checksum_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.", "title": "Checksum Sha256" } }, "required": [ "filename", "content_type", "size_bytes" ], "title": "AssetUploadItem", "type": "object" }, "CreateAssetUploadBatchResponse": { "properties": { "batch_id": { "description": "Identifier of the created batch. Pass to POST /v3/assets/complete/batches once all files are uploaded.", "title": "Batch Id", "type": "string" }, "items": { "description": "One presigned upload slot per requested file, in the submitted order.", "items": { "$ref": "#/components/schemas/AssetUploadBatchItem" }, "title": "Items", "type": "array" } }, "required": [ "batch_id", "items" ], "title": "CreateAssetUploadBatchResponse", "type": "object" }, "AssetUploadBatchItem": { "description": "One issued presigned upload slot in the create response.", "properties": { "asset_id": { "description": "Reusable asset identifier. Becomes usable after POST /v3/assets/complete/batches finalizes the batch.", "title": "Asset Id", "type": "string" }, "upload_url": { "description": "Presigned S3 URL. PUT the raw file bytes here.", "title": "Upload Url", "type": "string" }, "upload_headers": { "additionalProperties": { "type": "string" }, "description": "Headers that must be sent verbatim on the PUT request.", "title": "Upload Headers", "type": "object" }, "expires_in_seconds": { "description": "Seconds until the upload URL expires.", "title": "Expires In Seconds", "type": "integer" }, "max_bytes": { "description": "Maximum allowed upload size in bytes for this content type: 1.5 GB (1,500,000,000 bytes) per audio file and 200 MiB (209,715,200 bytes) for other supported files.", "title": "Max Bytes", "type": "integer" }, "status": { "const": "pending_upload", "description": "Upload lifecycle status. Always 'pending_upload' here.", "title": "Status", "type": "string" } }, "required": [ "asset_id", "upload_url", "upload_headers", "expires_in_seconds", "max_bytes", "status" ], "title": "AssetUploadBatchItem", "type": "object" }, "CompleteAssetBatchRequest": { "additionalProperties": false, "description": "Finalize every uploaded file in a batch (POST /v3/assets/complete/batches).", "properties": { "batch_id": { "description": "Identifier returned by POST /v3/assets/direct-uploads/batches.", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "CompleteAssetBatchRequest", "type": "object" }, "CompleteAssetBatchResponse": { "properties": { "batch_id": { "description": "Identifier of the batch being finalized. Poll GET /v3/assets/batches/{batch_id} for progress.", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "CompleteAssetBatchResponse", "type": "object" }, "CreatePodcastRequest": { "additionalProperties": false, "description": "Request body for POST /v3/podcasts.", "properties": { "topic": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-text topic / angle / instructions for the conversation. Provide `topic`, `source_files`, or both.", "title": "Topic" }, "source_files": { "description": "Grounding documents (PDF/image/video) the script is built from. Provide each as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}. Provide `topic`, `source_files`, or both.", "items": { "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" } ] }, "maxItems": 5, "title": "Source Files", "type": "array" }, "host_avatar_id": { "description": "Avatar id for the host.", "minLength": 1, "title": "Host Avatar Id", "type": "string" }, "guest_avatar_id": { "description": "Avatar id for the guest.", "minLength": 1, "title": "Guest Avatar Id", "type": "string" }, "host_voice_id": { "description": "Voice id for the host. List voices via GET /v3/voices.", "minLength": 1, "title": "Host Voice Id", "type": "string" }, "guest_voice_id": { "description": "Voice id for the guest. List voices via GET /v3/voices.", "minLength": 1, "title": "Guest Voice Id", "type": "string" }, "layout": { "default": "landscape", "description": "Output aspect ratio: 'landscape' (16:9) or 'portrait' (9:16).", "enum": [ "landscape", "portrait" ], "title": "Layout", "type": "string" }, "duration": { "default": "auto", "description": "Target spoken length. 'auto' lets the generator pick the length.", "enum": [ "auto", "1min", "2min", "3min", "5min" ], "title": "Duration", "type": "string" }, "instructions": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-form scene/studio instructions (e.g. setting, tone). Used verbatim to describe the studio when set.", "title": "Instructions" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional webhook URL. When set, HeyGen POSTs a notification here when the podcast reaches a terminal state (completed or failed), so you don't have to poll GET /v3/podcasts/{podcast_id}.", "title": "Callback Url" }, "callback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Caller-defined identifier echoed back in the webhook payload so you can correlate the callback with this request.", "title": "Callback Id" } }, "required": [ "host_avatar_id", "guest_avatar_id", "host_voice_id", "guest_voice_id" ], "title": "CreatePodcastRequest", "type": "object" }, "PodcastCreateResponse": { "description": "Response for POST /v3/podcasts.", "properties": { "podcast_id": { "description": "Podcast id. Use GET /v3/podcasts/{podcast_id} to poll status.", "title": "Podcast Id", "type": "string" }, "status": { "description": "Status of the created podcast \u2014 'processing' while it generates. Poll GET /v3/podcasts/{podcast_id} for updates.", "enum": [ "processing", "completed", "failed" ], "title": "Status", "type": "string" } }, "required": [ "podcast_id", "status" ], "title": "PodcastCreateResponse", "type": "object" }, "PodcastDetail": { "description": "Response payload for GET /v3/podcasts/{podcast_id} and list items.", "properties": { "podcast_id": { "description": "Unique podcast identifier.", "title": "Podcast Id", "type": "string" }, "status": { "description": "Current status: processing, completed, or failed.", "enum": [ "processing", "completed", "failed" ], "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Generated podcast title. Present once the script is generated.", "title": "Title" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the finished podcast video. Present only when status is 'completed'.", "title": "Video Url" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to the podcast thumbnail. Present only when status is 'completed'.", "title": "Thumbnail Url" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds. Present only when status is 'completed'.", "title": "Duration" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error description. Present only when status is 'failed'.", "title": "Failure Message" }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Unix timestamp (seconds) when the podcast was created.", "title": "Created At" } }, "required": [ "podcast_id", "status" ], "title": "PodcastDetail", "type": "object" }, "PodcastDeleteResponse": { "description": "Response for DELETE /v3/podcasts/{podcast_id} \u2014 an empty object on success.", "properties": {}, "title": "PodcastDeleteResponse", "type": "object" }, "CreateWorkflowRequest": { "additionalProperties": false, "description": "Request body for POST /v3/workflows.", "properties": { "name": { "description": "Human-readable workflow name (unique per space). Creating a workflow with a name that already exists in this space fails with 409 conflict.", "maxLength": 256, "minLength": 1, "title": "Name", "type": "string" }, "product_graph": { "$ref": "#/components/schemas/WorkflowProductGraph", "description": "Complete product graph. Validated and compiled before anything is created; a graph that fails validation returns 422 graph_invalid and creates nothing. On success the graph is published as immutable version 1 and the workflow becomes active." }, "meta": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional caller-supplied metadata stored with the workflow.", "title": "Meta" } }, "required": [ "name", "product_graph" ], "title": "CreateWorkflowRequest", "type": "object" }, "GraphListBinding": { "additionalProperties": false, "description": "Composes a JSON list from nested bindings; valid only for a `json` port.", "properties": { "kind": { "const": "list", "default": "list", "title": "Kind", "type": "string" }, "items": { "description": "List items, each bound independently.", "items": { "discriminator": { "mapping": { "list": "#/components/schemas/GraphListBinding", "literal": "#/components/schemas/GraphLiteralBinding", "node_output": "#/components/schemas/GraphNodeOutputBinding", "object": "#/components/schemas/GraphObjectBinding", "run_input": "#/components/schemas/GraphRunInputBinding" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/GraphLiteralBinding" }, { "$ref": "#/components/schemas/GraphNodeOutputBinding" }, { "$ref": "#/components/schemas/GraphRunInputBinding" }, { "$ref": "#/components/schemas/GraphObjectBinding" }, { "$ref": "#/components/schemas/GraphListBinding" } ] }, "title": "Items", "type": "array" } }, "title": "GraphListBinding", "type": "object" }, "GraphLiteralBinding": { "additionalProperties": false, "description": "Binds an input port to a fixed JSON value authored in the graph.", "properties": { "kind": { "const": "literal", "default": "literal", "title": "Kind", "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue", "default": null, "description": "The literal JSON value bound to the port; type-checked against the port at publish." } }, "title": "GraphLiteralBinding", "type": "object" }, "GraphNodeOutputBinding": { "additionalProperties": false, "description": "Binds an input port to another node's output port.", "properties": { "kind": { "const": "node_output", "default": "node_output", "title": "Kind", "type": "string" }, "node_id": { "description": "Id of the node whose output feeds this port.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Node Id", "type": "string" }, "port": { "description": "Output port name on that node.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Port", "type": "string" } }, "required": [ "node_id", "port" ], "title": "GraphNodeOutputBinding", "type": "object" }, "GraphObjectBinding": { "additionalProperties": false, "description": "Composes a JSON object from nested bindings; valid only for a `json` port.", "properties": { "kind": { "const": "object", "default": "object", "title": "Kind", "type": "string" }, "fields": { "additionalProperties": { "discriminator": { "mapping": { "list": "#/components/schemas/GraphListBinding", "literal": "#/components/schemas/GraphLiteralBinding", "node_output": "#/components/schemas/GraphNodeOutputBinding", "object": "#/components/schemas/GraphObjectBinding", "run_input": "#/components/schemas/GraphRunInputBinding" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/GraphLiteralBinding" }, { "$ref": "#/components/schemas/GraphNodeOutputBinding" }, { "$ref": "#/components/schemas/GraphRunInputBinding" }, { "$ref": "#/components/schemas/GraphObjectBinding" }, { "$ref": "#/components/schemas/GraphListBinding" } ] }, "description": "Object fields, each bound independently.", "title": "Fields", "type": "object" } }, "title": "GraphObjectBinding", "type": "object" }, "GraphRunInputBinding": { "additionalProperties": false, "description": "Binds an input port to a declared workflow input supplied at run start.", "properties": { "kind": { "const": "run_input", "default": "run_input", "title": "Kind", "type": "string" }, "name": { "description": "Name of the declared workflow input.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "GraphRunInputBinding", "type": "object" }, "JsonValue": {}, "WorkflowGraphInputDecl": { "additionalProperties": false, "description": "Declares one workflow input supplied when a run starts.", "properties": { "type": { "$ref": "#/components/schemas/WorkflowValueType", "description": "Type of the value this input carries." }, "required": { "default": true, "description": "Whether every run must supply this input.", "title": "Required", "type": "boolean" } }, "required": [ "type" ], "title": "WorkflowGraphInputDecl", "type": "object" }, "WorkflowGraphNode": { "additionalProperties": false, "description": "One authored node. `type`/`variant` select a node type from the node-type catalog.", "properties": { "id": { "description": "Node id, unique within the graph.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Id", "type": "string" }, "type": { "description": "Node family, as listed by the node-type catalog.", "title": "Type", "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Variant within the family; omit for a single-variant family.", "title": "Variant" }, "config": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "Authored configuration, validated against the node type's config schema.", "title": "Config", "type": "object" }, "depends_on": { "description": "Ids of nodes that must complete before this one, beyond binding-implied edges.", "items": { "type": "string" }, "title": "Depends On", "type": "array" }, "bindings": { "additionalProperties": { "discriminator": { "mapping": { "list": "#/components/schemas/GraphListBinding", "literal": "#/components/schemas/GraphLiteralBinding", "node_output": "#/components/schemas/GraphNodeOutputBinding", "object": "#/components/schemas/GraphObjectBinding", "run_input": "#/components/schemas/GraphRunInputBinding" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/GraphLiteralBinding" }, { "$ref": "#/components/schemas/GraphNodeOutputBinding" }, { "$ref": "#/components/schemas/GraphRunInputBinding" }, { "$ref": "#/components/schemas/GraphObjectBinding" }, { "$ref": "#/components/schemas/GraphListBinding" } ] }, "description": "Where each input port's value comes from, keyed by port name.", "title": "Bindings", "type": "object" } }, "required": [ "id", "type" ], "title": "WorkflowGraphNode", "type": "object" }, "WorkflowGraphOutputDecl": { "additionalProperties": false, "description": "Declares one workflow output: the node output surfaced as a run result.", "properties": { "node_id": { "description": "Id of the node producing this output.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Node Id", "type": "string" }, "port": { "description": "Output port name on that node.", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$", "title": "Port", "type": "string" } }, "required": [ "node_id", "port" ], "title": "WorkflowGraphOutputDecl", "type": "object" }, "WorkflowProductGraph": { "additionalProperties": false, "description": "An authored workflow product graph: nodes, their bindings, and the run-level inputs/outputs.", "properties": { "schema_version": { "description": "Graph schema version; currently \"1.0.0\".", "title": "Schema Version", "type": "string" }, "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowGraphInputDecl" }, "description": "Workflow inputs supplied at run start, keyed by input name.", "title": "Inputs", "type": "object" }, "nodes": { "description": "Nodes in the graph.", "items": { "$ref": "#/components/schemas/WorkflowGraphNode" }, "title": "Nodes", "type": "array" }, "outputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowGraphOutputDecl" }, "description": "Node outputs surfaced as run results, keyed by output name.", "title": "Outputs", "type": "object" } }, "required": [ "schema_version" ], "title": "WorkflowProductGraph", "type": "object" }, "WorkflowValueType": { "description": "Type of a value flowing through a workflow: a run input, a port, or an output.", "enum": [ "text", "json", "video", "image", "audio", "avatar" ], "title": "WorkflowValueType", "type": "string" }, "WorkflowDefinitionResponse": { "description": "Response body for a single workflow definition (mutable draft).", "properties": { "id": { "description": "Workflow definition id (def_\u2026).", "title": "Id", "type": "string" }, "name": { "description": "Workflow name.", "title": "Name", "type": "string" }, "status": { "$ref": "#/components/schemas/WorkflowDefinitionStatus", "description": "Lifecycle status of the workflow definition." }, "draft_revision": { "description": "Monotonic draft revision; supply as expected_revision when updating the draft.", "title": "Draft Revision", "type": "integer" }, "draft_product_graph": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowProductGraphView" }, { "type": "null" } ], "default": null, "description": "Current mutable draft graph, if any." }, "meta": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Caller-supplied metadata stored with the workflow, if any.", "title": "Meta" }, "latest_version": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowVersionRef" }, { "type": "null" } ], "default": null, "description": "The version this request published. Present on POST /v3/workflows responses (the version 1 the create published); omitted on read endpoints." } }, "required": [ "id", "name", "status", "draft_revision" ], "title": "WorkflowDefinitionResponse", "type": "object" }, "WorkflowDefinitionStatus": { "enum": [ "draft", "active", "archived" ], "title": "WorkflowDefinitionStatus", "type": "string" }, "WorkflowProductGraphView": { "additionalProperties": false, "description": "The same graph shape as stored and returned on read surfaces.\n\nA separate schema from the request-side graph so the published contract can describe what a\nstored graph may contain (including node types that are no longer available for new\nauthoring) independently of what a new request may submit.", "properties": { "schema_version": { "description": "Graph schema version; currently \"1.0.0\".", "title": "Schema Version", "type": "string" }, "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowGraphInputDecl" }, "description": "Workflow inputs supplied at run start, keyed by input name.", "title": "Inputs", "type": "object" }, "nodes": { "description": "Nodes in the graph.", "items": { "$ref": "#/components/schemas/WorkflowGraphNode" }, "title": "Nodes", "type": "array" }, "outputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowGraphOutputDecl" }, "description": "Node outputs surfaced as run results, keyed by output name.", "title": "Outputs", "type": "object" } }, "required": [ "schema_version" ], "title": "WorkflowProductGraphView", "type": "object" }, "WorkflowVersionRef": { "description": "Compact reference to a published workflow version.", "properties": { "id": { "description": "Version id (dwv_\u2026).", "title": "Id", "type": "string" }, "version_number": { "description": "Monotonic version number within the workflow.", "title": "Version Number", "type": "integer" } }, "required": [ "id", "version_number" ], "title": "WorkflowVersionRef", "type": "object" }, "WorkflowDefinitionListItem": { "description": "Compact per-item shape for GET /v3/workflows list responses.", "properties": { "id": { "description": "Workflow definition id.", "title": "Id", "type": "string" }, "name": { "description": "Workflow name.", "title": "Name", "type": "string" }, "status": { "$ref": "#/components/schemas/WorkflowDefinitionStatus", "description": "Lifecycle status." }, "draft_revision": { "description": "Current draft revision.", "title": "Draft Revision", "type": "integer" } }, "required": [ "id", "name", "status", "draft_revision" ], "title": "WorkflowDefinitionListItem", "type": "object" }, "UpdateWorkflowDraftRequest": { "additionalProperties": false, "description": "Request body for PATCH /v3/workflows/{workflow_id}.", "properties": { "product_graph": { "$ref": "#/components/schemas/WorkflowProductGraph", "description": "New draft product graph. Structure is validated on submission; graph semantics (node types, bindings, outputs) are validated at publish." }, "expected_revision": { "description": "draft_revision the client last read; the update is rejected (409) if stale.", "minimum": 0, "title": "Expected Revision", "type": "integer" } }, "required": [ "product_graph", "expected_revision" ], "title": "UpdateWorkflowDraftRequest", "type": "object" }, "PublishVersionRequest": { "additionalProperties": false, "description": "Request body for POST /v3/workflows/{workflow_id}/versions.", "properties": { "product_graph": { "$ref": "#/components/schemas/WorkflowProductGraph", "description": "Complete product graph to publish as the next immutable version. The stored draft is not read or modified; a graph identical to the latest published version returns that version (200) instead of creating a new one." } }, "required": [ "product_graph" ], "title": "PublishVersionRequest", "type": "object" }, "WorkflowVersionResponse": { "description": "Response body for a single immutable, compiled workflow version.", "properties": { "id": { "description": "Version id (dwv_\u2026).", "title": "Id", "type": "string" }, "definition_id": { "description": "Parent workflow definition id.", "title": "Definition Id", "type": "string" }, "version_number": { "description": "Monotonic version number within the definition.", "title": "Version Number", "type": "integer" }, "checksum": { "description": "Deterministic checksum of the frozen graph + plan.", "title": "Checksum", "type": "string" }, "compiler_version": { "description": "Compiler version that produced the plan.", "title": "Compiler Version", "type": "string" }, "adapter_manifest_digest": { "description": "Digest of the per-node adapter-version manifest.", "title": "Adapter Manifest Digest", "type": "string" }, "product_graph": { "$ref": "#/components/schemas/WorkflowProductGraphView", "description": "Frozen authored product graph." }, "plan_summary": { "description": "Compact per-node summary of the compiled plan (no internal node dumps).", "items": { "$ref": "#/components/schemas/CompiledNodeSummary" }, "title": "Plan Summary", "type": "array" } }, "required": [ "id", "definition_id", "version_number", "checksum", "compiler_version", "adapter_manifest_digest", "product_graph", "plan_summary" ], "title": "WorkflowVersionResponse", "type": "object" }, "CompiledNodeSummary": { "description": "Compact per-node summary of a compiled execution plan (no internal node dumps).", "properties": { "node_id": { "description": "Node id within the graph.", "title": "Node Id", "type": "string" }, "family": { "description": "Node family, as authored in the product graph.", "title": "Family", "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Variant within the family; null for a single-variant family.", "title": "Variant" }, "contract_version": { "description": "NodeType contract version pinned in the plan.", "title": "Contract Version", "type": "string" }, "adapter_version": { "description": "Adapter version pinned for this node.", "title": "Adapter Version", "type": "string" }, "parents": { "description": "Upstream node ids this node depends on.", "items": { "type": "string" }, "title": "Parents", "type": "array" } }, "required": [ "node_id", "family", "contract_version", "adapter_version" ], "title": "CompiledNodeSummary", "type": "object" }, "WorkflowVersionListItem": { "description": "Compact per-item shape for GET /v3/workflows/{id}/versions list responses.", "properties": { "id": { "description": "Version id.", "title": "Id", "type": "string" }, "version_number": { "description": "Version number.", "title": "Version Number", "type": "integer" }, "checksum": { "description": "Plan checksum.", "title": "Checksum", "type": "string" } }, "required": [ "id", "version_number", "checksum" ], "title": "WorkflowVersionListItem", "type": "object" }, "NodeTypeCatalogResponse": { "description": "Response body for GET /v3/workflows/node-types.", "properties": { "families": { "description": "Node-type families, grouped and sorted by family name. Variants with lifecycle 'available' can be authored in new graphs; 'deprecated' variants are listed only so existing graphs stay readable.", "items": { "$ref": "#/components/schemas/NodeTypeFamilyEntry" }, "title": "Families", "type": "array" } }, "required": [ "families" ], "title": "NodeTypeCatalogResponse", "type": "object" }, "NodeTypeFamilyEntry": { "description": "A node-type family and its listed variants.", "properties": { "family": { "description": "Family identifier, as authored in a product graph node's `type`.", "title": "Family", "type": "string" }, "display_name": { "description": "Human-readable family name.", "title": "Display Name", "type": "string" }, "variants": { "description": "Variants in this family, sorted by variant name (a single-variant family's lone null-variant entry sorts first).", "items": { "$ref": "#/components/schemas/NodeTypeVariantEntry" }, "title": "Variants", "type": "array" } }, "required": [ "family", "display_name", "variants" ], "title": "NodeTypeFamilyEntry", "type": "object" }, "NodeTypeLifecycle": { "description": "Lifecycle of a listed node-type variant.", "enum": [ "available", "deprecated" ], "title": "NodeTypeLifecycle", "type": "string" }, "NodeTypePortEntry": { "description": "A single input or output port on a node-type variant.", "properties": { "name": { "description": "Port name.", "title": "Name", "type": "string" }, "type": { "description": "Port data type.", "title": "Type", "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the port is required. Null for an output port.", "title": "Required" }, "description": { "description": "Human-readable port description.", "title": "Description", "type": "string" } }, "required": [ "name", "type", "description" ], "title": "NodeTypePortEntry", "type": "object" }, "NodeTypeVariantEntry": { "description": "A single listed variant within a node-type family.\n\nDeliberately has no `type_id`/`availability` fields at all \u2014 this DTO is the external\nsurface, which never exposes either. Validating a listing dump against this shape is what\nguarantees no internal key can reach the response, not a dump-time exclusion filter.", "properties": { "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Variant name within the family. Null for a single-variant family.", "title": "Variant" }, "display_name": { "description": "Human-readable variant name.", "title": "Display Name", "type": "string" }, "description": { "description": "Human-readable variant description.", "title": "Description", "type": "string" }, "category": { "description": "UI grouping category.", "title": "Category", "type": "string" }, "config_schema": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "JSON schema describing this variant's config.", "title": "Config Schema", "type": "object" }, "input_ports": { "description": "Input ports this variant accepts.", "items": { "$ref": "#/components/schemas/NodeTypePortEntry" }, "title": "Input Ports", "type": "array" }, "output_ports": { "description": "Output ports this variant produces.", "items": { "$ref": "#/components/schemas/NodeTypePortEntry" }, "title": "Output Ports", "type": "array" }, "contract_version": { "description": "Version of this variant's authoring contract (config schema and ports).", "title": "Contract Version", "type": "string" }, "lifecycle": { "$ref": "#/components/schemas/NodeTypeLifecycle", "description": "Whether this variant can be used in new graphs (available) or is listed only so existing graphs stay readable (deprecated)." } }, "required": [ "variant", "display_name", "description", "category", "config_schema", "input_ports", "output_ports", "contract_version", "lifecycle" ], "title": "NodeTypeVariantEntry", "type": "object" }, "CreateWorkflowRunRequest": { "additionalProperties": false, "description": "Request body for POST /v3/workflow-runs.", "properties": { "workflow_id": { "description": "Workflow to run.", "title": "Workflow Id", "type": "string" }, "version_number": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Published version to run. Omit to run the latest published version, resolved once when the request's Idempotency-Key is first accepted; the response reports the exact version_number the run is pinned to.", "title": "Version Number" }, "inputs": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "Values for the version's declared run inputs. Validated against the frozen plan. Media inputs accept an asset id (a bare string, or {\"type\": \"asset_id\", \"asset_id\": ...}), a publicly accessible HTTPS source ({\"type\": \"url\", \"url\": ...}), or bounded inline content ({\"type\": \"base64\", \"media_type\": ..., \"data\": ...}); URL and inline sources are imported into your asset library before the run executes. Inline content must fit this endpoint's 1 MiB request-body limit.", "title": "Inputs", "type": "object" } }, "required": [ "workflow_id" ], "title": "CreateWorkflowRunRequest", "type": "object" }, "WorkflowRunResponse": { "description": "Response body for a single workflow run: self-contained at terminal state.", "properties": { "id": { "description": "Run id (dwr_\u2026).", "title": "Id", "type": "string" }, "workflow": { "$ref": "#/components/schemas/WorkflowRunWorkflowRef", "description": "Workflow and exact version this run is pinned to." }, "status": { "$ref": "#/components/schemas/PublicWorkflowRunStatus", "description": "Run lifecycle status." }, "created_at": { "description": "When the run was created (UTC).", "format": "date-time", "title": "Created At", "type": "string" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the run started executing (UTC), or null if it has not started.", "title": "Started At" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the run reached a terminal status (UTC), or null if still in progress.", "title": "Completed At" }, "progress": { "$ref": "#/components/schemas/WorkflowRunProgress", "description": "Aggregate node counts." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunError" }, { "type": "null" } ], "default": null, "description": "Terminal error, or null if the run did not fail." }, "outputs": { "description": "Declared top-level outputs of the run's frozen plan.", "items": { "$ref": "#/components/schemas/WorkflowRunOutput" }, "title": "Outputs", "type": "array" } }, "required": [ "id", "workflow", "status", "created_at", "progress" ], "title": "WorkflowRunResponse", "type": "object" }, "PublicWorkflowRunStatus": { "description": "Run lifecycle as published to callers.", "enum": [ "pending", "processing", "succeeded", "partial", "failed", "canceled" ], "title": "PublicWorkflowRunStatus", "type": "string" }, "WorkflowRunError": { "description": "Sanitized terminal error. Codes come from the closed product vocabulary; operator detail\nnever crosses this boundary.", "properties": { "code": { "description": "Stable public error code.", "title": "Code", "type": "string" }, "message": { "description": "Caller-safe explanation of the error.", "title": "Message", "type": "string" }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The failing node, when the failure is attributable to exactly one node.", "title": "Node Id" } }, "required": [ "code", "message" ], "title": "WorkflowRunError", "type": "object" }, "WorkflowRunOutput": { "description": "One declared top-level output of the run's frozen plan.\n\nInline values are bounded: at most 64 KiB per output and 256 KiB across the whole response\n(spent in output-name order); an output past either bound is delivered as a reference instead.", "properties": { "name": { "description": "Output name declared by the workflow version.", "title": "Name", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Output value type (e.g. video, text), once produced.", "title": "Type" }, "status": { "$ref": "#/components/schemas/WorkflowRunOutputStatus", "description": "Whether this output has been produced." }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunOutputDelivery" }, { "type": "null" } ], "default": null, "description": "Shape of a ready output: inline value or read-time URL. Null until ready." }, "artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Durable identity of the produced output, once produced.", "title": "Artifact Id" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ], "default": null, "description": "The output value, for ready inline deliveries." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Read-time URL for a ready reference delivery. Never persisted; mint a fresh one per read. For an inline JSON output delivered as a reference (its value exceeded the inline byte bounds), the URL serves the value itself as a JSON document.", "title": "Url" }, "expires_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seconds until `url` expires. Null when `is_public` is true \u2014 a public URL never expires.", "title": "Expires In" }, "is_public": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when `url` is served from a public bucket, so it is permanent and unauthenticated.", "title": "Is Public" } }, "required": [ "name", "status" ], "title": "WorkflowRunOutput", "type": "object" }, "WorkflowRunOutputDelivery": { "description": "Which shape a READY output takes in this response.\n\n``inline`` carries the value in ``value``; ``reference`` carries a read-time URL. An output\nwhose stored value exceeds the inline byte bounds is delivered as ``reference`` even when it\nwas persisted as inline JSON, so this describes the response, not the storage strategy.", "enum": [ "inline", "reference" ], "title": "WorkflowRunOutputDelivery", "type": "string" }, "WorkflowRunOutputStatus": { "description": "Per-output resolution status, derived from the persisted artifact status.", "enum": [ "pending", "ready", "failed" ], "title": "WorkflowRunOutputStatus", "type": "string" }, "WorkflowRunProgress": { "description": "Aggregate node counts. Counts, never node summaries \u2014 the body must not grow with the graph.", "properties": { "total": { "description": "Total nodes in this run's frozen plan.", "title": "Total", "type": "integer" }, "pending": { "default": 0, "description": "Nodes not yet started.", "title": "Pending", "type": "integer" }, "processing": { "default": 0, "description": "Nodes currently running.", "title": "Processing", "type": "integer" }, "succeeded": { "default": 0, "description": "Nodes that completed successfully.", "title": "Succeeded", "type": "integer" }, "failed": { "default": 0, "description": "Nodes that failed.", "title": "Failed", "type": "integer" }, "skipped": { "default": 0, "description": "Nodes that were skipped.", "title": "Skipped", "type": "integer" }, "canceled": { "default": 0, "description": "Nodes that were canceled.", "title": "Canceled", "type": "integer" } }, "required": [ "total" ], "title": "WorkflowRunProgress", "type": "object" }, "WorkflowRunWorkflowRef": { "description": "The workflow and exact immutable version this run executes against.", "properties": { "id": { "description": "Workflow this run belongs to.", "title": "Id", "type": "string" }, "version_id": { "description": "Immutable version this run is pinned to.", "title": "Version Id", "type": "string" }, "version_number": { "description": "Version number this run is pinned to.", "title": "Version Number", "type": "integer" } }, "required": [ "id", "version_id", "version_number" ], "title": "WorkflowRunWorkflowRef", "type": "object" }, "WorkflowRunListItem": { "description": "Compact per-item shape for GET /v3/workflow-runs list responses.", "properties": { "id": { "description": "Run id.", "title": "Id", "type": "string" }, "version_id": { "description": "Version the run is pinned to.", "title": "Version Id", "type": "string" }, "status": { "$ref": "#/components/schemas/PublicWorkflowRunStatus", "description": "Run lifecycle status." }, "created_at": { "description": "When the run was created (UTC).", "format": "date-time", "title": "Created At", "type": "string" } }, "required": [ "id", "version_id", "status", "created_at" ], "title": "WorkflowRunListItem", "type": "object" }, "WorkflowRunNodeItem": { "description": "Per-node diagnostics for GET /v3/workflow-runs/{run_id}/nodes.", "properties": { "node_id": { "description": "Node id within the workflow graph.", "title": "Node Id", "type": "string" }, "node_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "NodeType id executed for this node.", "title": "Node Type" }, "status": { "$ref": "#/components/schemas/PublicWorkflowNodeStatus", "description": "Node lifecycle status." }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the node started running (UTC), or null if it has not started.", "title": "Started At" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the node reached a terminal status (UTC), or null if still in progress.", "title": "Completed At" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunError" }, { "type": "null" } ], "default": null, "description": "Sanitized node error, or null if the node did not fail." } }, "required": [ "node_id", "status" ], "title": "WorkflowRunNodeItem", "type": "object" }, "PublicWorkflowNodeStatus": { "description": "Node lifecycle as published on the nodes diagnostics route.", "enum": [ "pending", "processing", "succeeded", "failed", "skipped", "canceled" ], "title": "PublicWorkflowNodeStatus", "type": "string" }, "VideoQualityComparisonRequest": { "additionalProperties": false, "description": "One pairwise video comparison.", "properties": { "prompt": { "description": "Prompt used to generate both candidate videos. This provides request context, but scoring is selected by question_id and does not condition on this free-form prompt.", "maxLength": 10000, "minLength": 1, "title": "Prompt", "type": "string" }, "model_a": { "description": "Caller-supplied identifier for the model that generated video A.", "maxLength": 255, "minLength": 1, "title": "Model A", "type": "string" }, "model_b": { "description": "Caller-supplied identifier for the model that generated video B.", "maxLength": 255, "minLength": 1, "title": "Model B", "type": "string" }, "video_a": { "description": "Video A as a public URL, HeyGen asset ID, or base64-encoded video.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Video A" }, "video_b": { "description": "Video B as a public URL, HeyGen asset ID, or base64-encoded video.", "discriminator": { "mapping": { "asset_id": "#/components/schemas/AssetId", "base64": "#/components/schemas/AssetBase64", "url": "#/components/schemas/AssetUrl" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/AssetUrl" }, { "$ref": "#/components/schemas/AssetId" }, { "$ref": "#/components/schemas/AssetBase64" } ], "title": "Video B" }, "question_id": { "$ref": "#/components/schemas/VideoQualityQuestionId", "description": "Question used by the judge. Supported values: engagement, prompt_intent, composition, temporal_consistency, and craft. q1 remains a compatibility alias for engagement." }, "judge_model_version": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Allowlisted dated judge model name. Omit to use the active server-configured version.", "title": "Judge Model Version" } }, "required": [ "prompt", "model_a", "model_b", "video_a", "video_b", "question_id" ], "title": "VideoQualityComparisonRequest", "type": "object" }, "VideoQualityQuestionId": { "description": "Supported C2V judge questions.", "enum": [ "engagement", "prompt_intent", "composition", "temporal_consistency", "craft", "q1" ], "title": "VideoQualityQuestionId", "type": "string" }, "VideoQualityComparisonResponse": { "additionalProperties": false, "description": "A comparison resource returned by synchronous submission or polling.", "properties": { "comparison_id": { "description": "Unique comparison identifier used for polling.", "maxLength": 255, "minLength": 1, "title": "Comparison Id", "type": "string" }, "status": { "$ref": "#/components/schemas/VideoQualityJobStatus", "description": "Current comparison lifecycle state." }, "result": { "anyOf": [ { "$ref": "#/components/schemas/VideoQualityComparisonResult" }, { "type": "null" } ], "default": null, "description": "Judge result, present only when status is completed." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/VideoQualityComparisonError" }, { "type": "null" } ], "default": null, "description": "Terminal failure details, present only when status is failed." } }, "required": [ "comparison_id", "status" ], "title": "VideoQualityComparisonResponse", "type": "object" }, "VideoQualityComparisonError": { "additionalProperties": false, "description": "Terminal per-comparison error returned by polling endpoints.", "properties": { "code": { "description": "Stable machine-readable failure code.", "maxLength": 128, "minLength": 1, "title": "Code", "type": "string" }, "message": { "description": "Human-readable explanation of the comparison failure.", "maxLength": 1000, "minLength": 1, "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "VideoQualityComparisonError", "type": "object" }, "VideoQualityComparisonResult": { "additionalProperties": false, "description": "Completed pairwise judge result.", "properties": { "model_a": { "description": "Caller-supplied identifier for video A's model.", "title": "Model A", "type": "string" }, "model_b": { "description": "Caller-supplied identifier for video B's model.", "title": "Model B", "type": "string" }, "winner": { "description": "Winning caller-supplied model identifier.", "title": "Winner", "type": "string" }, "winner_side": { "description": "Winning candidate side: 'a' or 'b'.", "enum": [ "a", "b" ], "title": "Winner Side", "type": "string" }, "confidence": { "description": "Winning-side probability derived from the pairwise judge.", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "question_id": { "$ref": "#/components/schemas/VideoQualityQuestionId", "description": "Question used for this comparison." }, "judge_model_version": { "description": "Exact judge model version used for this comparison.", "title": "Judge Model Version", "type": "string" } }, "required": [ "model_a", "model_b", "winner", "winner_side", "confidence", "question_id", "judge_model_version" ], "title": "VideoQualityComparisonResult", "type": "object" }, "VideoQualityJobStatus": { "description": "Lifecycle shared by single comparisons and batches.", "enum": [ "processing", "completed", "failed" ], "title": "VideoQualityJobStatus", "type": "string" }, "CreateVideoQualityComparisonBatchRequest": { "additionalProperties": false, "description": "Request body for asynchronous batch submission.", "properties": { "comparisons": { "description": "One to 2000 pairwise comparisons.", "items": { "$ref": "#/components/schemas/VideoQualityComparisonRequest" }, "maxItems": 2000, "minItems": 1, "title": "Comparisons", "type": "array" } }, "required": [ "comparisons" ], "title": "CreateVideoQualityComparisonBatchRequest", "type": "object" }, "CreateVideoQualityComparisonBatchResponse": { "additionalProperties": false, "description": "Accepted asynchronous batch.", "properties": { "batch_id": { "description": "Unique batch identifier used for polling.", "maxLength": 255, "minLength": 1, "title": "Batch Id", "type": "string" }, "status": { "$ref": "#/components/schemas/VideoQualityJobStatus", "description": "Current aggregate batch lifecycle state." }, "total_items": { "description": "Number of comparisons accepted in the batch.", "maximum": 2000, "minimum": 1, "title": "Total Items", "type": "integer" } }, "required": [ "batch_id", "status", "total_items" ], "title": "CreateVideoQualityComparisonBatchResponse", "type": "object" }, "VideoQualityComparisonBatchResponse": { "additionalProperties": false, "description": "Current state and one page of results for an asynchronous batch.", "properties": { "batch_id": { "description": "Unique batch identifier.", "maxLength": 255, "minLength": 1, "title": "Batch Id", "type": "string" }, "status": { "$ref": "#/components/schemas/VideoQualityJobStatus", "description": "Current aggregate batch lifecycle state." }, "total_items": { "description": "Total comparisons in this batch.", "maximum": 2000, "minimum": 1, "title": "Total Items", "type": "integer" }, "counts": { "$ref": "#/components/schemas/VideoQualityComparisonBatchCounts", "description": "Aggregate counts by lifecycle state." }, "items": { "description": "Stable, ordered page of comparison results.", "items": { "$ref": "#/components/schemas/VideoQualityComparisonBatchItem" }, "title": "Items", "type": "array" }, "has_more": { "description": "Whether another page of batch items is available.", "title": "Has More", "type": "boolean" }, "next_token": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque cursor for the next page when has_more is true.", "title": "Next Token" } }, "required": [ "batch_id", "status", "total_items", "counts", "items", "has_more" ], "title": "VideoQualityComparisonBatchResponse", "type": "object" }, "VideoQualityComparisonBatchCounts": { "additionalProperties": false, "description": "Aggregate batch item counts.", "properties": { "processing": { "description": "Number of comparisons still processing.", "minimum": 0, "title": "Processing", "type": "integer" }, "completed": { "description": "Number of successfully completed comparisons.", "minimum": 0, "title": "Completed", "type": "integer" }, "failed": { "description": "Number of terminally failed comparisons.", "minimum": 0, "title": "Failed", "type": "integer" } }, "required": [ "processing", "completed", "failed" ], "title": "VideoQualityComparisonBatchCounts", "type": "object" }, "VideoQualityComparisonBatchItem": { "additionalProperties": false, "description": "One stable, ordered entry in a comparison batch.", "properties": { "item_index": { "description": "Zero-based position of this comparison in the submitted batch.", "minimum": 0, "title": "Item Index", "type": "integer" }, "comparison": { "$ref": "#/components/schemas/VideoQualityComparisonResponse", "description": "Latest state of this comparison." } }, "required": [ "item_index", "comparison" ], "title": "VideoQualityComparisonBatchItem", "type": "object" }, "WordsEndEvent": { "description": "Payload of the terminal `event: end` frame on the SSE word stream.", "properties": { "reason": { "description": "Why the word stream ended. Matches the polling endpoint's `end_reason` where applicable.", "enum": [ "final_marker", "idle_timeout", "error", "completed" ], "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "WordsEndEvent", "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." } }, "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 \u2014 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\u2013255 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" }, "DurableIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required client-supplied key for safely retrying creation. The key is stored with the created resource, so a retry returns the original resource indefinitely \u2014 there is no expiry window. Scope is the space plus the specific workflow version: the same key against a different version is independent. A retry whose body differs from the original returns 409 `conflict`. It is required rather than optional because this request is submitted for execution: when that submission cannot be confirmed the response is a retryable 503, and repeating the request with the same key is what resumes the original run instead of starting a second one. A missing or blank value is rejected with 400. Keys must be 1\u2013255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,255}$", "maxLength": 255, "minLength": 1 }, "example": "550e8400-e29b-41d4-a716-446655440000" } }, "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 } } } } } } } }