From 30c6475737b1f0012042119ab714e7391e637f3e Mon Sep 17 00:00:00 2001 From: heygen-rui-bot Date: Sat, 22 Aug 2026 02:13:32 +0300 Subject: [PATCH] codegen: resync gen/ from EF a8b97e2b --- gen/asset.go | 4 ++-- gen/avatar.go | 2 +- gen/brand.go | 25 ++++++++++++++++++++----- gen/registry.go | 1 + gen/template.go | 2 +- gen/video.go | 16 ++++++++++++++-- 6 files changed, 39 insertions(+), 11 deletions(-) diff --git a/gen/asset.go b/gen/asset.go index dc22666..c8a8470 100644 --- a/gen/asset.go +++ b/gen/asset.go @@ -269,7 +269,7 @@ var AssetGet = &command.Spec{ Name: "get", Summary: "Get Asset", Description: "Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response payload for GET /v3/assets/{asset_id} and items of GET /v3/assets.\",\n \"properties\": {\n \"folder_id\": {\n \"description\": \"Identifier of the folder the asset is stored in. Null if the asset is at the space root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique asset identifier.\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the asset.\",\n \"type\": \"string\"\n },\n \"owner\": {\n \"description\": \"Username of the asset owner.\",\n \"type\": \"string\"\n },\n \"space_id\": {\n \"description\": \"Identifier of the space the asset belongs to.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Asset file type (e.g. 'image', 'video', 'audio', 'font').\",\n \"type\": \"string\"\n },\n \"uploaded_at\": {\n \"description\": \"Unix timestamp (seconds) of when the asset was uploaded.\",\n \"type\": \"integer\"\n },\n \"url\": {\n \"description\": \"Publicly accessible URL for the asset. Null if no URL can be generated.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"type\",\n \"owner\",\n \"space_id\",\n \"uploaded_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response payload for GET /v3/assets/{asset_id} and items of GET /v3/assets.\",\n \"properties\": {\n \"folder_id\": {\n \"description\": \"Identifier of the folder the asset is stored in. Null if the asset is at the space root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique asset identifier.\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the asset — the original filename for API uploads.\",\n \"type\": \"string\"\n },\n \"owner\": {\n \"description\": \"Username of the asset owner.\",\n \"type\": \"string\"\n },\n \"space_id\": {\n \"description\": \"Identifier of the space the asset belongs to.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Asset file type (e.g. 'image', 'video', 'audio', 'font').\",\n \"type\": \"string\"\n },\n \"uploaded_at\": {\n \"description\": \"Unix timestamp (seconds) of when the asset was uploaded.\",\n \"type\": \"integer\"\n },\n \"url\": {\n \"description\": \"Publicly accessible URL for the asset. Null if no URL can be generated.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"type\",\n \"owner\",\n \"space_id\",\n \"uploaded_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/assets/{asset_id}", Method: "GET", BodyEncoding: "", @@ -286,7 +286,7 @@ var AssetList = &command.Spec{ Name: "list", Summary: "List Assets", Description: "**Beta** — 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 — 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.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"Response payload for GET /v3/assets/{asset_id} and items of GET /v3/assets.\",\n \"properties\": {\n \"folder_id\": {\n \"description\": \"Identifier of the folder the asset is stored in. Null if the asset is at the space root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique asset identifier.\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the asset.\",\n \"type\": \"string\"\n },\n \"owner\": {\n \"description\": \"Username of the asset owner.\",\n \"type\": \"string\"\n },\n \"space_id\": {\n \"description\": \"Identifier of the space the asset belongs to.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Asset file type (e.g. 'image', 'video', 'audio', 'font').\",\n \"type\": \"string\"\n },\n \"uploaded_at\": {\n \"description\": \"Unix timestamp (seconds) of when the asset was uploaded.\",\n \"type\": \"integer\"\n },\n \"url\": {\n \"description\": \"Publicly accessible URL for the asset. Null if no URL can be generated.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"type\",\n \"owner\",\n \"space_id\",\n \"uploaded_at\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"has_more\": {\n \"description\": \"Whether more pages are available\",\n \"type\": \"boolean\"\n },\n \"next_token\": {\n \"description\": \"Opaque cursor for the next page\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"Response payload for GET /v3/assets/{asset_id} and items of GET /v3/assets.\",\n \"properties\": {\n \"folder_id\": {\n \"description\": \"Identifier of the folder the asset is stored in. Null if the asset is at the space root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique asset identifier.\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the asset — the original filename for API uploads.\",\n \"type\": \"string\"\n },\n \"owner\": {\n \"description\": \"Username of the asset owner.\",\n \"type\": \"string\"\n },\n \"space_id\": {\n \"description\": \"Identifier of the space the asset belongs to.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Asset file type (e.g. 'image', 'video', 'audio', 'font').\",\n \"type\": \"string\"\n },\n \"uploaded_at\": {\n \"description\": \"Unix timestamp (seconds) of when the asset was uploaded.\",\n \"type\": \"integer\"\n },\n \"url\": {\n \"description\": \"Publicly accessible URL for the asset. Null if no URL can be generated.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"type\",\n \"owner\",\n \"space_id\",\n \"uploaded_at\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"has_more\": {\n \"description\": \"Whether more pages are available\",\n \"type\": \"boolean\"\n },\n \"next_token\": {\n \"description\": \"Opaque cursor for the next page\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/assets", Method: "GET", BodyEncoding: "", diff --git a/gen/avatar.go b/gen/avatar.go index 2fe9673..bc49f08 100644 --- a/gen/avatar.go +++ b/gen/avatar.go @@ -41,7 +41,7 @@ var AvatarCreate = &command.Spec{ Name: "create", 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.", - RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/avatars request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"digital_twin\": \"#/components/schemas/CreateDigitalTwinRequest\",\n \"photo\": \"#/components/schemas/CreatePhotoAvatarRequest\",\n \"prompt\": \"#/components/schemas/CreatePromptAvatarRequest\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Aspect ratio of the generated avatar image, e.g. '16:9', '9:16', '1:1'. 'auto' lets the generation model pick, matching the reference image's ratio when one is provided. Defaults to the model's own choice when omitted.\",\n \"enum\": [\n \"auto\",\n \"16:9\",\n \"9:16\",\n \"1:1\",\n \"4:5\",\n \"5:4\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_group_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Prompt for avatar generation.\",\n \"type\": \"string\"\n },\n \"reference_images\": {\n \"description\": \"Reference images — each as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}. Max 3.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"type\": {\n \"description\": \"Must be 'prompt' for AI-generated avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"prompt\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"avatar_group_id\": {\n \"description\": \"Optional identity you would like to attach the digital twin to. By default it will create a new identity.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"file\": {\n \"description\": \"Footage of the avatar — provide as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'digital_twin' for digital twin avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"file\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"avatar_group_id\": {\n \"description\": \"Optional identity you would like to attach the photo avatar to. By default it will create a new identity.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"file\": {\n \"description\": \"Photo asset of the avatar — provide as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'photo' for photo-based avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"file\"\n ],\n \"type\": \"object\"\n }\n ]\n}", + RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/avatars request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"digital_twin\": \"#/components/schemas/CreateDigitalTwinRequest\",\n \"photo\": \"#/components/schemas/CreatePhotoAvatarRequest\",\n \"prompt\": \"#/components/schemas/CreatePromptAvatarRequest\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"properties\": {\n \"aspect_ratio\": {\n \"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.\",\n \"enum\": [\n \"auto\",\n \"16:9\",\n \"9:16\",\n \"1:1\",\n \"4:5\",\n \"5:4\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_group_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Prompt for avatar generation.\",\n \"type\": \"string\"\n },\n \"reference_images\": {\n \"description\": \"Reference images — each as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}. Max 3.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"type\": {\n \"description\": \"Must be 'prompt' for AI-generated avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"prompt\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"avatar_group_id\": {\n \"description\": \"Optional identity you would like to attach the digital twin to. By default it will create a new identity.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"file\": {\n \"description\": \"Footage of the avatar — provide as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'digital_twin' for digital twin avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"file\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"avatar_group_id\": {\n \"description\": \"Optional identity you would like to attach the photo avatar to. By default it will create a new identity.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"file\": {\n \"description\": \"Photo asset of the avatar — provide as {\\\"type\\\": \\\"url\\\", \\\"url\\\": \\\"https://...\\\"} or {\\\"type\\\": \\\"asset_id\\\", \\\"asset_id\\\": \\\"...\\\"}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"name\": {\n \"description\": \"Name of the avatar.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'photo' for photo-based avatars.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"name\",\n \"file\"\n ],\n \"type\": \"object\"\n }\n ]\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"avatar_group\": {\n \"description\": \"The avatar group.\",\n \"nullable\": true,\n \"properties\": {\n \"consent_status\": {\n \"description\": \"The status of consent for the group. None means consent is not required.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp (seconds) when the avatar was created.\",\n \"type\": \"integer\"\n },\n \"default_voice_id\": {\n \"description\": \"Default voice ID for this avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"error\": {\n \"description\": \"Error details. Only present when status is 'failed'.\",\n \"nullable\": true,\n \"properties\": {\n \"code\": {\n \"description\": \"Machine-readable error code.\",\n \"type\": \"string\"\n },\n \"message\": {\n \"description\": \"Human-readable error description.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"code\",\n \"message\"\n ],\n \"type\": \"object\"\n },\n \"gender\": {\n \"description\": \"Gender of the avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique avatar group identifier.\",\n \"type\": \"string\"\n },\n \"looks_count\": {\n \"description\": \"Number of looks (outfits/styles) available for this avatar.\",\n \"type\": \"integer\"\n },\n \"name\": {\n \"description\": \"Display name of the avatar.\",\n \"type\": \"string\"\n },\n \"preview_image_url\": {\n \"description\": \"URL to the avatar preview image.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"preview_video_url\": {\n \"description\": \"URL to the avatar preview video.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Training status of the avatar group. Only present for private avatars.\",\n \"enum\": [\n \"processing\",\n \"pending_consent\",\n \"failed\",\n \"completed\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"created_at\",\n \"looks_count\"\n ],\n \"type\": \"object\"\n },\n \"avatar_item\": {\n \"description\": \"The avatar item.\",\n \"nullable\": true,\n \"properties\": {\n \"avatar_type\": {\n \"description\": \"Avatar type — determines engine and parameter compatibility.\",\n \"enum\": [\n \"studio_avatar\",\n \"digital_twin\",\n \"photo_avatar\"\n ],\n \"type\": \"string\"\n },\n \"default_voice_id\": {\n \"description\": \"Default voice ID for this look.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"error\": {\n \"description\": \"Error details. Only present when status is 'failed'.\",\n \"nullable\": true,\n \"properties\": {\n \"code\": {\n \"description\": \"Machine-readable error code.\",\n \"type\": \"string\"\n },\n \"message\": {\n \"description\": \"Human-readable error description.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"code\",\n \"message\"\n ],\n \"type\": \"object\"\n },\n \"gender\": {\n \"description\": \"Gender of the avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"group_id\": {\n \"description\": \"ID of the avatar group this look belongs to.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique look identifier. Pass this as avatar_id to POST /v3/videos.\",\n \"type\": \"string\"\n },\n \"image_height\": {\n \"description\": \"Native height of the look in pixels.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"image_width\": {\n \"description\": \"Native width of the look in pixels.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"name\": {\n \"description\": \"Display name of the look.\",\n \"type\": \"string\"\n },\n \"preferred_orientation\": {\n \"description\": \"Preferred orientation of the look: 'portrait', 'landscape', or 'square'.\",\n \"enum\": [\n \"portrait\",\n \"landscape\",\n \"square\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"preview_image_url\": {\n \"description\": \"URL to the look preview image.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"preview_video_url\": {\n \"description\": \"URL to the look preview video.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Training status of the avatar look: 'processing', 'completed', or 'failed'. Only present for private avatars.\",\n \"enum\": [\n \"processing\",\n \"pending_consent\",\n \"failed\",\n \"completed\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"supported_api_engines\": {\n \"description\": \"Engine values this look supports for POST /v3/videos. Possible values: 'avatar_v', 'avatar_iv', 'avatar_iii'.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"tags\": {\n \"description\": \"Tags associated with the look.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"avatar_type\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/avatars", Method: "POST", diff --git a/gen/brand.go b/gen/brand.go index 40b6a34..945a113 100644 --- a/gen/brand.go +++ b/gen/brand.go @@ -9,8 +9,8 @@ var BrandGlossariesCreate = &command.Spec{ Name: "glossaries create", 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` may 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 — a term keeps its original spelling in captions and subtitles. Translation rules are managed in the HeyGen web app and cannot be set here.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/brand-glossaries.\",\n \"properties\": {\n \"name\": {\n \"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.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"default\": [],\n \"description\": \"Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/brand-glossaries.\",\n \"properties\": {\n \"name\": {\n \"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.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"default\": [],\n \"description\": \"Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.\",\n \"items\": {\n \"description\": \"Write-side glossary entry: strict shape enforced on POST / PATCH bodies only.\\n\\nSplit from ``BrandGlossaryTerm`` on purpose. The read projection must round-trip any legacy\\n(term, pronunciation) pair that ``brand_voice.vocabulary`` holds, including blank or padded\\nvalues, so a fresher write-time constraint cannot leak into GET without silently dropping\\nthose rows. Keeping the constraints on a write-only subclass means POST / PATCH reject empty\\nor whitespace-only entries with a 400 while GET behavior is byte-identical to before.\\n\\nSame shape as ``BrandGlossaryTerm`` so ``_vocabulary_from_terms`` and\\n``ensure_brand_glossary_terms_unique`` (which reads ``.term`` off each entry) accept either\\nwithout adaptation.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries", Method: "POST", BodyEncoding: "json", @@ -35,12 +35,27 @@ var BrandGlossariesCreate = &command.Spec{ }, } +var BrandGlossariesDelete = &command.Spec{ + Group: "brand", + Name: "glossaries 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 — the latter managed in the HeyGen web app and not visible here — 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.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for DELETE /v3/brand-glossaries/{brand_glossary_id}.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Identifier of the deleted brand glossary.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", + Method: "DELETE", + BodyEncoding: "", + Destructive: true, + Args: []command.ArgSpec{ + {Name: "brand-glossary-id", Param: "brand_glossary_id", Help: ""}, + }, +} + var BrandGlossariesGet = &command.Spec{ Group: "brand", Name: "glossaries 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 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\nA glossary can also carry translation rules, which control how terms are handled when a video is translated. Those are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", Method: "GET", BodyEncoding: "", @@ -98,8 +113,8 @@ var BrandGlossariesUpdate = &command.Spec{ Name: "glossaries update", 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 `terms` array removes every term. There is no way to add a single term — read the glossary, append to `terms`, and send the whole list back.\n\nRenaming to a name another glossary in your workspace already uses returns 409.\n\nA glossary's translation rules 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.", - RequestSchema: "{\n \"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 the term list. There is no way to add a\\nsingle term — read the glossary, append to `terms`, and send the whole list back.\",\n \"properties\": {\n \"name\": {\n \"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.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"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 the term list. There is no way to add a\\nsingle term — read the glossary, append to `terms`, and send the whole list back.\",\n \"properties\": {\n \"name\": {\n \"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.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.\",\n \"items\": {\n \"description\": \"Write-side glossary entry: strict shape enforced on POST / PATCH bodies only.\\n\\nSplit from ``BrandGlossaryTerm`` on purpose. The read projection must round-trip any legacy\\n(term, pronunciation) pair that ``brand_voice.vocabulary`` holds, including blank or padded\\nvalues, so a fresher write-time constraint cannot leak into GET without silently dropping\\nthose rows. Keeping the constraints on a write-only subclass means POST / PATCH reject empty\\nor whitespace-only entries with a 400 while GET behavior is byte-identical to before.\\n\\nSame shape as ``BrandGlossaryTerm`` so ``_vocabulary_from_terms`` and\\n``ensure_brand_glossary_terms_unique`` (which reads ``.term`` off each entry) accept either\\nwithout adaptation.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", Method: "PATCH", BodyEncoding: "json", diff --git a/gen/registry.go b/gen/registry.go index 1ec371d..e3c7d9c 100644 --- a/gen/registry.go +++ b/gen/registry.go @@ -51,6 +51,7 @@ var Groups = map[string][]*command.Spec{ }, "brand": { BrandGlossariesCreate, + BrandGlossariesDelete, BrandGlossariesGet, BrandGlossariesList, BrandGlossariesUpdate, diff --git a/gen/template.go b/gen/template.go index 580d066..eb9b2e4 100644 --- a/gen/template.go +++ b/gen/template.go @@ -9,7 +9,7 @@ var TemplateGenerate = &command.Spec{ Name: "generate", 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 — 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.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/templates/{template_id}.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Legacy field name for `brand_glossary_id`. Both are accepted and resolve to the same workspace record. Prefer `brand_glossary_id`.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Opaque ID echoed back in webhook events for this video\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"URL called with the video result in addition to registered webhook endpoints\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"default\": false,\n \"description\": \"Whether to burn captions into the video\",\n \"type\": \"boolean\"\n },\n \"dimension\": {\n \"description\": \"Output resolution override. Must match the template's aspect ratio.\",\n \"nullable\": true,\n \"properties\": {\n \"height\": {\n \"description\": \"Output video height in pixels (even number, 128-4096)\",\n \"type\": \"integer\"\n },\n \"width\": {\n \"description\": \"Output video width in pixels (even number, 128-4096)\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"width\",\n \"height\"\n ],\n \"type\": \"object\"\n },\n \"enable_sharing\": {\n \"default\": false,\n \"description\": \"Whether the generated video's share page is publicly accessible\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Folder to place the generated video in\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps\": {\n \"default\": 25,\n \"description\": \"Output frame rate. One of 25, 30, or 60.\",\n \"type\": \"number\"\n },\n \"include_gif\": {\n \"default\": false,\n \"description\": \"Whether to include a GIF preview in the webhook payload\",\n \"type\": \"boolean\"\n },\n \"keep_text_vertically_centered\": {\n \"default\": false,\n \"description\": \"When true, replaced text elements are vertically re-centered based on their rendered height\",\n \"type\": \"boolean\"\n },\n \"reorder_music\": {\n \"default\": true,\n \"description\": \"When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.\",\n \"type\": \"boolean\"\n },\n \"scene_ids\": {\n \"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.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"subtitles\": {\n \"description\": \"Subtitle style settings. Implies captions when provided.\",\n \"nullable\": true,\n \"properties\": {\n \"alignment\": {\n \"default\": 2,\n \"description\": \"Subtitle alignment\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"disable_highlight\": {\n \"default\": false,\n \"description\": \"Override the preset's word-highlight style\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"font_size\": {\n \"description\": \"Font size override for the preset\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"position\": {\n \"description\": \"Subtitle position override\",\n \"nullable\": true,\n \"properties\": {\n \"x\": {\n \"default\": 0,\n \"description\": \"Horizontal subtitle position\",\n \"type\": \"number\"\n },\n \"y\": {\n \"default\": 0,\n \"description\": \"Vertical subtitle position\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"preset_name\": {\n \"description\": \"Subtitle preset name, e.g. 'classic', 'bold', 'bright'\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"preset_name\"\n ],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the generated video\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Template variable replacements, keyed by the variable name defined in the template\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"variables\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/templates/{template_id}.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Legacy field name for `brand_glossary_id`. Both are accepted and resolve to the same workspace record. Prefer `brand_glossary_id`.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Opaque ID echoed back in webhook events for this video\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"URL called with the video result in addition to registered webhook endpoints\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"default\": false,\n \"description\": \"Whether to burn captions into the video\",\n \"type\": \"boolean\"\n },\n \"dimension\": {\n \"description\": \"Output resolution override. Must match the template's aspect ratio.\",\n \"nullable\": true,\n \"properties\": {\n \"height\": {\n \"description\": \"Output video height in pixels (even number, 128-4096)\",\n \"type\": \"integer\"\n },\n \"width\": {\n \"description\": \"Output video width in pixels (even number, 128-4096)\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"width\",\n \"height\"\n ],\n \"type\": \"object\"\n },\n \"enable_sharing\": {\n \"default\": false,\n \"description\": \"Whether the generated video's share page is publicly accessible\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Folder to place the generated video in\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps\": {\n \"default\": 25,\n \"description\": \"Output frame rate. One of 25, 30, or 60.\",\n \"type\": \"number\"\n },\n \"include_gif\": {\n \"default\": false,\n \"description\": \"Whether to include a GIF preview in the webhook payload\",\n \"type\": \"boolean\"\n },\n \"keep_text_vertically_centered\": {\n \"default\": false,\n \"description\": \"When true, replaced text elements are vertically re-centered based on their rendered height\",\n \"type\": \"boolean\"\n },\n \"reorder_music\": {\n \"default\": true,\n \"description\": \"When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.\",\n \"type\": \"boolean\"\n },\n \"scene_ids\": {\n \"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.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"subtitles\": {\n \"description\": \"Subtitle style settings. Implies captions when provided.\",\n \"nullable\": true,\n \"properties\": {\n \"alignment\": {\n \"default\": 2,\n \"description\": \"Subtitle alignment\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"disable_highlight\": {\n \"default\": false,\n \"description\": \"Override the preset's word-highlight style\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"font_size\": {\n \"description\": \"Font size override for the preset\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"position\": {\n \"description\": \"Subtitle position override\",\n \"nullable\": true,\n \"properties\": {\n \"x\": {\n \"default\": 0,\n \"description\": \"Horizontal subtitle position\",\n \"type\": \"number\"\n },\n \"y\": {\n \"default\": 0,\n \"description\": \"Vertical subtitle position\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"preset_name\": {\n \"description\": \"Subtitle preset name, e.g. 'classic', 'bold', 'bright'\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"preset_name\"\n ],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the generated video\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"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.\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"variables\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"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.\",\n \"properties\": {\n \"captioned_video_url\": {\n \"description\": \"Presigned URL to download the video file with captions burned in\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"completed_at\": {\n \"description\": \"Unix timestamp when video generation finished\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"duration\": {\n \"description\": \"Video duration in seconds\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"failure_code\": {\n \"description\": \"Machine-readable failure reason. Only present when status is failed.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"failure_message\": {\n \"description\": \"Human-readable failure description. Only present when status is failed.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"ID of containing folder\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"gif_url\": {\n \"description\": \"URL to animated GIF preview\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique video identifier\",\n \"type\": \"string\"\n },\n \"output_language\": {\n \"description\": \"BCP-47 output language code. Present only for translated videos.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current video status\",\n \"enum\": [\n \"pending\",\n \"processing\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n },\n \"subtitle_url\": {\n \"description\": \"Presigned URL to download the SRT subtitle file\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to video thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Video title\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_page_url\": {\n \"description\": \"URL to the video page in the HeyGen app\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_url\": {\n \"description\": \"Presigned URL to download the video file\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"status\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/templates/{template_id}", Method: "POST", diff --git a/gen/video.go b/gen/video.go index 2e51a0c..a0cd2b4 100644 --- a/gen/video.go +++ b/gen/video.go @@ -9,7 +9,7 @@ var VideoBatchesCreate = &command.Spec{ Name: "batches create", 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.", - RequestSchema: "{\n \"properties\": {\n \"callback_url\": {\n \"description\": \"Webhook URL invoked once when every item in the batch reaches a terminal state.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"videos\": {\n \"description\": \"Video creation requests, identical in shape to POST /v3/videos (avatar / image / cinematic_avatar). Max 100 per batch.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — 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.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"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`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) — 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).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"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.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"videos\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"properties\": {\n \"callback_url\": {\n \"description\": \"Webhook URL invoked once when every item in the batch reaches a terminal state.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"videos\": {\n \"description\": \"Video creation requests (avatar / image / cinematic_avatar). Set folder_id once on the batch request, not on individual videos. Max 100 per batch.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateBatchVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateBatchVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateBatchVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateBatchVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — 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.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"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`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) — 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).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"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.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"videos\"\n ],\n \"type\": \"object\"\n}", Endpoint: "/v3/videos/batches", Method: "POST", BodyEncoding: "json", @@ -30,6 +30,18 @@ var VideoBatchesCreate = &command.Spec{ Source: "body", JSONName: "callback_url", }, + { + Name: "folder-id", + Type: "string", + Default: "", + Help: "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.", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "folder_id", + }, { Name: "title", Type: "string", @@ -94,7 +106,7 @@ var VideoCreate = &command.Spec{ Name: "create", 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.", - RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/videos request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — 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.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"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`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) — 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).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"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.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n}", + RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/videos request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"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.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"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 — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"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 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"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.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"folder_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"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.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — 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.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e 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.\",\n \"properties\": {\n \"type\": {\n \"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.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"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.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"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).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"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`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"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``) — 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).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"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.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"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.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"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.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"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.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Resolved output format for the video.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Initial video status (e.g. 'waiting').\",\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"Unique identifier for the created video.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"video_id\",\n \"status\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/videos", Method: "POST",