From 9143fa115b339917dcd24722010183d7dc86f6ac Mon Sep 17 00:00:00 2001 From: heygen-rui-bot Date: Wed, 23 Sep 2026 09:13:41 +0300 Subject: [PATCH] codegen: resync gen/ from EF a29f7e91 --- gen/model.go | 44 ++++++++++++++++-- gen/registry.go | 4 ++ gen/template.go | 111 ++++++++++++++++++++++++++++++++++++++++++++- gen/video-agent.go | 30 ++++++++---- gen/video.go | 8 ++-- gen/voice.go | 6 +-- 6 files changed, 182 insertions(+), 21 deletions(-) diff --git a/gen/model.go b/gen/model.go index 0dee050..0cecfa2 100644 --- a/gen/model.go +++ b/gen/model.go @@ -8,8 +8,8 @@ var ModelAudioTtsCreate = &command.Spec{ Group: "model", Name: "audio tts create", Summary: "Generate Speech", - Description: "Generates speech using the voice identified by `voice_id` and returns a URL for one completed mono PCM16 WAV file at 44.1 kHz. The request remains open until synthesis and output assembly finish. The voice must be an ACTIVE professional voice. Rate limit: 30 requests per minute per workspace member.", - RequestSchema: "{\n \"properties\": {\n \"language\": {\n \"description\": \"Language code used for speech synthesis, such as `en`.\",\n \"type\": \"string\"\n },\n \"seed\": {\n \"description\": \"Optional best-effort deterministic generation seed.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"text\": {\n \"description\": \"Plain text to synthesize. SSML and break tags are not supported.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Identifier of the voice used for speech synthesis.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"text\",\n \"language\"\n ],\n \"type\": \"object\"\n}", + Description: "Generates speech using the voice identified by `voice_id` and returns a URL for one completed mono PCM16 WAV file at 44.1 kHz. The request remains open until synthesis and output assembly finish. The voice must be an ACTIVE HeyGen Voice clone, instant or professional, owned by the caller's workspace; `seed`, `speed`, `pitch_shift` and `pitch_variance` apply to professional clones only. Rate limit: 30 requests per minute per workspace member.", + RequestSchema: "{\n \"properties\": {\n \"language\": {\n \"description\": \"Language code used for speech synthesis, such as `en`.\",\n \"type\": \"string\"\n },\n \"pitch_shift\": {\n \"description\": \"Pitch shift in semitones.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"pitch_variance\": {\n \"description\": \"Pitch variation multiplier; 1.0 preserves the voice default.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"seed\": {\n \"description\": \"Optional best-effort deterministic generation seed.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"speed\": {\n \"description\": \"Speech speed multiplier.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"text\": {\n \"description\": \"Plain text to synthesize. SSML and break tags are not supported.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Identifier of the voice used for speech synthesis.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"text\",\n \"language\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"audio_url\": {\n \"description\": \"URL of the generated audio file.\",\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Duration of the generated audio in seconds.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"audio_url\",\n \"duration\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/models/audio/tts", Method: "POST", @@ -31,6 +31,30 @@ var ModelAudioTtsCreate = &command.Spec{ Source: "body", JSONName: "language", }, + { + Name: "pitch-shift", + Type: "float64", + Default: "", + Help: "Pitch shift in semitones.", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "pitch_shift", + }, + { + Name: "pitch-variance", + Type: "float64", + Default: "", + Help: "Pitch variation multiplier; 1.0 preserves the voice default.", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "pitch_variance", + }, { Name: "seed", Type: "int", @@ -43,6 +67,18 @@ var ModelAudioTtsCreate = &command.Spec{ Source: "body", JSONName: "seed", }, + { + Name: "speed", + Type: "float64", + Default: "", + Help: "Speech speed multiplier.", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "speed", + }, { Name: "text", Type: "string", @@ -170,7 +206,7 @@ var ModelAudioVoicesGet = &command.Spec{ Name: "audio voices get", Summary: "Get an Audio Voice", Description: "Returns one caller-owned model-backed audio voice and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Customer-visible state of one model-backed audio voice.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp in seconds when the voice was created.\",\n \"type\": \"integer\"\n },\n \"failure_reason\": {\n \"description\": \"Stable failure code. Present only when `status` is `FAILED`.\",\n \"enum\": [\n \"INVALID_AUDIO\",\n \"INSUFFICIENT_AUDIO\",\n \"PREPROCESSING_FAILED\",\n \"TRAINING_FAILED\",\n \"ARTIFACT_VALIDATION_FAILED\",\n \"INTERNAL_ERROR\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Primary language code supplied when the voice was created.\",\n \"type\": \"string\"\n },\n \"mode\": {\n \"description\": \"Voice creation mode.\",\n \"enum\": [\n \"professional\"\n ],\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the voice.\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`.\",\n \"enum\": [\n \"PENDING\",\n \"ACTIVE\",\n \"FAILED\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Stable identifier for this voice.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"mode\",\n \"name\",\n \"language\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Customer-visible state of one model-backed audio voice.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp in seconds when the voice was created.\",\n \"type\": \"integer\"\n },\n \"failure_reason\": {\n \"description\": \"Stable failure code. Present only when `status` is `FAILED`.\",\n \"enum\": [\n \"INVALID_AUDIO\",\n \"INSUFFICIENT_AUDIO\",\n \"PREPROCESSING_FAILED\",\n \"TRAINING_FAILED\",\n \"DESIGN_FAILED\",\n \"ARTIFACT_VALIDATION_FAILED\",\n \"INTERNAL_ERROR\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Primary language code supplied when the voice was created.\",\n \"type\": \"string\"\n },\n \"mode\": {\n \"description\": \"Voice creation mode.\",\n \"enum\": [\n \"professional\"\n ],\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the voice.\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`.\",\n \"enum\": [\n \"PENDING\",\n \"ACTIVE\",\n \"FAILED\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Stable identifier for this voice.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"mode\",\n \"name\",\n \"language\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/models/audio/voices/{voice_id}", Method: "GET", BodyEncoding: "", @@ -187,7 +223,7 @@ var ModelAudioVoicesList = &command.Spec{ Name: "audio voices list", Summary: "List Audio Voices", Description: "Returns the model-backed audio voices in the caller's workspace, ordered newest first. Use `limit` and `token` to retrieve additional pages.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"Customer-visible state of one model-backed audio voice.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp in seconds when the voice was created.\",\n \"type\": \"integer\"\n },\n \"failure_reason\": {\n \"description\": \"Stable failure code. Present only when `status` is `FAILED`.\",\n \"enum\": [\n \"INVALID_AUDIO\",\n \"INSUFFICIENT_AUDIO\",\n \"PREPROCESSING_FAILED\",\n \"TRAINING_FAILED\",\n \"ARTIFACT_VALIDATION_FAILED\",\n \"INTERNAL_ERROR\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Primary language code supplied when the voice was created.\",\n \"type\": \"string\"\n },\n \"mode\": {\n \"description\": \"Voice creation mode.\",\n \"enum\": [\n \"professional\"\n ],\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the voice.\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`.\",\n \"enum\": [\n \"PENDING\",\n \"ACTIVE\",\n \"FAILED\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Stable identifier for this voice.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"mode\",\n \"name\",\n \"language\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"has_more\": {\n \"description\": \"Whether more pages are available\",\n \"type\": \"boolean\"\n },\n \"next_token\": {\n \"description\": \"Opaque cursor for the next page\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"Customer-visible state of one model-backed audio voice.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp in seconds when the voice was created.\",\n \"type\": \"integer\"\n },\n \"failure_reason\": {\n \"description\": \"Stable failure code. Present only when `status` is `FAILED`.\",\n \"enum\": [\n \"INVALID_AUDIO\",\n \"INSUFFICIENT_AUDIO\",\n \"PREPROCESSING_FAILED\",\n \"TRAINING_FAILED\",\n \"DESIGN_FAILED\",\n \"ARTIFACT_VALIDATION_FAILED\",\n \"INTERNAL_ERROR\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Primary language code supplied when the voice was created.\",\n \"type\": \"string\"\n },\n \"mode\": {\n \"description\": \"Voice creation mode.\",\n \"enum\": [\n \"professional\"\n ],\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the voice.\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`.\",\n \"enum\": [\n \"PENDING\",\n \"ACTIVE\",\n \"FAILED\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Stable identifier for this voice.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"voice_id\",\n \"mode\",\n \"name\",\n \"language\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"has_more\": {\n \"description\": \"Whether more pages are available\",\n \"type\": \"boolean\"\n },\n \"next_token\": {\n \"description\": \"Opaque cursor for the next page\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/models/audio/voices", Method: "GET", BodyEncoding: "", diff --git a/gen/registry.go b/gen/registry.go index efef05c..2ae3459 100644 --- a/gen/registry.go +++ b/gen/registry.go @@ -85,9 +85,13 @@ var Groups = map[string][]*command.Spec{ ModelAudioVoicesList, }, "template": { + TemplateCreate, + TemplateDelete, TemplateGenerate, TemplateGet, TemplateList, + TemplateUpdate, + TemplateVariablesUpdate, }, "user": { UserMeGet, diff --git a/gen/template.go b/gen/template.go index 135eb70..b0db0fa 100644 --- a/gen/template.go +++ b/gen/template.go @@ -4,6 +4,71 @@ package gen import "github.com/heygen-com/heygen-cli/internal/command" +var TemplateCreate = &command.Spec{ + Group: "template", + Name: "create", + Summary: "Create Template from Video", + Description: "Creates a private template whose scenes, avatars, script and media are copied from one of your videos. The video must carry a draft in the current editor format, which every video generated with POST /v3/videos or saved in the HeyGen editor has; URL-to-Video and older editor videos are refused with template_source_unsupported. The video's render status is not checked. The new template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables or in the HeyGen editor, then generate videos from it with POST /v3/templates/{template_id}. Returns the template detail.", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/templates.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Template name. Defaults to the source video's title.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"video_id\"\n ],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Template detail including its variable schema, scenes, and bindable elements.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Template aspect ratio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"elements\": {\n \"description\": \"Elements a variable can be bound to, in scene order, with their current values and existing bindings\",\n \"items\": {\n \"description\": \"A draft element a variable can be bound to.\",\n \"properties\": {\n \"bindable_as\": {\n \"description\": \"Variable types that can be bound to this element\",\n \"items\": {\n \"enum\": [\n \"text\",\n \"image\",\n \"video\",\n \"audio\",\n \"character\",\n \"voice\"\n ],\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"current\": {\n \"description\": \"The element's current value\",\n \"properties\": {\n \"avatar_look_id\": {\n \"description\": \"Avatar look placed in an avatar element; same IDs as GET /v3/avatars/looks\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"character_type\": {\n \"description\": \"Kind of look the avatar_look_id refers to\",\n \"enum\": [\n \"avatar\",\n \"talking_photo\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"play_style\": {\n \"description\": \"Playback behavior of a video element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"Text content, with any {{placeholders}} unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Media URL of an image, video, or audio element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice used by a script element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Audio volume of a video element, 0.0 to 1.0\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"element_id\": {\n \"description\": \"Element ID, stable for the life of the template\",\n \"type\": \"string\"\n },\n \"element_type\": {\n \"description\": \"Kind of element\",\n \"enum\": [\n \"avatar\",\n \"tts\",\n \"audio\",\n \"background_audio\",\n \"sound_effect\",\n \"text\",\n \"richtext\",\n \"image\",\n \"video\",\n \"background_image\",\n \"background_video\"\n ],\n \"type\": \"string\"\n },\n \"scene_id\": {\n \"description\": \"Scene the element belongs to; null for elements spanning scenes, such as background audio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text_variables\": {\n \"description\": \"Text variable names appearing as {{placeholders}} in this element\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"variable\": {\n \"description\": \"Name of the non-text variable bound to this element, if any\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"element_id\",\n \"element_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Unique template identifier\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Template name\",\n \"type\": \"string\"\n },\n \"scene_ids\": {\n \"description\": \"Scene IDs in template order\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"scenes\": {\n \"description\": \"Scenes defined in the template\",\n \"items\": {\n \"description\": \"A scene defined in the template.\",\n \"properties\": {\n \"scene_id\": {\n \"description\": \"Scene ID, usable in the generate request's scene_ids\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Scene script text, with variable placeholders unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Variables used in this scene\",\n \"items\": {\n \"description\": \"A variable used within a scene.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Variable name, matching a key in the template's variables\",\n \"type\": \"string\"\n },\n \"variable_type\": {\n \"description\": \"Variable type: text, image, video, audio, character, or voice\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\",\n \"variable_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"scene_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"source_video_id\": {\n \"description\": \"Video the template was created from, when known\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to the template thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp of last update\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"variables\": {\n \"description\": \"Variables defined in the template with their current default values, keyed by variable name\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/templates", + Method: "POST", + BodyEncoding: "json", + Flags: []command.FlagSpec{ + { + Name: "idempotency-key", + Type: "string", + Default: "", + Help: "Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "header", + JSONName: "Idempotency-Key", + }, + { + Name: "name", + Type: "string", + Default: "", + Help: "Template name. Defaults to the source video's title.", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "name", + }, + { + Name: "video-id", + Type: "string", + Default: "", + Help: "ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point.", + Required: true, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "video_id", + }, + }, +} + +var TemplateDelete = &command.Spec{ + Group: "template", + Name: "delete", + Summary: "Delete Template", + Description: "Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response body for DELETE /v3/templates/{template_id}.\",\n \"properties\": {\n \"deleted\": {\n \"default\": true,\n \"description\": \"Always true on success\",\n \"type\": \"boolean\"\n },\n \"id\": {\n \"description\": \"ID of the deleted template\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/templates/{template_id}", + Method: "DELETE", + BodyEncoding: "", + Destructive: true, + Args: []command.ArgSpec{ + {Name: "template-id", Param: "template_id", Help: ""}, + }, +} + var TemplateGenerate = &command.Spec{ Group: "template", Name: "generate", @@ -200,7 +265,7 @@ var TemplateGet = &command.Spec{ Name: "get", Summary: "Get Template", Description: "Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Template detail including its variable schema and scenes.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Template aspect ratio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"id\": {\n \"description\": \"Unique template identifier\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Template name\",\n \"type\": \"string\"\n },\n \"scene_ids\": {\n \"description\": \"Scene IDs in template order\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"scenes\": {\n \"description\": \"Scenes defined in the template\",\n \"items\": {\n \"description\": \"A scene defined in the template.\",\n \"properties\": {\n \"scene_id\": {\n \"description\": \"Scene ID, usable in the generate request's scene_ids\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Scene script text, with variable placeholders unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Variables used in this scene\",\n \"items\": {\n \"description\": \"A variable used within a scene.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Variable name, matching a key in the template's variables\",\n \"type\": \"string\"\n },\n \"variable_type\": {\n \"description\": \"Variable type: text, image, video, audio, character, or voice\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\",\n \"variable_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"scene_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to the template thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp of last update\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"variables\": {\n \"description\": \"Variables defined in the template with their current default values, keyed by variable name\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Template detail including its variable schema, scenes, and bindable elements.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Template aspect ratio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"elements\": {\n \"description\": \"Elements a variable can be bound to, in scene order, with their current values and existing bindings\",\n \"items\": {\n \"description\": \"A draft element a variable can be bound to.\",\n \"properties\": {\n \"bindable_as\": {\n \"description\": \"Variable types that can be bound to this element\",\n \"items\": {\n \"enum\": [\n \"text\",\n \"image\",\n \"video\",\n \"audio\",\n \"character\",\n \"voice\"\n ],\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"current\": {\n \"description\": \"The element's current value\",\n \"properties\": {\n \"avatar_look_id\": {\n \"description\": \"Avatar look placed in an avatar element; same IDs as GET /v3/avatars/looks\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"character_type\": {\n \"description\": \"Kind of look the avatar_look_id refers to\",\n \"enum\": [\n \"avatar\",\n \"talking_photo\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"play_style\": {\n \"description\": \"Playback behavior of a video element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"Text content, with any {{placeholders}} unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Media URL of an image, video, or audio element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice used by a script element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Audio volume of a video element, 0.0 to 1.0\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"element_id\": {\n \"description\": \"Element ID, stable for the life of the template\",\n \"type\": \"string\"\n },\n \"element_type\": {\n \"description\": \"Kind of element\",\n \"enum\": [\n \"avatar\",\n \"tts\",\n \"audio\",\n \"background_audio\",\n \"sound_effect\",\n \"text\",\n \"richtext\",\n \"image\",\n \"video\",\n \"background_image\",\n \"background_video\"\n ],\n \"type\": \"string\"\n },\n \"scene_id\": {\n \"description\": \"Scene the element belongs to; null for elements spanning scenes, such as background audio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text_variables\": {\n \"description\": \"Text variable names appearing as {{placeholders}} in this element\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"variable\": {\n \"description\": \"Name of the non-text variable bound to this element, if any\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"element_id\",\n \"element_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Unique template identifier\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Template name\",\n \"type\": \"string\"\n },\n \"scene_ids\": {\n \"description\": \"Scene IDs in template order\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"scenes\": {\n \"description\": \"Scenes defined in the template\",\n \"items\": {\n \"description\": \"A scene defined in the template.\",\n \"properties\": {\n \"scene_id\": {\n \"description\": \"Scene ID, usable in the generate request's scene_ids\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Scene script text, with variable placeholders unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Variables used in this scene\",\n \"items\": {\n \"description\": \"A variable used within a scene.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Variable name, matching a key in the template's variables\",\n \"type\": \"string\"\n },\n \"variable_type\": {\n \"description\": \"Variable type: text, image, video, audio, character, or voice\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\",\n \"variable_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"scene_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"source_video_id\": {\n \"description\": \"Video the template was created from, when known\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to the template thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp of last update\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"variables\": {\n \"description\": \"Variables defined in the template with their current default values, keyed by variable name\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/templates/{template_id}", Method: "GET", BodyEncoding: "", @@ -252,3 +317,47 @@ var TemplateList = &command.Spec{ }, }, } + +var TemplateUpdate = &command.Spec{ + Group: "template", + Name: "update", + Summary: "Update Template", + Description: "Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail.", + RequestSchema: "{\n \"description\": \"Request body for PATCH /v3/templates/{template_id}.\",\n \"properties\": {\n \"name\": {\n \"description\": \"New template name\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Template detail including its variable schema, scenes, and bindable elements.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Template aspect ratio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"elements\": {\n \"description\": \"Elements a variable can be bound to, in scene order, with their current values and existing bindings\",\n \"items\": {\n \"description\": \"A draft element a variable can be bound to.\",\n \"properties\": {\n \"bindable_as\": {\n \"description\": \"Variable types that can be bound to this element\",\n \"items\": {\n \"enum\": [\n \"text\",\n \"image\",\n \"video\",\n \"audio\",\n \"character\",\n \"voice\"\n ],\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"current\": {\n \"description\": \"The element's current value\",\n \"properties\": {\n \"avatar_look_id\": {\n \"description\": \"Avatar look placed in an avatar element; same IDs as GET /v3/avatars/looks\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"character_type\": {\n \"description\": \"Kind of look the avatar_look_id refers to\",\n \"enum\": [\n \"avatar\",\n \"talking_photo\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"play_style\": {\n \"description\": \"Playback behavior of a video element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"Text content, with any {{placeholders}} unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Media URL of an image, video, or audio element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice used by a script element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Audio volume of a video element, 0.0 to 1.0\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"element_id\": {\n \"description\": \"Element ID, stable for the life of the template\",\n \"type\": \"string\"\n },\n \"element_type\": {\n \"description\": \"Kind of element\",\n \"enum\": [\n \"avatar\",\n \"tts\",\n \"audio\",\n \"background_audio\",\n \"sound_effect\",\n \"text\",\n \"richtext\",\n \"image\",\n \"video\",\n \"background_image\",\n \"background_video\"\n ],\n \"type\": \"string\"\n },\n \"scene_id\": {\n \"description\": \"Scene the element belongs to; null for elements spanning scenes, such as background audio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text_variables\": {\n \"description\": \"Text variable names appearing as {{placeholders}} in this element\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"variable\": {\n \"description\": \"Name of the non-text variable bound to this element, if any\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"element_id\",\n \"element_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Unique template identifier\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Template name\",\n \"type\": \"string\"\n },\n \"scene_ids\": {\n \"description\": \"Scene IDs in template order\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"scenes\": {\n \"description\": \"Scenes defined in the template\",\n \"items\": {\n \"description\": \"A scene defined in the template.\",\n \"properties\": {\n \"scene_id\": {\n \"description\": \"Scene ID, usable in the generate request's scene_ids\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Scene script text, with variable placeholders unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Variables used in this scene\",\n \"items\": {\n \"description\": \"A variable used within a scene.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Variable name, matching a key in the template's variables\",\n \"type\": \"string\"\n },\n \"variable_type\": {\n \"description\": \"Variable type: text, image, video, audio, character, or voice\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\",\n \"variable_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"scene_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"source_video_id\": {\n \"description\": \"Video the template was created from, when known\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to the template thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp of last update\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"variables\": {\n \"description\": \"Variables defined in the template with their current default values, keyed by variable name\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/templates/{template_id}", + Method: "PATCH", + BodyEncoding: "json", + Args: []command.ArgSpec{ + {Name: "template-id", Param: "template_id", Help: ""}, + }, + Flags: []command.FlagSpec{ + { + Name: "name", + Type: "string", + Default: "", + Help: "New template name", + Required: true, + Enum: nil, + Min: nil, + Max: nil, + Source: "body", + JSONName: "name", + }, + }, +} + +var TemplateVariablesUpdate = &command.Spec{ + Group: "template", + Name: "variables update", + Summary: "Set Template Variables", + Description: "Declares the complete set of variables for a template, replacing whatever was declared before. This is a full replacement, not a patch: every variable you want to keep must be included in every call, and any variable omitted is removed (text placeholders are restored to their default text). Character, voice, image, video and audio variables bind to an element by element_id; use the elements list from GET /v3/templates/{template_id} to find IDs, and each element takes at most one such variable. Text variables are created with match: every occurrence of that exact text in the template's script and on-screen text (or only in element_ids) becomes a {{name}} placeholder, with the matched text as the default. Declare a text variable without match to keep placeholders that already exist. Returns the updated template detail.", + RequestSchema: "{\n \"description\": \"Request body for PUT /v3/templates/{template_id}/variables.\\n\\nFull replacement: the body is the complete variable set after the call. A variable that\\nexists on the template but is missing here is removed.\",\n \"properties\": {\n \"variables\": {\n \"description\": \"The complete variable set, keyed by variable name (letters, digits, underscores; must start with a letter or underscore; at most 64 characters). An empty object removes every variable.\",\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\": \"Template detail including its variable schema, scenes, and bindable elements.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"Template aspect ratio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"elements\": {\n \"description\": \"Elements a variable can be bound to, in scene order, with their current values and existing bindings\",\n \"items\": {\n \"description\": \"A draft element a variable can be bound to.\",\n \"properties\": {\n \"bindable_as\": {\n \"description\": \"Variable types that can be bound to this element\",\n \"items\": {\n \"enum\": [\n \"text\",\n \"image\",\n \"video\",\n \"audio\",\n \"character\",\n \"voice\"\n ],\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"current\": {\n \"description\": \"The element's current value\",\n \"properties\": {\n \"avatar_look_id\": {\n \"description\": \"Avatar look placed in an avatar element; same IDs as GET /v3/avatars/looks\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"character_type\": {\n \"description\": \"Kind of look the avatar_look_id refers to\",\n \"enum\": [\n \"avatar\",\n \"talking_photo\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"play_style\": {\n \"description\": \"Playback behavior of a video element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"Text content, with any {{placeholders}} unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Media URL of an image, video, or audio element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice used by a script element\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Audio volume of a video element, 0.0 to 1.0\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"element_id\": {\n \"description\": \"Element ID, stable for the life of the template\",\n \"type\": \"string\"\n },\n \"element_type\": {\n \"description\": \"Kind of element\",\n \"enum\": [\n \"avatar\",\n \"tts\",\n \"audio\",\n \"background_audio\",\n \"sound_effect\",\n \"text\",\n \"richtext\",\n \"image\",\n \"video\",\n \"background_image\",\n \"background_video\"\n ],\n \"type\": \"string\"\n },\n \"scene_id\": {\n \"description\": \"Scene the element belongs to; null for elements spanning scenes, such as background audio\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"text_variables\": {\n \"description\": \"Text variable names appearing as {{placeholders}} in this element\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"variable\": {\n \"description\": \"Name of the non-text variable bound to this element, if any\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"element_id\",\n \"element_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Unique template identifier\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Template name\",\n \"type\": \"string\"\n },\n \"scene_ids\": {\n \"description\": \"Scene IDs in template order\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"scenes\": {\n \"description\": \"Scenes defined in the template\",\n \"items\": {\n \"description\": \"A scene defined in the template.\",\n \"properties\": {\n \"scene_id\": {\n \"description\": \"Scene ID, usable in the generate request's scene_ids\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Scene script text, with variable placeholders unreplaced\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"variables\": {\n \"description\": \"Variables used in this scene\",\n \"items\": {\n \"description\": \"A variable used within a scene.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Variable name, matching a key in the template's variables\",\n \"type\": \"string\"\n },\n \"variable_type\": {\n \"description\": \"Variable type: text, image, video, audio, character, or voice\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\",\n \"variable_type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"scene_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"source_video_id\": {\n \"description\": \"Video the template was created from, when known\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"thumbnail_url\": {\n \"description\": \"URL to the template thumbnail image\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Unix timestamp of last update\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"variables\": {\n \"description\": \"Variables defined in the template with their current default values, keyed by variable name\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/templates/{template_id}/variables", + Method: "PUT", + BodyEncoding: "json", + Args: []command.ArgSpec{ + {Name: "template-id", Param: "template_id", Help: ""}, + }, +} diff --git a/gen/video-agent.go b/gen/video-agent.go index 4da1450..775e322 100644 --- a/gen/video-agent.go +++ b/gen/video-agent.go @@ -9,7 +9,7 @@ var VideoAgentCreate = &command.Spec{ Name: "create", Summary: "Create Video Agent Session", Description: "One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes.", - RequestSchema: "{\n \"description\": \"Request body for creating a video from a prompt using Video Agent v3.\\n\\nAll configuration is flat (no nested config object). Files use the\\ntype-discriminated AssetInput union for flexible asset inputs.\\n\\nSupports two modes:\\n- ``generate`` (default): one-shot — auto-proceeds through storyboard, produces one video.\\n- ``chat``: multi-turn — may pause for user input on real decisions (e.g. pick a voice),\\n auto-proceeds on confirmations. Allows revisions and follow-up videos.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"Specific avatar ID to use\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_kit_id\": {\n \"description\": \"Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Optional callback ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion/failure notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"files\": {\n \"description\": \"Optional file attachments (max 20 files)\",\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 \"incognito_mode\": {\n \"default\": false,\n \"description\": \"When enabled, disables memory injection and extraction for this session\",\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"generate\",\n \"description\": \"Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and allows revisions.\",\n \"enum\": [\n \"generate\",\n \"chat\"\n ],\n \"type\": \"string\"\n },\n \"orientation\": {\n \"description\": \"Video orientation. If not provided, auto-detected from content.\",\n \"enum\": [\n \"landscape\",\n \"portrait\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"The message/prompt for video generation (1-10000 characters)\",\n \"type\": \"string\"\n },\n \"style_id\": {\n \"description\": \"Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"visibility\": {\n \"default\": \"team\",\n \"description\": \"Session visibility: private (owner only), team (workspace members), or public (anyone with the link). Defaults to team. Applies to the session and its conversation; does not change existing sessions.\",\n \"enum\": [\n \"private\",\n \"team\",\n \"public\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Specific voice ID to use for narration\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"prompt\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"description\": \"Request body for creating a video from a prompt using Video Agent v3.\\n\\nAll configuration is flat (no nested config object). Files use the\\ntype-discriminated AssetInput union for flexible asset inputs.\\n\\nSupports two modes:\\n- ``generate`` (default): one-shot — auto-proceeds through storyboard, produces one video.\\n- ``chat``: multi-turn — may pause for user input on real decisions (e.g. pick a voice),\\n auto-proceeds on confirmations. Allows follow-up messages, targeted edits, and additional videos.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"Specific avatar ID to use\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_kit_id\": {\n \"description\": \"Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Optional callback ID included in webhook payload\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL for completion/failure notifications\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"files\": {\n \"description\": \"Optional file attachments (max 20 files)\",\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 \"incognito_mode\": {\n \"default\": false,\n \"description\": \"When enabled, disables memory injection and extraction for this session\",\n \"type\": \"boolean\"\n },\n \"mode\": {\n \"default\": \"generate\",\n \"description\": \"Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and accept follow-up messages.\",\n \"enum\": [\n \"generate\",\n \"chat\"\n ],\n \"type\": \"string\"\n },\n \"orientation\": {\n \"description\": \"Video orientation. If not provided, auto-detected from content.\",\n \"enum\": [\n \"landscape\",\n \"portrait\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"The message/prompt for video generation (1-10000 characters)\",\n \"type\": \"string\"\n },\n \"style_id\": {\n \"description\": \"Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"visibility\": {\n \"default\": \"team\",\n \"description\": \"Session visibility: private (owner only), team (workspace members), or public (anyone with the link). Defaults to team. Applies to the session and its conversation; does not change existing sessions.\",\n \"enum\": [\n \"private\",\n \"team\",\n \"public\"\n ],\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Specific voice ID to use for narration\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"prompt\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response from creating a video agent session.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp of session creation\",\n \"type\": \"integer\"\n },\n \"session_id\": {\n \"description\": \"Session ID — primary identifier for this video agent session\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Session status\",\n \"enum\": [\n \"generating\",\n \"thinking\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"Video ID for polling via GET /v3/videos/{video_id}, when available.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"session_id\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-agents", Method: "POST", @@ -96,7 +96,7 @@ var VideoAgentCreate = &command.Spec{ Name: "mode", Type: "string", Default: "generate", - Help: "Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and allows revisions.", + Help: "Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and accept follow-up messages.", Required: false, Enum: []string{"generate", "chat"}, Min: nil, @@ -172,7 +172,7 @@ var VideoAgentGet = &command.Spec{ Name: "get", Summary: "Get Video Agent Session", Description: "Returns the current status, progress, video_id, and recent chat messages for a session.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response from getting a video agent session.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp of session creation\",\n \"type\": \"integer\"\n },\n \"messages\": {\n \"description\": \"Most recent visible messages (max 40, newest-first)\",\n \"items\": {\n \"description\": \"Simplified chat message for external consumers.\",\n \"properties\": {\n \"content\": {\n \"description\": \"Message text content\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of message creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"resource_ids\": {\n \"description\": \"Resource IDs referenced in this message\",\n \"items\": {\n \"type\": \"string\"\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"role\": {\n \"description\": \"Message author: 'user' or 'model'\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Message type: text, resource, or error\",\n \"enum\": [\n \"text\",\n \"resource\",\n \"error\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"role\",\n \"content\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"progress\": {\n \"default\": 0,\n \"description\": \"Progress 0-100\",\n \"type\": \"integer\"\n },\n \"session_id\": {\n \"description\": \"Session ID\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Session status. If a generate session pauses for input before creating its reserved video, the session is waiting_for_input while the reserved video is failed.\",\n \"enum\": [\n \"thinking\",\n \"waiting_for_input\",\n \"reviewing\",\n \"generating\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"LLM-generated session title\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"Video ID once generation starts\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"session_id\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response from getting a video agent session.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp of session creation\",\n \"type\": \"integer\"\n },\n \"error\": {\n \"description\": \"Error details when a failed session has a specific, caller-actionable reason (e.g. a billing paywall). Absent for generic failures with no surfaced reason.\",\n \"nullable\": true,\n \"properties\": {\n \"code\": {\n \"description\": \"Machine-readable error code.\",\n \"type\": \"string\"\n },\n \"message\": {\n \"description\": \"Human-readable error description.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"code\",\n \"message\"\n ],\n \"type\": \"object\"\n },\n \"messages\": {\n \"description\": \"Most recent visible messages (max 40, newest-first)\",\n \"items\": {\n \"description\": \"Simplified chat message for external consumers.\",\n \"properties\": {\n \"content\": {\n \"description\": \"Message text content\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Unix timestamp of message creation\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"resource_ids\": {\n \"description\": \"Resource IDs referenced in this message\",\n \"items\": {\n \"type\": \"string\"\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"role\": {\n \"description\": \"Message author: 'user' or 'model'\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Message type: text, resource, or error\",\n \"enum\": [\n \"text\",\n \"resource\",\n \"error\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"role\",\n \"content\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"progress\": {\n \"default\": 0,\n \"description\": \"Progress 0-100\",\n \"type\": \"integer\"\n },\n \"session_id\": {\n \"description\": \"Session ID\",\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Session status. If a generate session pauses for input before creating its reserved video, the session is waiting_for_input while the reserved video is failed.\",\n \"enum\": [\n \"thinking\",\n \"waiting_for_input\",\n \"reviewing\",\n \"generating\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"LLM-generated session title\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"Video ID once generation starts\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"session_id\",\n \"status\",\n \"created_at\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-agents/{session_id}", Method: "GET", BodyEncoding: "", @@ -246,10 +246,10 @@ var VideoAgentResourcesGet = &command.Spec{ var VideoAgentSend = &command.Spec{ Group: "video-agent", Name: "send", - Summary: "Send Message or Request Revision", - Description: "Sends a follow-up message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode.", - RequestSchema: "{\n \"description\": \"Request body for sending a follow-up message, answering the agent's question,\\nor requesting edits and revisions to a previously generated video.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"Override avatar for this message\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_kit_id\": {\n \"description\": \"Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"files\": {\n \"description\": \"Optional file attachments (max 20 files)\",\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 \"message\": {\n \"description\": \"Text message to the agent\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Override voice for this message\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"message\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response from sending a message to a session.\",\n \"properties\": {\n \"run_id\": {\n \"description\": \"Run ID for this message processing\",\n \"type\": \"string\"\n },\n \"session_id\": {\n \"description\": \"Session ID\",\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"LLM-generated session title\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"session_id\",\n \"run_id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Summary: "Send Video Agent Message", + Description: "Submits a conversational or scene-edit turn to an existing session created in either `generate` or `chat` mode. Follow-up turns preserve the session mode: `generate` continues automatically, while `chat` may pause for user input. Provide `message`, `edit_plan`, or both. Send `message` to answer agent questions, add context, or request conversational changes. For deterministic scene-scoped changes, first call GET /v3/videos/{video_id}/scenes, then include that video's ID as `scene_snapshot_video_id`, its `edit_version`, and a public `scene_id` in each `edit_plan` item. Items may reference different scene snapshots from this session, including earlier videos; none identifies the output draft. The server resolves internal Video Agent resource and storyboard scene IDs; clients must not supply them. The complete edit plan is rejected before submission if any scene is invalid or the draft changed before acceptance. Edits are asynchronous: `edit_version` is not a document lock, so two requests created from the same version may both be accepted. A successful edit turn returns the current working draft in `video_id`; further edits reuse it until rendering starts, then the next edit receives a new draft ID. Poll GET /v3/videos/{video_id} directly for status.", + RequestSchema: "{\n \"anyOf\": [\n {\n \"properties\": {\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"message\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"edit_plan\": {\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"edit_plan\"\n ],\n \"type\": \"object\"\n }\n ],\n \"description\": \"One conversational or scene-edit turn in an existing Video Agent session.\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response from submitting a turn to a session.\",\n \"properties\": {\n \"run_id\": {\n \"description\": \"Run ID for this message processing\",\n \"type\": \"string\"\n },\n \"session_id\": {\n \"description\": \"Session ID\",\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"LLM-generated session title\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video_id\": {\n \"description\": \"Current working draft video ID for an edit turn; poll GET /v3/videos/{video_id} for status\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"session_id\",\n \"run_id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/video-agents/{session_id}", Method: "POST", BodyEncoding: "json", @@ -260,6 +260,18 @@ var VideoAgentSend = &command.Spec{ {Name: "session-id", Param: "session_id", Help: ""}, }, Flags: []command.FlagSpec{ + { + Name: "idempotency-key", + Type: "string", + Default: "", + Help: "Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "header", + JSONName: "Idempotency-Key", + }, { Name: "avatar-id", Type: "string", @@ -288,8 +300,8 @@ var VideoAgentSend = &command.Spec{ Name: "message", Type: "string", Default: "", - Help: "Text message to the agent", - Required: true, + Help: "Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided.", + Required: false, Enum: nil, Min: nil, Max: nil, diff --git a/gen/video.go b/gen/video.go index 94a7b6c..ab3696d 100644 --- a/gen/video.go +++ b/gen/video.go @@ -9,7 +9,7 @@ var VideoBatchesCreate = &command.Spec{ Name: "batches create", Summary: "Create Video Batch", Description: "Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses.", - RequestSchema: "{\n \"properties\": {\n \"callback_url\": {\n \"description\": \"Webhook URL invoked once when every item in the batch reaches a terminal state.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"videos\": {\n \"description\": \"Video creation requests (avatar / image / cinematic_avatar). Set folder_id once on the batch request, not on individual videos. Max 100 per batch.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateBatchVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateBatchVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateBatchVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateBatchVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Create a video from a HeyGen avatar (video or photo avatar).\\n\\nProvide an avatar_id to use a previously created avatar. Supports all\\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\\nserver defaults to Avatar IV.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video by animating an arbitrary image.\\n\\nProvide an image via URL, asset ID, or inline base64. The image will be\\nanimated with lip-sync to the provided audio or generated speech.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\\n\\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\\nreference content: one to three avatar looks and optional reference assets\\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\\nno script or voice — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame still-image scene: either silent (held for ``duration``) or narrated.\\n\\nExactly one mode must be chosen:\\n- silent: set ``duration`` (seconds) and no audio source.\\n- narrated: set exactly one audio source (script + voice_id, audio_url, or\\n audio_asset_id) and omit ``duration`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame scene backed by an existing video clip.\\n\\nOptional ``playback`` exposes the audio volume / mute capability; when\\nomitted the clip plays at its source volume.\\n\\nFor optional voiceover / narration, supply at most one audio source\\n(``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the *same*\\naudio inputs a narrated ``image`` scene accepts. When present, the narration\\ndrives the scene length and ``playback.mode`` controls whether the clip\\nfreezes, loops, or changes speed to fit that duration. When omitted the clip\\nplays full-length as before. The clip's own audio level is still governed by\\n``playback`` (the two compose).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"description\": \"How a narrated clip aligns to the voiceover-driven scene duration. 'freeze' plays once and holds the last frame; 'loop' repeats the clip; 'fit_to_scene' adjusts playback speed to exactly match the scene. Defaults to 'freeze' when omitted. Requires a video-scene voiceover.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"videos\"\n ],\n \"type\": \"object\"\n}", + RequestSchema: "{\n \"properties\": {\n \"callback_url\": {\n \"description\": \"Webhook URL invoked once when every item in the batch reaches a terminal state.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"videos\": {\n \"description\": \"Video creation requests (avatar / image / cinematic_avatar). Set folder_id once on the batch request, not on individual videos. Max 100 per batch.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateBatchVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateBatchVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateBatchVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateBatchVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Create a video from a HeyGen avatar (video or photo avatar).\\n\\nProvide an avatar_id to use a previously created avatar. Supports all\\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\\nserver defaults to Avatar IV.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 \"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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution. 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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"videos\"\n ],\n \"type\": \"object\"\n}", Endpoint: "/v3/videos/batches", Method: "POST", BodyEncoding: "json", @@ -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. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video by animating an arbitrary image.\\n\\nProvide an image via URL, asset ID, or inline base64. The image will be\\nanimated with lip-sync to the provided audio or generated speech.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\\n\\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\\nreference content: one to three avatar looks and optional reference assets\\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\\nno script or voice — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution. 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, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame still-image scene: either silent (held for ``duration``) or narrated.\\n\\nExactly one mode must be chosen:\\n- silent: set ``duration`` (seconds) and no audio source.\\n- narrated: set exactly one audio source (script + voice_id, audio_url, or\\n audio_asset_id) and omit ``duration`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame scene backed by an existing video clip.\\n\\nOptional ``playback`` exposes the audio volume / mute capability; when\\nomitted the clip plays at its source volume.\\n\\nFor optional voiceover / narration, supply at most one audio source\\n(``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the *same*\\naudio inputs a narrated ``image`` scene accepts. When present, the narration\\ndrives the scene length and ``playback.mode`` controls whether the clip\\nfreezes, loops, or changes speed to fit that duration. When omitted the clip\\nplays full-length as before. The clip's own audio level is still governed by\\n``playback`` (the two compose).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"description\": \"How a narrated clip aligns to the voiceover-driven scene duration. 'freeze' plays once and holds the last frame; 'loop' repeats the clip; 'fit_to_scene' adjusts playback speed to exactly match the scene. Defaults to 'freeze' when omitted. Requires a video-scene voiceover.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n}", + RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/videos request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Create a video from a HeyGen avatar (video or photo avatar).\\n\\nProvide an avatar_id to use a previously created avatar. Supports all\\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\\nserver defaults to Avatar IV.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution. 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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution. 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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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", @@ -249,8 +249,8 @@ var VideoScenesGet = &command.Spec{ Group: "video", Name: "scenes get", Summary: "Get Video Scenes", - Description: "Returns the video's scenes together with the video-level context needed to use them. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated.\n\nEach scene splits by the role a thing plays: `background` fills the frame, `elements` are placed within it, and `script` is the audio delivered over it. A whole-frame image or clip lands in `background`, so code that reads only `elements` misses it.\n\nElement types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in `elements`, so the count is always truthful, but only `avatar`, `image` and `video` are described in full; `group` and `mask` carry their children; the rest carry an `id` and a `type` and nothing more.\n\n**What this does not describe.** A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which this version does not return.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"The composite document: one video's context and every one of its scenes.\",\n \"properties\": {\n \"scenes\": {\n \"description\": \"Every scene in the video, in the video's own order, which is playback order unless the video branches. Never paginated.\",\n \"items\": {\n \"description\": \"One scene, in the video's own order.\\n\\nThat is playback order for a linear video, which is the ordinary case. A branching video plays as\\na walk over branch targets instead, so its scenes are still all here and still ordered, but the\\norder is not the sequence a viewer sees. Branching is not otherwise described by this version.\\n\\nThe three content fields split by the role a thing plays rather than by its kind:\\n``background`` fills the frame, ``elements`` are placed within it, ``script`` carries\\nthe speech delivered over it. The background is visual too, so ``elements`` means \\\"the\\nones the scene places\\\", not \\\"the visual ones\\\".\",\n \"properties\": {\n \"background\": {\n \"description\": \"What fills the frame behind this scene's elements.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/ColorBackground\",\n \"image\": \"#/components/schemas/ImageBackground\",\n \"video\": \"#/components/schemas/VideoBackground\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"A solid colour filling the frame behind the scene's elements.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Hex colour, e.g. '#f6f6fc'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"color\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"color\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame image.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame video clip.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene. Same values as a video element's playback.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"elements\": {\n \"description\": \"Every element this scene places, in the video's own order.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"An avatar performing the scene's speech.\\n\\nCarries what a v3 create request can set per avatar, so what is read back here is what can be\\nsent back. Fields are added as callers need them, and a new one is not a breaking change.\\n\\nOutput resolution is a whole-video setting, reported on the video rather than per avatar.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"The avatar look performing this scene.\",\n \"type\": \"string\"\n },\n \"engine\": {\n \"description\": \"Generation engine for this avatar. Absent when the video does not record one and none can be determined.\",\n \"enum\": [\n \"avatar_v\",\n \"avatar_iv\",\n \"avatar_iii\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"expressiveness\": {\n \"description\": \"Expressiveness level. Absent when left at the default.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Motion description authored for this avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"avatar\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An image placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed; the element is still reported either way, so an image with no URL is one this read could not link to rather than an element this API does not describe. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A video clip placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene: 'freeze' holds the last frame, 'loop' repeats it, 'fit_to_scene' changes speed to match, 'full_video' plays it whole and drives the scene's length.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element this version names but does not describe.\\n\\nExists so a scene's ``elements`` array is never a filtered view presented as a complete one: a\\ncaller iterating it sees every element the scene places. Carries exactly two fields: which\\nelement this is, and what kind of thing it is.\\n\\n**Absence of content is not by itself proof that an element is undescribed.** A described\\ncategory can serialize with nothing but an id and a type when every optional field happens to be\\nunavailable, and one case is reachable today: an image with no usable link carries no ``url``,\\nleaving ``{id, type}``. Read the ``type`` to tell them apart.\\n``avatar``, ``image`` and ``video`` are described, so a bare one of those is a described element\\nmissing an optional value rather than an unexpanded node.\\n\\nThe ``id`` matters most here. Two masked elements in one scene are otherwise identical on the\\nwire, so without it a caller can see that the scene places two things and nothing else about\\neither.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The element's category. An **open set**: new values may be added, so treat an unrecognized one as an element to skip rather than an error. Several kinds of element can share one value, so a category says what an element is rather than naming a single underlying kind. Every value is permanent except 'other', which means 'a kind of element this API does not yet categorise' and may be replaced by a more specific category later.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element that holds other elements: a group, or a mask.\\n\\nA scene lists the container, not its contents, so a scene holding one group of five images\\nlists a single element while five things render. Walking a scene's composition means recursing\\ninto ``children``.\\n\\nA mask matters more here than a group: a group conveys linkage this response does not express,\\nwhile a mask conveys clipping, so treating a masked image as a plain image asserts a\\ncomposition that renders differently in kind.\",\n \"properties\": {\n \"children\": {\n \"description\": \"The elements this container holds, each described exactly as a top-level element would be.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"An avatar performing the scene's speech.\\n\\nCarries what a v3 create request can set per avatar, so what is read back here is what can be\\nsent back. Fields are added as callers need them, and a new one is not a breaking change.\\n\\nOutput resolution is a whole-video setting, reported on the video rather than per avatar.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"The avatar look performing this scene.\",\n \"type\": \"string\"\n },\n \"engine\": {\n \"description\": \"Generation engine for this avatar. Absent when the video does not record one and none can be determined.\",\n \"enum\": [\n \"avatar_v\",\n \"avatar_iv\",\n \"avatar_iii\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"expressiveness\": {\n \"description\": \"Expressiveness level. Absent when left at the default.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Motion description authored for this avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"avatar\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An image placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed; the element is still reported either way, so an image with no URL is one this read could not link to rather than an element this API does not describe. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A video clip placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene: 'freeze' holds the last frame, 'loop' repeats it, 'fit_to_scene' changes speed to match, 'full_video' plays it whole and drives the scene's length.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element this version names but does not describe.\\n\\nExists so a scene's ``elements`` array is never a filtered view presented as a complete one: a\\ncaller iterating it sees every element the scene places. Carries exactly two fields: which\\nelement this is, and what kind of thing it is.\\n\\n**Absence of content is not by itself proof that an element is undescribed.** A described\\ncategory can serialize with nothing but an id and a type when every optional field happens to be\\nunavailable, and one case is reachable today: an image with no usable link carries no ``url``,\\nleaving ``{id, type}``. Read the ``type`` to tell them apart.\\n``avatar``, ``image`` and ``video`` are described, so a bare one of those is a described element\\nmissing an optional value rather than an unexpanded node.\\n\\nThe ``id`` matters most here. Two masked elements in one scene are otherwise identical on the\\nwire, so without it a caller can see that the scene places two things and nothing else about\\neither.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The element's category. An **open set**: new values may be added, so treat an unrecognized one as an element to skip rather than an error. Several kinds of element can share one value, so a category says what an element is rather than naming a single underlying kind. Every value is permanent except 'other', which means 'a kind of element this API does not yet categorise' and may be replaced by a more specific category later.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Circular reference to ContainerElement\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The container's category, e.g. 'group' or 'mask'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Identifier of this scene within the video.\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"This scene's audio sources in order, each one synthesized speech, uploaded audio, or a silence. The create API's per-scene `script` is narrower: it is the text of a single one of these entries.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"Synthesized speech: a script delivered by a voice.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this script entry within the video. Not to be parsed, sorted, or assumed to encode anything. The same id under two scenes means one entry is shared between them: its text belongs to both, and concatenating both scenes' scripts would synthesize the shared words twice.\",\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"The script, verbatim, including inline markup. Empty when the scene was left unfinished.\",\n \"type\": \"string\"\n },\n \"trim_to_speech\": {\n \"description\": \"Whether leading and trailing silence is trimmed to the spoken window.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"type\": {\n \"default\": \"text\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"The voice delivering this script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning applied to this script.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Present only when the video pins an engine this API exposes; absent when the engine is left for the server to pick.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"description\": \"Pitch adjustment in semitones.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"speed\": {\n \"description\": \"Playback speed multiplier.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"volume\": {\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"text\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Uploaded audio played as the scene's speech.\",\n \"properties\": {\n \"audio_url\": {\n \"description\": \"URL of the audio. Present when the video records a link for this entry and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Identifier of this script entry within the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"audio\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A held silence, with no words spoken over the scene.\",\n \"properties\": {\n \"duration\": {\n \"description\": \"How long the silence is held, in seconds. Absent where the number does not describe what renders — on a scene whose video clip plays in full, the clip's own length governs the scene.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"id\": {\n \"description\": \"Identifier of this script entry within the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"silence\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"video\": {\n \"description\": \"Video-level context for the scenes.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"The video's aspect ratio.\",\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 applied to this video's speech.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption configuration for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"enabled\": {\n \"description\": \"Whether captions are enabled for this video.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"enabled\"\n ],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"The video's output resolution, in the same values a create request accepts. Absent when the video's size matches none of them, which is a size a create request could not have asked for and cannot reproduce.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"The video's current title. Editor saves update it.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"video_id\": {\n \"description\": \"The video these scenes belong to.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"video_id\",\n \"video\"\n ],\n \"type\": \"object\"\n },\n \"error\": {\n \"nullable\": true,\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Description: "Returns the video's scenes together with the video-level context needed to use them. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated. The response includes an opaque `edit_version` for optimistic concurrency. A video whose editor document is still being prepared returns `409 resource_not_ready`; retry after the video advances.\n\nEach scene splits by the role a thing plays: `background` fills the frame, `elements` are placed within it, and `script` is the audio delivered over it. A whole-frame image or clip lands in `background`, so code that reads only `elements` misses it.\n\nElement types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in `elements`, so the count is always truthful, but only `avatar`, `image` and `video` are described in full; `group` and `mask` carry their children; the rest carry an `id` and a `type` and nothing more.\n\n**What this does not describe.** A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which this version does not return.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"The composite document: one video's context and every one of its scenes.\",\n \"properties\": {\n \"edit_version\": {\n \"description\": \"Opaque version of the editor document returned by this request. Pass it unchanged when requesting an edit so the server can reject a document that changed before submission. This submission-time check does not lock the document while the asynchronous agent applies the edit.\",\n \"type\": \"string\"\n },\n \"scenes\": {\n \"description\": \"Every scene in the video, in the video's own order, which is playback order unless the video branches. Never paginated.\",\n \"items\": {\n \"description\": \"One scene, in the video's own order.\\n\\nThat is playback order for a linear video, which is the ordinary case. A branching video plays as\\na walk over branch targets instead, so its scenes are still all here and still ordered, but the\\norder is not the sequence a viewer sees. Branching is not otherwise described by this version.\\n\\nThe three content fields split by the role a thing plays rather than by its kind:\\n``background`` fills the frame, ``elements`` are placed within it, ``script`` carries\\nthe speech delivered over it. The background is visual too, so ``elements`` means \\\"the\\nones the scene places\\\", not \\\"the visual ones\\\".\",\n \"properties\": {\n \"background\": {\n \"description\": \"What fills the frame behind this scene's elements.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/ColorBackground\",\n \"image\": \"#/components/schemas/ImageBackground\",\n \"video\": \"#/components/schemas/VideoBackground\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"A solid colour filling the frame behind the scene's elements.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Hex colour, e.g. '#f6f6fc'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"color\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"color\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame image.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame video clip.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene. Same values as a video element's playback.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Background type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this background and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"elements\": {\n \"description\": \"Every element this scene places, in the video's own order.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"An avatar performing the scene's speech.\\n\\nCarries what a v3 create request can set per avatar, so what is read back here is what can be\\nsent back. Fields are added as callers need them, and a new one is not a breaking change.\\n\\nOutput resolution is a whole-video setting, reported on the video rather than per avatar.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"The avatar look performing this scene.\",\n \"type\": \"string\"\n },\n \"engine\": {\n \"description\": \"Generation engine for this avatar. Absent when the video does not record one and none can be determined.\",\n \"enum\": [\n \"avatar_v\",\n \"avatar_iv\",\n \"avatar_iii\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"expressiveness\": {\n \"description\": \"Expressiveness level. Absent when left at the default.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Motion description authored for this avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"avatar\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An image placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed; the element is still reported either way, so an image with no URL is one this read could not link to rather than an element this API does not describe. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A video clip placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene: 'freeze' holds the last frame, 'loop' repeats it, 'fit_to_scene' changes speed to match, 'full_video' plays it whole and drives the scene's length.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element this version names but does not describe.\\n\\nExists so a scene's ``elements`` array is never a filtered view presented as a complete one: a\\ncaller iterating it sees every element the scene places. Carries exactly two fields: which\\nelement this is, and what kind of thing it is.\\n\\n**Absence of content is not by itself proof that an element is undescribed.** A described\\ncategory can serialize with nothing but an id and a type when every optional field happens to be\\nunavailable, and one case is reachable today: an image with no usable link carries no ``url``,\\nleaving ``{id, type}``. Read the ``type`` to tell them apart.\\n``avatar``, ``image`` and ``video`` are described, so a bare one of those is a described element\\nmissing an optional value rather than an unexpanded node.\\n\\nThe ``id`` matters most here. Two masked elements in one scene are otherwise identical on the\\nwire, so without it a caller can see that the scene places two things and nothing else about\\neither.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The element's category. An **open set**: new values may be added, so treat an unrecognized one as an element to skip rather than an error. Several kinds of element can share one value, so a category says what an element is rather than naming a single underlying kind. Every value is permanent except 'other', which means 'a kind of element this API does not yet categorise' and may be replaced by a more specific category later.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element that holds other elements: a group, or a mask.\\n\\nA scene lists the container, not its contents, so a scene holding one group of five images\\nlists a single element while five things render. Walking a scene's composition means recursing\\ninto ``children``.\\n\\nA mask matters more here than a group: a group conveys linkage this response does not express,\\nwhile a mask conveys clipping, so treating a masked image as a plain image asserts a\\ncomposition that renders differently in kind.\",\n \"properties\": {\n \"children\": {\n \"description\": \"The elements this container holds, each described exactly as a top-level element would be.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"An avatar performing the scene's speech.\\n\\nCarries what a v3 create request can set per avatar, so what is read back here is what can be\\nsent back. Fields are added as callers need them, and a new one is not a breaking change.\\n\\nOutput resolution is a whole-video setting, reported on the video rather than per avatar.\",\n \"properties\": {\n \"avatar_id\": {\n \"description\": \"The avatar look performing this scene.\",\n \"type\": \"string\"\n },\n \"engine\": {\n \"description\": \"Generation engine for this avatar. Absent when the video does not record one and none can be determined.\",\n \"enum\": [\n \"avatar_v\",\n \"avatar_iv\",\n \"avatar_iii\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"expressiveness\": {\n \"description\": \"Expressiveness level. Absent when left at the default.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Motion description authored for this avatar.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"avatar\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An image placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"image\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the image. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed; the element is still reported either way, so an image with no URL is one this read could not link to rather than an element this API does not describe. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A video clip placed in the scene.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"How the clip is reconciled to the scene: 'freeze' holds the last frame, 'loop' repeats it, 'fit_to_scene' changes speed to match, 'full_video' plays it whole and drives the scene's length.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed_multiplier\": {\n \"description\": \"Playback speed multiplier. 2.0 = twice as fast.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"trim\": {\n \"description\": \"Seconds trimmed from each end of the clip.\",\n \"nullable\": true,\n \"properties\": {\n \"end_offset\": {\n \"description\": \"Seconds trimmed from the end of the clip.\",\n \"type\": \"number\"\n },\n \"start_offset\": {\n \"description\": \"Seconds trimmed from the start of the clip.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"start_offset\",\n \"end_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"default\": \"video\",\n \"description\": \"Element type discriminator.\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the clip. Present when the video records a link for this element and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"volume\": {\n \"description\": \"Clip audio volume. 1.0 = source level, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"An element this version names but does not describe.\\n\\nExists so a scene's ``elements`` array is never a filtered view presented as a complete one: a\\ncaller iterating it sees every element the scene places. Carries exactly two fields: which\\nelement this is, and what kind of thing it is.\\n\\n**Absence of content is not by itself proof that an element is undescribed.** A described\\ncategory can serialize with nothing but an id and a type when every optional field happens to be\\nunavailable, and one case is reachable today: an image with no usable link carries no ``url``,\\nleaving ``{id, type}``. Read the ``type`` to tell them apart.\\n``avatar``, ``image`` and ``video`` are described, so a bare one of those is a described element\\nmissing an optional value rather than an unexpanded node.\\n\\nThe ``id`` matters most here. Two masked elements in one scene are otherwise identical on the\\nwire, so without it a caller can see that the scene places two things and nothing else about\\neither.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The element's category. An **open set**: new values may be added, so treat an unrecognized one as an element to skip rather than an error. Several kinds of element can share one value, so a category says what an element is rather than naming a single underlying kind. Every value is permanent except 'other', which means 'a kind of element this API does not yet categorise' and may be replaced by a more specific category later.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Circular reference to ContainerElement\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Opaque identifier of this element within the video. Not to be parsed, sorted, or assumed to encode anything. Stable across edits and across regeneration of the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"The container's category, e.g. 'group' or 'mask'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"id\": {\n \"description\": \"Identifier of this scene within the video.\",\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"This scene's audio sources in order, each one synthesized speech, uploaded audio, or a silence. The create API's per-scene `script` is narrower: it is the text of a single one of these entries.\",\n \"items\": {\n \"anyOf\": [\n {\n \"description\": \"Synthesized speech: a script delivered by a voice.\",\n \"properties\": {\n \"id\": {\n \"description\": \"Opaque identifier of this script entry within the video. Not to be parsed, sorted, or assumed to encode anything. The same id under two scenes means one entry is shared between them: its text belongs to both, and concatenating both scenes' scripts would synthesize the shared words twice.\",\n \"type\": \"string\"\n },\n \"text\": {\n \"description\": \"The script, verbatim, including inline markup. Empty when the scene was left unfinished.\",\n \"type\": \"string\"\n },\n \"trim_to_speech\": {\n \"description\": \"Whether leading and trailing silence is trimmed to the spoken window.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"type\": {\n \"default\": \"text\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"The voice delivering this script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning applied to this script.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Present only when the video pins an engine this API exposes; absent when the engine is left for the server to pick.\",\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 must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\",\n \"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 \"description\": \"Pitch adjustment in semitones.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"speed\": {\n \"description\": \"Playback speed multiplier.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"volume\": {\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"id\",\n \"text\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Uploaded audio played as the scene's speech.\",\n \"properties\": {\n \"audio_url\": {\n \"description\": \"URL of the audio. Present when the video records a link for this entry and, if that link is signed, it is not at or near its deadline. Absent when no link is recorded, or the only recorded link has lapsed. Only the deadline is checked, so a present URL is not a promise that it resolves: it may name an object that has since moved, or a host the customer supplied. Signed links expire, so download what you need rather than storing the URL.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Identifier of this script entry within the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"audio\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A held silence, with no words spoken over the scene.\",\n \"properties\": {\n \"duration\": {\n \"description\": \"How long the silence is held, in seconds. Absent where the number does not describe what renders — on a scene whose video clip plays in full, the clip's own length governs the scene.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"id\": {\n \"description\": \"Identifier of this script entry within the video.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"default\": \"silence\",\n \"description\": \"Script entry type discriminator.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"video\": {\n \"description\": \"Video-level context for the scenes.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"description\": \"The video's aspect ratio.\",\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 applied to this video's speech.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption configuration for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"enabled\": {\n \"description\": \"Whether captions are enabled for this video.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"enabled\"\n ],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"The video's output resolution, in the same values a create request accepts. Absent when the video's size matches none of them, which is a size a create request could not have asked for and cannot reproduce.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"The video's current title. Editor saves update it.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"video_id\": {\n \"description\": \"The video these scenes belong to.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"video_id\",\n \"edit_version\",\n \"video\"\n ],\n \"type\": \"object\"\n },\n \"error\": {\n \"nullable\": true,\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/videos/{video_id}/scenes", Method: "GET", BodyEncoding: "", diff --git a/gen/voice.go b/gen/voice.go index a598365..540390a 100644 --- a/gen/voice.go +++ b/gen/voice.go @@ -255,8 +255,8 @@ var VoiceSpeechCreate = &command.Spec{ Group: "voice", Name: "speech create", Summary: "Generate Speech", - Description: "Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.", - RequestSchema: "{\n \"description\": \"Request body for text-to-speech generation.\",\n \"properties\": {\n \"input_type\": {\n \"default\": \"text\",\n \"description\": \"Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.\",\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"locale\": {\n \"description\": \"BCP-47 locale tag (e.g. 'en-US', 'pt-BR'). When set, language is inferred from locale.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Speed multiplier (0.5-2.0).\",\n \"type\": \"number\"\n },\n \"text\": {\n \"description\": \"Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, \\u003cbreak time=\\\"0.35s\\\"/\\u003e); millisecond values are not supported.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID to use. The voice must support the starfish engine. Filter compatible voices by passing engine=starfish to the voice listing endpoint.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"text\",\n \"voice_id\"\n ],\n \"type\": \"object\"\n}", + Description: "Synthesize speech audio from text with a voice from the voice catalog. The voice must be one the Starfish engine supports: a stock voice, a designed voice, or an instant clone. List them with GET /v3/voices?engine=starfish. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.", + RequestSchema: "{\n \"description\": \"Request body for text-to-speech generation.\",\n \"properties\": {\n \"input_type\": {\n \"default\": \"text\",\n \"description\": \"Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.\",\n \"type\": \"string\"\n },\n \"language\": {\n \"description\": \"Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"locale\": {\n \"description\": \"BCP-47 locale tag (e.g. 'en-US', 'pt-BR'). When set, language is inferred from locale.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Speed multiplier (0.5-2.0).\",\n \"type\": \"number\"\n },\n \"text\": {\n \"description\": \"Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, \\u003cbreak time=\\\"0.35s\\\"/\\u003e); millisecond values are not supported.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID from the voice catalog. The voice must be one the Starfish engine supports: a stock voice, a designed voice, or an instant clone. List them with GET /v3/voices?engine=starfish. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"text\",\n \"voice_id\"\n ],\n \"type\": \"object\"\n}", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response payload for text-to-speech generation.\",\n \"properties\": {\n \"audio_url\": {\n \"description\": \"URL of the generated audio file.\",\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Duration of the audio in seconds.\",\n \"type\": \"number\"\n },\n \"request_id\": {\n \"description\": \"Unique identifier for this generation request.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"word_timestamps\": {\n \"description\": \"Word-level timing data.\",\n \"items\": {\n \"description\": \"Word-level timing data from TTS generation.\",\n \"properties\": {\n \"end\": {\n \"description\": \"End time in seconds.\",\n \"type\": \"number\"\n },\n \"start\": {\n \"description\": \"Start time in seconds.\",\n \"type\": \"number\"\n },\n \"word\": {\n \"description\": \"The word.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"word\",\n \"start\",\n \"end\"\n ],\n \"type\": \"object\"\n },\n \"nullable\": true,\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"audio_url\",\n \"duration\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/voices/speech", Method: "POST", @@ -329,7 +329,7 @@ var VoiceSpeechCreate = &command.Spec{ Name: "voice-id", Type: "string", Default: "", - Help: "Voice ID to use. The voice must support the starfish engine. Filter compatible voices by passing engine=starfish to the voice listing endpoint.", + Help: "Voice ID from the voice catalog. The voice must be one the Starfish engine supports: a stock voice, a designed voice, or an instant clone. List them with GET /v3/voices?engine=starfish. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead.", Required: true, Enum: nil, Min: nil,