diff --git a/gen/folder.go b/gen/folder.go index 93b640e..5076bce 100644 --- a/gen/folder.go +++ b/gen/folder.go @@ -9,8 +9,8 @@ var FolderCreate = &command.Spec{ Name: "create", Summary: "Create Folder", Description: "Creates a folder in the caller's workspace, at the root or inside another folder, and returns it. Pass the returned folder_id as folder_id to POST /v3/videos or POST /v3/video-translations to place the output in it, or as parent_id to this endpoint to nest another folder. Folders and their contents are visible in the HeyGen web app. Sibling folders may share a name; this endpoint never looks up an existing folder by name, so store the ids you receive rather than recreating a tree on retry, and send an Idempotency-Key so a retried request returns the folder the first attempt created. API keys need the videos:write scope; a key scoped only to translations can place translations in a folder but cannot create one.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/folders.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Folder name, 1-256 characters. Sibling folders may share a name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace that is not in the trash.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"mixed\",\n \"description\": \"Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video_translate' is what the Video Translate page creates. The web app lists all three kinds together in its folder views, and every kind accepts videos and translations placed with folder_id on POST /v3/videos and POST /v3/video-translations.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A folder in the caller's workspace.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was created.\",\n \"type\": \"integer\"\n },\n \"creator_username\": {\n \"description\": \"Username of the workspace member who created the folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations, or as parent_id to POST /v3/folders.\",\n \"type\": \"string\"\n },\n \"is_trash\": {\n \"description\": \"Whether the folder is in the trash.\",\n \"type\": \"boolean\"\n },\n \"name\": {\n \"description\": \"Folder name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the containing folder. Absent for a folder at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Kind of folder; see the type field of POST /v3/folders.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\"\n ],\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was last updated.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"folder_id\",\n \"name\",\n \"type\",\n \"is_trash\",\n \"created_at\",\n \"updated_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/folders.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Folder name, 1-256 characters. Sibling folders may share a name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace, of a kind this endpoint creates, that is not in the trash. Assets library folders are flat and cannot hold folders.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"mixed\",\n \"description\": \"Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video_translate' is what the Video Translate page creates. Folders the Assets library creates have kind 'asset'; they cannot be created or nested under here. Every kind is accepted as a folder_id destination on POST /v3/videos, POST /v3/video-translations and the other routes that take one, but the HeyGen app files only assets in an 'asset' folder, so a render placed in one may not appear in the Assets library view.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A folder in the caller's workspace.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was created.\",\n \"type\": \"integer\"\n },\n \"creator_username\": {\n \"description\": \"Username of the workspace member who created the folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations. A folder of type 'mixed', 'video' or 'video_translate' may also be passed as parent_id to POST /v3/folders; 'asset' folders are flat.\",\n \"type\": \"string\"\n },\n \"is_trash\": {\n \"description\": \"Whether the folder is in the trash.\",\n \"type\": \"boolean\"\n },\n \"name\": {\n \"description\": \"Folder name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the containing folder. Absent for a folder at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Kind of folder; see the type field of POST /v3/folders.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\",\n \"asset\"\n ],\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was last updated.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"folder_id\",\n \"name\",\n \"type\",\n \"is_trash\",\n \"created_at\",\n \"updated_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/folders", Method: "POST", BodyEncoding: "json", @@ -46,7 +46,7 @@ var FolderCreate = &command.Spec{ Name: "parent-id", Type: "string", Default: "", - Help: "ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace that is not in the trash.", + Help: "ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace, of a kind this endpoint creates, that is not in the trash. Assets library folders are flat and cannot hold folders.", Required: false, Enum: nil, Min: nil, @@ -58,7 +58,7 @@ var FolderCreate = &command.Spec{ Name: "type", Type: "string", Default: "mixed", - Help: "Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video_translate' is what the Video Translate page creates. The web app lists all three kinds together in its folder views, and every kind accepts videos and translations placed with folder_id on POST /v3/videos and POST /v3/video-translations.", + Help: "Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video_translate' is what the Video Translate page creates. Folders the Assets library creates have kind 'asset'; they cannot be created or nested under here. Every kind is accepted as a folder_id destination on POST /v3/videos, POST /v3/video-translations and the other routes that take one, but the HeyGen app files only assets in an 'asset' folder, so a render placed in one may not appear in the Assets library view.", Required: false, Enum: []string{"mixed", "video", "video_translate"}, Min: nil, @@ -74,7 +74,7 @@ var FolderGet = &command.Spec{ Name: "get", Summary: "Get Folder", Description: "Returns one folder in the caller's workspace, including one that is in the trash (is_trash is true). Use it to confirm a stored folder_id still exists before placing content in it. A folder that was deleted, or that belongs to another workspace, is reported as not found. API keys need the videos:read scope.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A folder in the caller's workspace.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was created.\",\n \"type\": \"integer\"\n },\n \"creator_username\": {\n \"description\": \"Username of the workspace member who created the folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations, or as parent_id to POST /v3/folders.\",\n \"type\": \"string\"\n },\n \"is_trash\": {\n \"description\": \"Whether the folder is in the trash.\",\n \"type\": \"boolean\"\n },\n \"name\": {\n \"description\": \"Folder name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the containing folder. Absent for a folder at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Kind of folder; see the type field of POST /v3/folders.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\"\n ],\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was last updated.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"folder_id\",\n \"name\",\n \"type\",\n \"is_trash\",\n \"created_at\",\n \"updated_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A folder in the caller's workspace.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was created.\",\n \"type\": \"integer\"\n },\n \"creator_username\": {\n \"description\": \"Username of the workspace member who created the folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations. A folder of type 'mixed', 'video' or 'video_translate' may also be passed as parent_id to POST /v3/folders; 'asset' folders are flat.\",\n \"type\": \"string\"\n },\n \"is_trash\": {\n \"description\": \"Whether the folder is in the trash.\",\n \"type\": \"boolean\"\n },\n \"name\": {\n \"description\": \"Folder name.\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"description\": \"ID of the containing folder. Absent for a folder at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Kind of folder; see the type field of POST /v3/folders.\",\n \"enum\": [\n \"mixed\",\n \"video\",\n \"video_translate\",\n \"asset\"\n ],\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp (seconds) when the folder was last updated.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"folder_id\",\n \"name\",\n \"type\",\n \"is_trash\",\n \"created_at\",\n \"updated_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/folders/{folder_id}", Method: "GET", BodyEncoding: "", diff --git a/gen/lipsync.go b/gen/lipsync.go index c653736..b8496b0 100644 --- a/gen/lipsync.go +++ b/gen/lipsync.go @@ -9,7 +9,7 @@ var LipsyncBatchesCreate = &command.Spec{ Name: "batches create", Summary: "Create Lipsync Batch", Description: "Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.", - 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 \"lipsyncs\": {\n \"description\": \"Lipsync payloads, identical in shape to POST /v3/lipsyncs. Each entry becomes exactly one batch item (no expansion); the item count is capped at 100.\",\n \"items\": {\n \"description\": \"Request body for POST /v3/lipsyncs.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode: 'vfr', 'cfr', or 'passthrough'.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"title\": {\n \"description\": \"Title for the lipsync job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"audio\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"lipsyncs\"\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 \"lipsyncs\": {\n \"description\": \"Lipsync payloads, identical in shape to POST /v3/lipsyncs. Each entry becomes exactly one batch item (no expansion); the item count is capped at 100.\",\n \"items\": {\n \"description\": \"Request body for POST /v3/lipsyncs.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode: 'vfr', 'cfr', or 'passthrough'.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"title\": {\n \"description\": \"Title for the lipsync job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"audio\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"lipsyncs\"\n ],\n \"type\": \"object\"\n}", Endpoint: "/v3/lipsyncs/batches", Method: "POST", BodyEncoding: "json", @@ -106,7 +106,7 @@ var LipsyncCreate = &command.Spec{ Name: "create", Summary: "Create Lipsync", Description: "Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/lipsyncs.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode: 'vfr', 'cfr', or 'passthrough'.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"title\": {\n \"description\": \"Title for the lipsync job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"audio\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/lipsyncs.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode: 'vfr', 'cfr', or 'passthrough'.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial lipsync\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"title\": {\n \"description\": \"Title for the lipsync job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"audio\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for POST /v3/lipsyncs.\",\n \"properties\": {\n \"lipsync_id\": {\n \"description\": \"Lipsync ID — use GET /v3/lipsyncs/{id} to poll status\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"lipsync_id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/lipsyncs", Method: "POST", @@ -228,7 +228,7 @@ var LipsyncCreate = &command.Spec{ Name: "folder-id", Type: "string", Default: "", - Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", + Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", Required: false, Enum: nil, Min: nil, diff --git a/gen/model.go b/gen/model.go index b13e8e7..f332333 100644 --- a/gen/model.go +++ b/gen/model.go @@ -262,8 +262,8 @@ var ModelAudioVoicesList = &command.Spec{ var ModelVideosCreate = &command.Spec{ Group: "model", Name: "videos create", - Summary: "Create Instant Video", - Description: "Generate an Instant Video with model `heygen-video-1` from a text prompt, a first-frame image, or reference images, videos, and audio. Select `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Prompts accept at most 5,000 Unicode characters. Duration is 5–15 whole seconds; resolution is 480p or 768p. Image-to-video follows the image proportions and ignores aspect_ratio. Reference-to-video requires at least one image or video, with at most nine images, three videos, three audio recordings, and twelve references total. Reference videos must be within a 1:4–4:1 ratio. Assets accept HTTPS URLs, uploaded asset IDs, or inline base64. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id} for completion and the download URL. Pass an Idempotency-Key header to retry safely; without a key, each submission creates a new generation.", + Summary: "Create HeyGen Video", + Description: "Generate a HeyGen Video with model `heygen-video-1` from a text prompt, a first-frame image, or reference images, videos, and audio. Select `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Prompts accept at most 5,000 Unicode characters. Duration is 5–15 whole seconds; resolution is 480p or 768p. Image-to-video follows the image proportions and ignores aspect_ratio. Reference-to-video requires at least one image or video, with at most nine images, three videos, three audio recordings, and twelve references total. Reference videos must be within a 1:4–4:1 ratio. Assets accept HTTPS URLs, uploaded asset IDs, or inline base64. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id} for completion and the download URL. Pass an Idempotency-Key header to retry safely; without a key, each submission creates a new generation.", RequestSchema: "{\n \"description\": \"Body of POST /v3/models/videos: one schema per generation mode, selected by the required mode field.\",\n \"discriminator\": {\n \"mapping\": {\n \"image_to_video\": \"#/components/schemas/ImageToVideoRequest\",\n \"reference_to_video\": \"#/components/schemas/ReferenceToVideoRequest\",\n \"text_to_video\": \"#/components/schemas/TextToVideoRequest\"\n },\n \"propertyName\": \"mode\"\n },\n \"oneOf\": [\n {\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio for text-to-video. Defaults to 16:9.\",\n \"enum\": [\n \"21:9\",\n \"16:9\",\n \"4:3\",\n \"1:1\",\n \"3:4\",\n \"9:16\"\n ],\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Client tracking ID echoed in the terminal webhook event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"HTTPS webhook URL for the terminal generation event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"default\": 5,\n \"description\": \"Requested video duration in whole seconds, from 5 through 15 inclusive.\",\n \"type\": \"integer\"\n },\n \"mode\": {\n \"description\": \"Generate from the prompt alone.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Required video generation model. Only heygen-video-1 is supported.\",\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Instructions for the video to generate. At most 5,000 Unicode characters.\",\n \"type\": \"string\"\n },\n \"prompt_enhancement\": {\n \"default\": \"turbo\",\n \"description\": \"Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo.\",\n \"enum\": [\n \"turbo\",\n \"quality\",\n \"default\",\n \"disabled\"\n ],\n \"type\": \"string\"\n },\n \"resolution\": {\n \"default\": \"768p\",\n \"description\": \"Output resolution: 480p or 768p. Defaults to 768p.\",\n \"enum\": [\n \"480p\",\n \"768p\"\n ],\n \"type\": \"string\"\n },\n \"seed\": {\n \"description\": \"Generation seed. A random seed is chosen when omitted.\",\n \"nullable\": true,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"model\",\n \"prompt\",\n \"mode\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"The output follows the image proportions, aligned to supported pixel dimensions. Any supplied aspect ratio is ignored.\",\n \"enum\": [\n \"21:9\",\n \"16:9\",\n \"4:3\",\n \"1:1\",\n \"3:4\",\n \"9:16\",\n \"adaptive\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Client tracking ID echoed in the terminal webhook event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"HTTPS webhook URL for the terminal generation event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"default\": 5,\n \"description\": \"Requested video duration in whole seconds, from 5 through 15 inclusive.\",\n \"type\": \"integer\"\n },\n \"image\": {\n \"description\": \"First-frame image.\",\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 \"mode\": {\n \"description\": \"Animate a first-frame image.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Required video generation model. Only heygen-video-1 is supported.\",\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Instructions for the video to generate. At most 5,000 Unicode characters.\",\n \"type\": \"string\"\n },\n \"prompt_enhancement\": {\n \"default\": \"turbo\",\n \"description\": \"Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo.\",\n \"enum\": [\n \"turbo\",\n \"quality\",\n \"default\",\n \"disabled\"\n ],\n \"type\": \"string\"\n },\n \"resolution\": {\n \"default\": \"768p\",\n \"description\": \"Output resolution: 480p or 768p. Defaults to 768p.\",\n \"enum\": [\n \"480p\",\n \"768p\"\n ],\n \"type\": \"string\"\n },\n \"seed\": {\n \"description\": \"Generation seed. A random seed is chosen when omitted.\",\n \"nullable\": true,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"model\",\n \"prompt\",\n \"mode\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"adaptive\",\n \"description\": \"Output aspect ratio. Adaptive uses the first reference image, or the first reference video when no images are supplied. Defaults to adaptive.\",\n \"enum\": [\n \"21:9\",\n \"16:9\",\n \"4:3\",\n \"1:1\",\n \"3:4\",\n \"9:16\",\n \"adaptive\"\n ],\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Client tracking ID echoed in the terminal webhook event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"HTTPS webhook URL for the terminal generation event.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"default\": 5,\n \"description\": \"Requested video duration in whole seconds, from 5 through 15 inclusive.\",\n \"type\": \"integer\"\n },\n \"mode\": {\n \"description\": \"Generate guided by reference images, videos, and audio.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Required video generation model. Only heygen-video-1 is supported.\",\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Instructions for the video to generate. At most 5,000 Unicode characters.\",\n \"type\": \"string\"\n },\n \"prompt_enhancement\": {\n \"default\": \"turbo\",\n \"description\": \"Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo.\",\n \"enum\": [\n \"turbo\",\n \"quality\",\n \"default\",\n \"disabled\"\n ],\n \"type\": \"string\"\n },\n \"reference_audio\": {\n \"description\": \"Reference audio recordings. At most three.\",\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 \"type\": \"array\"\n },\n \"reference_images\": {\n \"description\": \"Reference images. At most nine.\",\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 \"type\": \"array\"\n },\n \"reference_videos\": {\n \"description\": \"Reference videos. At most three.\",\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 \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"768p\",\n \"description\": \"Output resolution: 480p or 768p. Defaults to 768p.\",\n \"enum\": [\n \"480p\",\n \"768p\"\n ],\n \"type\": \"string\"\n },\n \"seed\": {\n \"description\": \"Generation seed. A random seed is chosen when omitted.\",\n \"nullable\": true,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"model\",\n \"prompt\",\n \"mode\"\n ],\n \"type\": \"object\"\n }\n ]\n}", Endpoint: "/v3/models/videos", Method: "POST", @@ -292,8 +292,8 @@ var ModelVideosCreate = &command.Spec{ var ModelVideosGet = &command.Spec{ Group: "model", Name: "videos get", - Summary: "Get Instant Video", - Description: "Get an Instant Video generation in the caller's workspace. Status is pending, processing, completed, failed, or cancelled. Completed results include a fresh video_url, duration, aspect_ratio, dimensions, and seed when available. Failed and cancelled results include failure_code and failure_message. Poll again to refresh an expired download URL. Missing videos and videos from another workspace return the same 404.", + Summary: "Get HeyGen Video", + Description: "Get a HeyGen Video generation in the caller's workspace. Status is pending, processing, completed, failed, or cancelled. Completed results include a fresh video_url, duration, aspect_ratio, dimensions, and seed when available. Failed and cancelled results include failure_code and failure_message. Poll again to refresh an expired download URL. Missing videos and videos from another workspace return the same 404.", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Output aspect ratio. Adaptive outputs report the actual width:height ratio after pixel alignment.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Request creation time as Unix seconds.\",\n \"type\": \"integer\"\n },\n \"duration\": {\n \"description\": \"Generated video duration in seconds, present when completed.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"failure_code\": {\n \"description\": \"Failure code, present when failed or cancelled.\",\n \"enum\": [\n \"generation_failed\",\n \"generation_cancelled\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"failure_message\": {\n \"description\": \"Failure explanation, present when failed or cancelled.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"height\": {\n \"description\": \"Actual output height in pixels, present when reported by the renderer.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"model\": {\n \"description\": \"Requested video generation model.\",\n \"enum\": [\n \"heygen-video-1\"\n ],\n \"type\": \"string\"\n },\n \"seed\": {\n \"description\": \"Generation seed, present when completed.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"status\": {\n \"description\": \"Current generation status.\",\n \"enum\": [\n \"pending\",\n \"processing\",\n \"completed\",\n \"failed\",\n \"cancelled\"\n ],\n \"type\": \"string\"\n },\n \"timings\": {\n \"description\": \"Generation timing in seconds, when reported by the renderer.\",\n \"nullable\": true,\n \"properties\": {\n \"inference\": {\n \"description\": \"Diffusion transformer execution time in seconds. Excludes other inference stages, encoding, and queueing.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"inference\"\n ],\n \"type\": \"object\"\n },\n \"video_id\": {\n \"description\": \"Generated video identifier.\",\n \"type\": \"string\"\n },\n \"video_url\": {\n \"description\": \"Download URL, present when completed. Poll again to obtain a fresh URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"width\": {\n \"description\": \"Actual output width in pixels, present when reported by the renderer.\",\n \"nullable\": true,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"video_id\",\n \"status\",\n \"model\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/models/videos/{video_id}", Method: "GET", diff --git a/gen/registry.go b/gen/registry.go index ee91eae..dfd5aa3 100644 --- a/gen/registry.go +++ b/gen/registry.go @@ -162,7 +162,7 @@ var GroupDescriptions = map[string]string{ "audio": "Search the background-music and sound-effects catalog", "avatar": "List and manage avatars and looks", "brand": "Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations)", - "folder": "Create folders to organize videos and translations in the workspace", + "folder": "Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id", "lipsync": "Dub or replace audio on existing videos", "template": "Generate videos from reusable templates by replacing their variables", "user": "Account information and billing", diff --git a/gen/template.go b/gen/template.go index ef59190..572fe9a 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\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\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}", + 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\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\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", @@ -112,7 +112,7 @@ var TemplateGenerate = &command.Spec{ Name: "folder-id", Type: "string", Default: "", - Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.", + Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.", Required: false, Enum: nil, Min: nil, diff --git a/gen/video-translate.go b/gen/video-translate.go index 9a63821..6b4d500 100644 --- a/gen/video-translate.go +++ b/gen/video-translate.go @@ -9,7 +9,7 @@ var VideoTranslateBatchesCreate = &command.Spec{ Name: "batches create", Summary: "Create Video Translation Batch", Description: "Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.", - 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 \"video_translations\": {\n \"description\": \"Video-translation payloads, identical in shape to POST /v3/video-translations. A single entry targeting multiple output_languages expands to one batch item per language; the expanded item count is capped at 100.\",\n \"items\": {\n \"description\": \"Request body for POST /v3/video-translations.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Custom audio for dubbing — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.\",\n \"enum\": [\n \"vfr\",\n \"cfr\",\n \"passthrough\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"input_language\": {\n \"description\": \"Source language code (auto-detected if omitted)\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Custom subtitle file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"srt_role\": {\n \"description\": \"Which video the subtitle applies to: 'input' (source) or 'output' (translated).\",\n \"enum\": [\n \"input\",\n \"output\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stock_voice_config\": {\n \"description\": \"Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request — contact your HeyGen account team.\",\n \"nullable\": true,\n \"properties\": {\n \"preferred_stock_voice_ids\": {\n \"description\": \"Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"use_stock_voice\": {\n \"default\": false,\n \"description\": \"Set to true to use a preset stock voice instead of cloning the original speaker.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the translation job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"translate_audio_only\": {\n \"default\": false,\n \"description\": \"Only translate audio, keep original video\",\n \"type\": \"boolean\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"video_translations\"\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 \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_translations\": {\n \"description\": \"Video-translation payloads, identical in shape to POST /v3/video-translations. A single entry targeting multiple output_languages expands to one batch item per language; the expanded item count is capped at 100.\",\n \"items\": {\n \"description\": \"Request body for POST /v3/video-translations.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Custom audio for dubbing — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.\",\n \"enum\": [\n \"vfr\",\n \"cfr\",\n \"passthrough\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"input_language\": {\n \"description\": \"Source language code (auto-detected if omitted)\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Custom subtitle file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"srt_role\": {\n \"description\": \"Which video the subtitle applies to: 'input' (source) or 'output' (translated).\",\n \"enum\": [\n \"input\",\n \"output\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stock_voice_config\": {\n \"description\": \"Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request — contact your HeyGen account team.\",\n \"nullable\": true,\n \"properties\": {\n \"preferred_stock_voice_ids\": {\n \"description\": \"Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"use_stock_voice\": {\n \"default\": false,\n \"description\": \"Set to true to use a preset stock voice instead of cloning the original speaker.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the translation job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"translate_audio_only\": {\n \"default\": false,\n \"description\": \"Only translate audio, keep original video\",\n \"type\": \"boolean\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"video_translations\"\n ],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-translations/batches", Method: "POST", BodyEncoding: "json", @@ -106,7 +106,7 @@ var VideoTranslateCreate = &command.Spec{ Name: "create", Summary: "Create Video Translation", Description: "Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/video-translations.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Custom audio for dubbing — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.\",\n \"enum\": [\n \"vfr\",\n \"cfr\",\n \"passthrough\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"input_language\": {\n \"description\": \"Source language code (auto-detected if omitted)\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Custom subtitle file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"srt_role\": {\n \"description\": \"Which video the subtitle applies to: 'input' (source) or 'output' (translated).\",\n \"enum\": [\n \"input\",\n \"output\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stock_voice_config\": {\n \"description\": \"Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request — contact your HeyGen account team.\",\n \"nullable\": true,\n \"properties\": {\n \"preferred_stock_voice_ids\": {\n \"description\": \"Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"use_stock_voice\": {\n \"default\": false,\n \"description\": \"Set to true to use a preset stock voice instead of cloning the original speaker.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the translation job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"translate_audio_only\": {\n \"default\": false,\n \"description\": \"Only translate audio, keep original video\",\n \"type\": \"boolean\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/video-translations.\",\n \"properties\": {\n \"audio\": {\n \"description\": \"Custom audio for dubbing — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_caption\": {\n \"default\": false,\n \"deprecated\": true,\n \"description\": \"Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.\",\n \"type\": \"boolean\"\n },\n \"enable_dynamic_duration\": {\n \"default\": true,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_watermark\": {\n \"default\": false,\n \"description\": \"Add watermark to output\",\n \"type\": \"boolean\"\n },\n \"end_time\": {\n \"description\": \"End time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fps_mode\": {\n \"description\": \"Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.\",\n \"enum\": [\n \"vfr\",\n \"cfr\",\n \"passthrough\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"input_language\": {\n \"description\": \"Source language code (auto-detected if omitted)\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate).\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Custom subtitle file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"srt_role\": {\n \"description\": \"Which video the subtitle applies to: 'input' (source) or 'output' (translated).\",\n \"enum\": [\n \"input\",\n \"output\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"start_time\": {\n \"description\": \"Start time in seconds for partial translation\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stock_voice_config\": {\n \"description\": \"Use a preset stock voice for the translation instead of recreating the original speaker's voice. By default, Video Translation clones the original speaker so the result sounds like them; with this enabled, the translation is spoken by a natural preset voice optimized for clear pronunciation and accent in the target language (the result will not sound like the original speaker). Enterprise feature, available for selected accounts and languages by request — contact your HeyGen account team.\",\n \"nullable\": true,\n \"properties\": {\n \"preferred_stock_voice_ids\": {\n \"description\": \"Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"use_stock_voice\": {\n \"default\": false,\n \"description\": \"Set to true to use a preset stock voice instead of cloning the original speaker.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"title\": {\n \"description\": \"Title for the translation job\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"translate_audio_only\": {\n \"default\": false,\n \"description\": \"Only translate audio, keep original video\",\n \"type\": \"boolean\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for POST /v3/video-translations.\",\n \"properties\": {\n \"video_translation_ids\": {\n \"description\": \"Video translation IDs, one per target language\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"video_translation_ids\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-translations", Method: "POST", @@ -254,7 +254,7 @@ var VideoTranslateCreate = &command.Spec{ Name: "folder-id", Type: "string", Default: "", - Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", + Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", Required: false, Enum: nil, Min: nil, @@ -480,7 +480,7 @@ var VideoTranslateProofreadsCreate = &command.Spec{ Name: "proofreads create", Summary: "Create Proofread Session", Description: "Creates a proofread session that extracts editable subtitles from a video before final rendering.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/video-translations/proofreads.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_video_stretching\": {\n \"default\": false,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"default\": false,\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate)\",\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language codes. Use one for single proofread, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Initial SRT file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"title\": {\n \"description\": \"Title for the proofread job\",\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\",\n \"title\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/video-translations/proofreads.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_voice_id\": {\n \"deprecated\": true,\n \"description\": \"Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"disable_music_track\": {\n \"default\": false,\n \"description\": \"Remove background music\",\n \"type\": \"boolean\"\n },\n \"enable_speech_enhancement\": {\n \"default\": false,\n \"description\": \"Enhance speech quality\",\n \"type\": \"boolean\"\n },\n \"enable_video_stretching\": {\n \"default\": false,\n \"description\": \"Allow dynamic duration adjustment\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"keep_the_same_format\": {\n \"default\": false,\n \"description\": \"Preserve the source video's encoding specs (resolution, bitrate)\",\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"speed\",\n \"description\": \"Translation quality mode: 'speed' (faster) or 'precision' (higher quality)\",\n \"enum\": [\n \"speed\",\n \"precision\"\n ],\n \"type\": \"string\"\n },\n \"output_languages\": {\n \"description\": \"Target language codes. Use one for single proofread, multiple for batch.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"speaker_num\": {\n \"description\": \"Number of speakers (improves speaker separation)\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"srt\": {\n \"description\": \"Initial SRT file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\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 },\n \"title\": {\n \"description\": \"Title for the proofread job\",\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\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 }\n },\n \"required\": [\n \"video\",\n \"output_languages\",\n \"title\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for POST /v3/video-translations/proofreads.\",\n \"properties\": {\n \"proofread_ids\": {\n \"description\": \"Proofread IDs, one per target language\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"status\": {\n \"description\": \"Initial status (always processing)\",\n \"enum\": [\n \"processing\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"proofread_ids\",\n \"status\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-translations/proofreads", Method: "POST", @@ -566,7 +566,7 @@ var VideoTranslateProofreadsCreate = &command.Spec{ Name: "folder-id", Type: "string", Default: "", - Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", + Help: "Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.", Required: false, Enum: nil, Min: nil, diff --git a/gen/video.go b/gen/video.go index 577b517..ff0f698 100644 --- a/gen/video.go +++ b/gen/video.go @@ -118,7 +118,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 \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. 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. Avatar IV and Avatar V render the avatar at up to 1080p: with `4k`, the avatar is composited onto a 4K canvas rather than rendered natively. Native 4K output is available for Avatar III digital twins and studio avatars.\",\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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 or eleven_v4, stability may be any value in [0.0, 1.0].\",\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 \"eleven_v4\"\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",