From 7569e3c06c81f59a4a8adf3fa326037ff6d4cfe5 Mon Sep 17 00:00:00 2001 From: heygen-rui-bot Date: Wed, 16 Sep 2026 04:20:30 +0300 Subject: [PATCH] codegen: resync gen/ from EF aa22d49b --- gen/asset.go | 4 +-- gen/brand.go | 20 +++++++------- gen/filler-word-removal.go | 2 +- gen/registry.go | 2 ++ gen/video-agent.go | 20 +++++++++++--- gen/video-translate.go | 53 ++++++++++++++++++++++++++++++++++++++ gen/video.go | 8 +++--- 7 files changed, 88 insertions(+), 21 deletions(-) diff --git a/gen/asset.go b/gen/asset.go index c8a8470..72b6496 100644 --- a/gen/asset.go +++ b/gen/asset.go @@ -162,7 +162,7 @@ var AssetDirectUploadsBatchesCreate = &command.Spec{ Summary: "Create Asset Upload Batch", Description: "Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch).", RequestSchema: "{\n \"properties\": {\n \"callback_url\": {\n \"description\": \"Reserved. Asset completion does not emit a webhook.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"files\": {\n \"description\": \"Files to presign, same shape as POST /v3/assets/direct-uploads. Max 100 per batch.\",\n \"items\": {\n \"description\": \"One requested file in a create-upload-batch call.\",\n \"properties\": {\n \"checksum_sha256\": {\n \"description\": \"Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"content_type\": {\n \"description\": \"Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf'). Verified against the stored bytes when the batch is completed.\",\n \"type\": \"string\"\n },\n \"filename\": {\n \"description\": \"Original filename for reference/metadata. The stored object's extension is derived from content_type.\",\n \"type\": \"string\"\n },\n \"size_bytes\": {\n \"description\": \"Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"filename\",\n \"content_type\",\n \"size_bytes\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display name for the batch, shown in the HeyGen app.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"files\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"batch_id\": {\n \"description\": \"Identifier of the created batch. Pass to POST /v3/assets/complete/batches once all files are uploaded.\",\n \"type\": \"string\"\n },\n \"items\": {\n \"description\": \"One presigned upload slot per requested file, in the submitted order.\",\n \"items\": {\n \"description\": \"One issued presigned upload slot in the create response.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"Reusable asset identifier. Becomes usable after POST /v3/assets/complete/batches finalizes the batch.\",\n \"type\": \"string\"\n },\n \"expires_in_seconds\": {\n \"description\": \"Seconds until the upload URL expires.\",\n \"type\": \"integer\"\n },\n \"max_bytes\": {\n \"description\": \"Maximum allowed upload size in bytes.\",\n \"type\": \"integer\"\n },\n \"status\": {\n \"description\": \"Upload lifecycle status. Always 'pending_upload' here.\",\n \"type\": \"string\"\n },\n \"upload_headers\": {\n \"description\": \"Headers that must be sent verbatim on the PUT request.\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n },\n \"upload_url\": {\n \"description\": \"Presigned S3 URL. PUT the raw file bytes here.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"asset_id\",\n \"upload_url\",\n \"upload_headers\",\n \"expires_in_seconds\",\n \"max_bytes\",\n \"status\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"batch_id\",\n \"items\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"properties\": {\n \"batch_id\": {\n \"description\": \"Identifier of the created batch. Pass to POST /v3/assets/complete/batches once all files are uploaded.\",\n \"type\": \"string\"\n },\n \"items\": {\n \"description\": \"One presigned upload slot per requested file, in the submitted order.\",\n \"items\": {\n \"description\": \"One issued presigned upload slot in the create response.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"Reusable asset identifier. Becomes usable after POST /v3/assets/complete/batches finalizes the batch.\",\n \"type\": \"string\"\n },\n \"expires_in_seconds\": {\n \"description\": \"Seconds until the upload URL expires.\",\n \"type\": \"integer\"\n },\n \"max_bytes\": {\n \"description\": \"Maximum allowed upload size in bytes for this content type: 1.5 GB (1,500,000,000 bytes) per audio file and 200 MiB (209,715,200 bytes) for other supported files.\",\n \"type\": \"integer\"\n },\n \"status\": {\n \"description\": \"Upload lifecycle status. Always 'pending_upload' here.\",\n \"type\": \"string\"\n },\n \"upload_headers\": {\n \"description\": \"Headers that must be sent verbatim on the PUT request.\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n },\n \"upload_url\": {\n \"description\": \"Presigned S3 URL. PUT the raw file bytes here.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"asset_id\",\n \"upload_url\",\n \"upload_headers\",\n \"expires_in_seconds\",\n \"max_bytes\",\n \"status\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"batch_id\",\n \"items\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/assets/direct-uploads/batches", Method: "POST", BodyEncoding: "json", @@ -204,7 +204,7 @@ var AssetDirectUploadsCreate = &command.Spec{ Summary: "Create Asset Upload", Description: "Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API.", RequestSchema: "{\n \"description\": \"Request to begin a presigned direct-to-S3 upload (POST /v3/assets/direct-uploads).\",\n \"properties\": {\n \"checksum_sha256\": {\n \"description\": \"Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"content_type\": {\n \"description\": \"Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf', 'application/zip'). Verified against the stored bytes at completion.\",\n \"type\": \"string\"\n },\n \"filename\": {\n \"description\": \"Original filename for reference/metadata. The stored object's extension is derived from content_type.\",\n \"type\": \"string\"\n },\n \"size_bytes\": {\n \"description\": \"Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"filename\",\n \"content_type\",\n \"size_bytes\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Presigned upload instructions.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"Reusable asset identifier. Becomes usable after POST /v3/assets/{asset_id}/complete.\",\n \"type\": \"string\"\n },\n \"expires_in_seconds\": {\n \"description\": \"Seconds until the upload URL expires.\",\n \"type\": \"integer\"\n },\n \"max_bytes\": {\n \"description\": \"Maximum allowed upload size in bytes.\",\n \"type\": \"integer\"\n },\n \"status\": {\n \"description\": \"Upload lifecycle status. Always 'pending_upload' here.\",\n \"type\": \"string\"\n },\n \"upload_headers\": {\n \"description\": \"Headers that must be sent verbatim on the PUT request.\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n },\n \"upload_url\": {\n \"description\": \"Presigned S3 URL. PUT the raw file bytes here.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"asset_id\",\n \"upload_url\",\n \"upload_headers\",\n \"expires_in_seconds\",\n \"max_bytes\",\n \"status\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Presigned upload instructions.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"Reusable asset identifier. Becomes usable after POST /v3/assets/{asset_id}/complete.\",\n \"type\": \"string\"\n },\n \"expires_in_seconds\": {\n \"description\": \"Seconds until the upload URL expires.\",\n \"type\": \"integer\"\n },\n \"max_bytes\": {\n \"description\": \"Maximum allowed upload size in bytes for this content type: 1.5 GB (1,500,000,000 bytes) per audio file and 200 MiB (209,715,200 bytes) for other supported files.\",\n \"type\": \"integer\"\n },\n \"status\": {\n \"description\": \"Upload lifecycle status. Always 'pending_upload' here.\",\n \"type\": \"string\"\n },\n \"upload_headers\": {\n \"description\": \"Headers that must be sent verbatim on the PUT request.\",\n \"properties\": {},\n \"required\": [],\n \"type\": \"object\"\n },\n \"upload_url\": {\n \"description\": \"Presigned S3 URL. PUT the raw file bytes here.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"asset_id\",\n \"upload_url\",\n \"upload_headers\",\n \"expires_in_seconds\",\n \"max_bytes\",\n \"status\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/assets/direct-uploads", Method: "POST", BodyEncoding: "json", diff --git a/gen/brand.go b/gen/brand.go index dbe5fc8..b8d967f 100644 --- a/gen/brand.go +++ b/gen/brand.go @@ -8,9 +8,9 @@ var BrandGlossariesCreate = &command.Spec{ Group: "brand", Name: "glossaries create", Summary: "Create Brand Glossary", - Description: "Creates a brand glossary in your workspace. Pass the returned `brand_glossary_id` when creating a video or translation to apply it.\n\n`name` must be unique within your workspace, compared without regard to case; a duplicate returns 409. `terms` may be omitted to create an empty glossary you fill in later with PATCH /v3/brand-glossaries/{brand_glossary_id}.\n\nPronunciations affect generated audio only — a term keeps its original spelling in captions and subtitles. Translation rules are managed in the HeyGen web app and cannot be set here.", - RequestSchema: "{\n \"description\": \"Request body for POST /v3/brand-glossaries.\",\n \"properties\": {\n \"name\": {\n \"description\": \"Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"default\": [],\n \"description\": \"Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.\",\n \"items\": {\n \"description\": \"Write-side glossary entry: strict shape enforced on POST / PATCH bodies only.\\n\\nSplit from ``BrandGlossaryTerm`` on purpose. The read projection must round-trip any legacy\\n(term, pronunciation) pair that ``brand_voice.vocabulary`` holds, including blank or padded\\nvalues, so a fresher write-time constraint cannot leak into GET without silently dropping\\nthose rows. Keeping the constraints on a write-only subclass means POST / PATCH reject empty\\nor whitespace-only entries with a 400 while GET behavior is byte-identical to before.\\n\\nSame shape as ``BrandGlossaryTerm`` so ``_vocabulary_from_terms`` and\\n``ensure_brand_glossary_terms_unique`` (which reads ``.term`` off each entry) accept either\\nwithout adaptation.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Description: "Creates a brand glossary in your workspace. Pass the returned `brand_glossary_id` when creating a video or translation to apply it.\n\n`name` must be unique within your workspace, compared without regard to case; a duplicate returns 409. `terms`, `do_not_translate_terms` and `forced_translations` may each be omitted to create an empty glossary you fill in later with PATCH /v3/brand-glossaries/{brand_glossary_id}.\n\nPronunciations affect generated audio only — a term keeps its original spelling in captions and subtitles. `do_not_translate_terms` and `forced_translations` apply only when the glossary is used by a translation feature (video translation, Studio script translation, on-screen text translation), in every target language; they have no effect on video generation or text-to-speech requests. Tone settings are managed in the HeyGen web app and cannot be set here.", + RequestSchema: "{\n \"description\": \"Request body for POST /v3/brand-glossaries.\",\n \"properties\": {\n \"do_not_translate_terms\": {\n \"default\": [],\n \"description\": \"Terms to keep untranslated when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none.\",\n \"items\": {\n \"description\": \"One Don't Translate rule as accepted on POST / PATCH bodies.\",\n \"properties\": {\n \"term\": {\n \"description\": \"A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term — matched case-insensitively — is kept untranslated in every target language. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"forced_translations\": {\n \"default\": [],\n \"description\": \"Force Translate rules: terms translated into an exact replacement when this glossary is used by a translation feature. Omit it, or pass an empty array, to add none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.\",\n \"items\": {\n \"description\": \"One Force Translate rule as accepted on POST / PATCH bodies.\",\n \"properties\": {\n \"term\": {\n \"description\": \"The term to replace, matched in the source text case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"translation\": {\n \"description\": \"The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"translation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"name\": {\n \"description\": \"Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"default\": [],\n \"description\": \"Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you fill in later.\",\n \"items\": {\n \"description\": \"One glossary entry as accepted on POST / PATCH: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"do_not_translate_terms\": {\n \"description\": \"Don't Translate rules in this glossary. Omitted when it has none.\",\n \"items\": {\n \"description\": \"One Don't Translate rule: a term kept untranslated when content is translated.\",\n \"properties\": {\n \"term\": {\n \"description\": \"A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term — matched case-insensitively — is kept untranslated in every target language.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"forced_translations\": {\n \"description\": \"Force Translate rules in this glossary. Omitted when it has none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.\",\n \"items\": {\n \"description\": \"One Force Translate rule: a term and the exact translation that replaces it.\",\n \"properties\": {\n \"term\": {\n \"description\": \"The term to replace, matched in the source text case-insensitively.\",\n \"type\": \"string\"\n },\n \"translation\": {\n \"description\": \"The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"translation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries", Method: "POST", BodyEncoding: "json", @@ -39,7 +39,7 @@ var BrandGlossariesDelete = &command.Spec{ Group: "brand", Name: "glossaries delete", Summary: "Delete Brand Glossary", - Description: "Deletes a brand glossary.\n\nThis cannot be undone: there is no way to restore a deleted brand glossary through the API.\n\nThe glossary stops being returned by this API at once, and stops applying: neither its pronunciation terms nor its translation rules — the latter managed in the HeyGen web app and not visible here — affect anything generated afterwards.\n\nVideos already generated with the glossary are unaffected, since their audio was synthesized at the time. A video or translation still configured with a deleted glossary keeps working rather than failing.", + Description: "Deletes a brand glossary.\n\nThis cannot be undone: there is no way to restore a deleted brand glossary through the API.\n\nThe glossary stops being returned by this API at once, and stops applying: neither its pronunciation terms nor its translation rules affect anything generated afterwards.\n\nVideos already generated with the glossary are unaffected, since their audio was synthesized at the time. A video or translation still configured with a deleted glossary keeps working rather than failing.", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for DELETE /v3/brand-glossaries/{brand_glossary_id}.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Identifier of the deleted brand glossary.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", Method: "DELETE", @@ -58,8 +58,8 @@ var BrandGlossariesGet = &command.Spec{ Group: "brand", Name: "glossaries get", Summary: "Get Brand Glossary", - Description: "Returns one brand glossary with its full term list, so you can see exactly which terms are remapped and how. Use this to verify a glossary's contents when a generated video pronounces a term unexpectedly.\n\nPronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its `pronunciation`.\n\nA glossary can also carry translation rules, which control how terms are handled when a video is translated. Those are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged.", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Description: "Returns one brand glossary with its full term list, so you can see exactly which terms are remapped and how. Use this to verify a glossary's contents when a generated video pronounces or translates a term unexpectedly.\n\nPronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its `pronunciation`.\n\nTranslation rules apply only when the glossary is used by a translation feature — video translation, Studio script translation, and on-screen text translation: `do_not_translate_terms` are kept untranslated in every target language, and `forced_translations` replace their `term` with their `translation` in every target language. They have no effect on video generation or text-to-speech requests; only `terms` applies there. Either list is omitted from the response when the glossary has no rules of that kind. Tone settings are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"do_not_translate_terms\": {\n \"description\": \"Don't Translate rules in this glossary. Omitted when it has none.\",\n \"items\": {\n \"description\": \"One Don't Translate rule: a term kept untranslated when content is translated.\",\n \"properties\": {\n \"term\": {\n \"description\": \"A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term — matched case-insensitively — is kept untranslated in every target language.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"forced_translations\": {\n \"description\": \"Force Translate rules in this glossary. Omitted when it has none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.\",\n \"items\": {\n \"description\": \"One Force Translate rule: a term and the exact translation that replaces it.\",\n \"properties\": {\n \"term\": {\n \"description\": \"The term to replace, matched in the source text case-insensitively.\",\n \"type\": \"string\"\n },\n \"translation\": {\n \"description\": \"The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"translation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", Method: "GET", BodyEncoding: "", @@ -75,7 +75,7 @@ var BrandGlossariesList = &command.Spec{ Group: "brand", Name: "glossaries list", Summary: "List Brand Glossaries", - Description: "List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary controls how custom terms are pronounced in generated speech — for example, speaking \"HeyGen\" as \"hey-jen\".\n\nPass the returned `brand_glossary_id` when creating a video or translation to apply the glossary. Use GET /v3/brand-glossaries/{brand_glossary_id} to see which terms it remaps, POST /v3/brand-glossaries to create one, and PATCH /v3/brand-glossaries/{brand_glossary_id} to change one.", + Description: "List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary controls how custom terms are pronounced in generated speech — for example, speaking \"HeyGen\" as \"hey-jen\" — and how they are handled when a video is translated: Don't Translate terms kept as-is, and Force Translate terms with a fixed replacement.\n\nPass the returned `brand_glossary_id` when creating a video or translation to apply the glossary. Use GET /v3/brand-glossaries/{brand_glossary_id} to see which terms it remaps, POST /v3/brand-glossaries to create one, and PATCH /v3/brand-glossaries/{brand_glossary_id} to change one.", ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"A single brand glossary entry in the list response.\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\"\n ],\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/brand-glossaries", Method: "GET", @@ -116,9 +116,9 @@ var BrandGlossariesUpdate = &command.Spec{ Group: "brand", Name: "glossaries update", Summary: "Update Brand Glossary", - Description: "Updates a brand glossary. Each field is replaced independently: a field you omit is left untouched, a field you send replaces that value in full, and an empty `terms` array removes every term. There is no way to add a single term — read the glossary, append to `terms`, and send the whole list back.\n\nRenaming to a name another glossary in your workspace already uses returns 409.\n\nA glossary's translation rules are managed in the HeyGen web app and are never modified by this endpoint, so a glossary edited there keeps them through an update made here.", - RequestSchema: "{\n \"description\": \"Request body for PATCH /v3/brand-glossaries/{brand_glossary_id}.\\n\\nEach field is replaced independently: a field you omit is left untouched, a field you send\\nreplaces that value in full, and an empty array clears the term list. There is no way to add a\\nsingle term — read the glossary, append to `terms`, and send the whole list back.\",\n \"properties\": {\n \"name\": {\n \"description\": \"New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.\",\n \"items\": {\n \"description\": \"Write-side glossary entry: strict shape enforced on POST / PATCH bodies only.\\n\\nSplit from ``BrandGlossaryTerm`` on purpose. The read projection must round-trip any legacy\\n(term, pronunciation) pair that ``brand_voice.vocabulary`` holds, including blank or padded\\nvalues, so a fresher write-time constraint cannot leak into GET without silently dropping\\nthose rows. Keeping the constraints on a write-only subclass means POST / PATCH reject empty\\nor whitespace-only entries with a 400 while GET behavior is byte-identical to before.\\n\\nSame shape as ``BrandGlossaryTerm`` so ``_vocabulary_from_terms`` and\\n``ensure_brand_glossary_terms_unique`` (which reads ``.term`` off each entry) accept either\\nwithout adaptation.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", - ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\\n\\nRead-side / response model. Deliberately lenient: it is used as the value type in\\n``from_vocabulary`` to project already-stored pairs, so any constraint added here would\\nreject the legacy blank / padded rows that ``brand_voice.vocabulary`` (a schemaless JSON\\ncolumn) can legitimately hold. Write-side constraints live on ``BrandGlossaryTermWrite``.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Description: "Updates a brand glossary. Each field is replaced independently: a field you omit is left untouched, a field you send replaces that value in full, and an empty array removes every entry from that list. There is no way to add a single entry — read the glossary, append to the list, and send the whole list back.\n\nRenaming to a name another glossary in your workspace already uses returns 409.\n\nA glossary's tone settings are managed in the HeyGen web app and are never modified by this endpoint, so a glossary edited there keeps them through an update made here.", + RequestSchema: "{\n \"description\": \"Request body for PATCH /v3/brand-glossaries/{brand_glossary_id}.\\n\\nEach field is replaced independently: a field you omit is left untouched, a field you send\\nreplaces that value in full, and an empty array clears that list. There is no way to add a\\nsingle entry — read the glossary, append to the list, and send the whole list back.\",\n \"properties\": {\n \"do_not_translate_terms\": {\n \"description\": \"Replacement Don't Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all.\",\n \"items\": {\n \"description\": \"One Don't Translate rule as accepted on POST / PATCH bodies.\",\n \"properties\": {\n \"term\": {\n \"description\": \"A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term — matched case-insensitively — is kept untranslated in every target language. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"forced_translations\": {\n \"description\": \"Replacement Force Translate list. Omit to leave the existing entries untouched, or pass an empty array to remove them all. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.\",\n \"items\": {\n \"description\": \"One Force Translate rule as accepted on POST / PATCH bodies.\",\n \"properties\": {\n \"term\": {\n \"description\": \"The term to replace, matched in the source text case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"translation\": {\n \"description\": \"The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"translation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"name\": {\n \"description\": \"New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Replacement term list. Omit to leave the existing terms untouched, or pass an empty array to remove them all.\",\n \"items\": {\n \"description\": \"One glossary entry as accepted on POST / PATCH: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively. Surrounding whitespace is removed and the trimmed value must be non-empty.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"A single brand glossary with its full term list (GET /v3/brand-glossaries/{id}).\",\n \"properties\": {\n \"brand_glossary_id\": {\n \"description\": \"Unique brand glossary ID. Pass it as `brand_glossary_id` when creating a video or translation to apply this glossary.\",\n \"type\": \"string\"\n },\n \"created_at\": {\n \"description\": \"Creation timestamp (UTC).\",\n \"type\": \"string\"\n },\n \"do_not_translate_terms\": {\n \"description\": \"Don't Translate rules in this glossary. Omitted when it has none.\",\n \"items\": {\n \"description\": \"One Don't Translate rule: a term kept untranslated when content is translated.\",\n \"properties\": {\n \"term\": {\n \"description\": \"A term to keep untranslated. When this glossary is used by a translation feature, each occurrence of the term — matched case-insensitively — is kept untranslated in every target language.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"forced_translations\": {\n \"description\": \"Force Translate rules in this glossary. Omitted when it has none. A term should not appear in both this list and `do_not_translate_terms`; behavior is undefined if it does.\",\n \"items\": {\n \"description\": \"One Force Translate rule: a term and the exact translation that replaces it.\",\n \"properties\": {\n \"term\": {\n \"description\": \"The term to replace, matched in the source text case-insensitively.\",\n \"type\": \"string\"\n },\n \"translation\": {\n \"description\": \"The exact text used in place of `term` in the translated output, in every target language. Inserted verbatim: grammatical inflection (case, gender, number) is not adapted to the surrounding sentence.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"translation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"name\": {\n \"description\": \"Display name of the brand glossary.\",\n \"type\": \"string\"\n },\n \"terms\": {\n \"description\": \"Every term mapping in this glossary. Empty when the glossary has no terms yet, in which case applying it has no effect.\",\n \"items\": {\n \"description\": \"One glossary entry: a written term and how it should be spoken.\",\n \"properties\": {\n \"pronunciation\": {\n \"description\": \"Respelling handed to the speech synthesizer in place of `term` (for example 'hey-jen' for 'HeyGen'). Affects generated audio only — captions and subtitles keep the original `term` spelling.\",\n \"type\": \"string\"\n },\n \"term\": {\n \"description\": \"The term as written in a script, matched case-insensitively.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"term\",\n \"pronunciation\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"updated_at\": {\n \"description\": \"Last update timestamp (UTC).\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"brand_glossary_id\",\n \"name\",\n \"created_at\",\n \"updated_at\",\n \"terms\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", Endpoint: "/v3/brand-glossaries/{brand_glossary_id}", Method: "PATCH", BodyEncoding: "json", diff --git a/gen/filler-word-removal.go b/gen/filler-word-removal.go index c093faa..8680279 100644 --- a/gen/filler-word-removal.go +++ b/gen/filler-word-removal.go @@ -8,7 +8,7 @@ var FillerWordRemovalCreate = &command.Spec{ Group: "filler-word-removal", Name: "create", Summary: "Create Filler Word Removal", - Description: "Submit a video and return a job id immediately. The job runs asynchronously: it transcribes the audio, detects filler words ('um', 'uh', ...), removes them along with overlong silences, and renders one cleaned video — no review step. If the run changes nothing at all, the job completes with the original video as output and the charge is automatically refunded. Pricing: $0.60 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or subscribe to filler_word_removal.success / filler_word_removal.fail webhooks.", + Description: "Submit a video and return a job id immediately. The job runs asynchronously: it transcribes the audio, detects filler words ('um', 'uh', ...), removes them along with overlong silences, and renders one cleaned video — no review step. If the run changes nothing at all, the job completes with the original video as output and the charge is automatically refunded. Pricing: $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or subscribe to filler_word_removal.success / filler_word_removal.fail webhooks.", RequestSchema: "{\n \"description\": \"Request body for POST /v3/filler-word-removals.\",\n \"properties\": {\n \"callback_id\": {\n \"description\": \"Opaque client identifier echoed verbatim in webhook payloads.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"HTTPS URL to receive per-job webhook callbacks (filler_word_removal.success / filler_word_removal.fail). Delivery is best-effort with limited retries — poll GET /v3/filler-word-removals/{id} as the source of truth (a terminal GET may precede its webhook). Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret via /v3/webhooks/endpoints.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the job. Defaults to 'Filler Removal' if omitted.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"video\": {\n \"description\": \"Source video to clean. Either a URL or an asset_id from POST /v1/asset.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n },\n \"required\": [\n \"video\"\n ],\n \"type\": \"object\"\n}", Endpoint: "/v3/filler-word-removals", Method: "POST", diff --git a/gen/registry.go b/gen/registry.go index 4fa226e..d63af62 100644 --- a/gen/registry.go +++ b/gen/registry.go @@ -112,8 +112,10 @@ var Groups = map[string][]*command.Spec{ VideoTranslateLanguagesList, VideoTranslateList, VideoTranslateProofreadsCreate, + VideoTranslateProofreadsDelete, VideoTranslateProofreadsGenerate, VideoTranslateProofreadsGet, + VideoTranslateProofreadsList, VideoTranslateProofreadsSrtGet, VideoTranslateProofreadsSrtUpdate, VideoTranslateStatusesList, diff --git a/gen/video-agent.go b/gen/video-agent.go index 0e1ec93..eb2823b 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.\",\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 \"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 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}", 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", @@ -48,7 +48,7 @@ var VideoAgentCreate = &command.Spec{ Name: "brand-kit-id", Type: "string", Default: "", - Help: "Brand kit ID to apply brand colors, fonts, and logos to the generated video.", + Help: "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.", Required: false, Enum: nil, Min: nil, @@ -140,6 +140,18 @@ var VideoAgentCreate = &command.Spec{ Source: "body", JSONName: "style_id", }, + { + Name: "visibility", + Type: "string", + Default: "team", + Help: "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.", + Required: false, + Enum: []string{"private", "team", "public"}, + Min: nil, + Max: nil, + Source: "body", + JSONName: "visibility", + }, { Name: "voice-id", Type: "string", @@ -236,7 +248,7 @@ var VideoAgentSend = &command.Spec{ 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\",\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}", + 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}", Endpoint: "/v3/video-agents/{session_id}", Method: "POST", @@ -264,7 +276,7 @@ var VideoAgentSend = &command.Spec{ Name: "brand-kit-id", Type: "string", Default: "", - Help: "Brand kit ID to apply for this message", + Help: "Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted.", Required: false, Enum: nil, Min: nil, diff --git a/gen/video-translate.go b/gen/video-translate.go index b492476..78f65e4 100644 --- a/gen/video-translate.go +++ b/gen/video-translate.go @@ -601,6 +601,21 @@ var VideoTranslateProofreadsCreate = &command.Spec{ }, } +var VideoTranslateProofreadsDelete = &command.Spec{ + Group: "video-translate", + Name: "proofreads delete", + Summary: "Delete Proofread Session", + Description: "Deletes a proofread session, removing it from listings and from the workspace's projects. Requires an account role of Creator or higher. This action cannot be undone.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"description\": \"Response for DELETE /v3/video-translations/proofreads/{id}.\",\n \"properties\": {\n \"id\": {\n \"description\": \"ID of the deleted proofread session\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", + Endpoint: "/v3/video-translations/proofreads/{proofread_id}", + Method: "DELETE", + BodyEncoding: "", + Destructive: true, + Args: []command.ArgSpec{ + {Name: "proofread-id", Param: "proofread_id", Help: ""}, + }, +} + var VideoTranslateProofreadsGenerate = &command.Spec{ Group: "video-translate", Name: "proofreads generate", @@ -687,6 +702,44 @@ var VideoTranslateProofreadsGet = &command.Spec{ }, } +var VideoTranslateProofreadsList = &command.Spec{ + Group: "video-translate", + Name: "proofreads list", + Summary: "List Proofread Sessions", + Description: "Returns a paginated list of all proofread sessions in the workspace, newest first.", + ResponseSchema: "{\n \"properties\": {\n \"data\": {\n \"items\": {\n \"description\": \"Detailed proofread resource.\",\n \"properties\": {\n \"created_at\": {\n \"description\": \"Unix timestamp when the proofread was created\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"failure_message\": {\n \"description\": \"Error description. Only present when status is failed.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"id\": {\n \"description\": \"Unique proofread identifier\",\n \"type\": \"string\"\n },\n \"input_language\": {\n \"description\": \"Detected or specified source language code\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_language\": {\n \"description\": \"Target language code\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"status\": {\n \"description\": \"Current status\",\n \"enum\": [\n \"processing\",\n \"completed\",\n \"failed\"\n ],\n \"type\": \"string\"\n },\n \"submitted_for_review\": {\n \"description\": \"Whether the proofread has been submitted for review\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"title\": {\n \"description\": \"Title of the proofread job\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"status\"\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/video-translations/proofreads", + Method: "GET", + BodyEncoding: "", + Paginated: true, + Flags: []command.FlagSpec{ + { + Name: "limit", + Type: "int", + Default: "10", + Help: "Maximum number of items per page", + Required: false, + Enum: nil, + Min: intPtr(1), + Max: intPtr(100), + Source: "query", + JSONName: "limit", + }, + { + Name: "token", + Type: "string", + Default: "", + Help: "Opaque cursor token for the next page", + Required: false, + Enum: nil, + Min: nil, + Max: nil, + Source: "query", + JSONName: "token", + }, + }, +} + var VideoTranslateProofreadsSrtGet = &command.Spec{ Group: "video-translate", Name: "proofreads srt get", diff --git a/gen/video.go b/gen/video.go index b0515c0..85adf88 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.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video by animating an arbitrary image.\\n\\nProvide an image via URL, asset ID, or inline base64. The image will be\\nanimated with lip-sync to the provided audio or generated speech.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\\n\\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\\nreference content: one to three avatar looks and optional reference assets\\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\\nno script or voice — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"description\": \"Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — video avatars and photo avatars alike (pass a photo avatar's look id to get a talking photo). The scene duration is derived server-side from the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame still-image scene: either silent (held for ``duration``) or narrated.\\n\\nExactly one mode must be chosen:\\n- silent: set ``duration`` (seconds) and no audio source.\\n- narrated: set exactly one audio source (script + voice_id, audio_url, or\\n audio_asset_id) and omit ``duration`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame scene backed by an existing video clip.\\n\\nOptional ``playback`` exposes the audio volume / mute capability; when\\nomitted the clip plays at its source volume.\\n\\nFor optional voiceover / narration, supply at most one audio source\\n(``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the *same*\\naudio inputs a narrated ``image`` scene accepts. When present, the narration\\ndrives the scene length and ``playback.mode`` controls whether the clip\\nfreezes, loops, or changes speed to fit that duration. When omitted the clip\\nplays full-length as before. The clip's own audio level is still governed by\\n``playback`` (the two compose).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"description\": \"How a narrated clip aligns to the voiceover-driven scene duration. 'freeze' plays once and holds the last frame; 'loop' repeats the clip; 'fit_to_scene' adjusts playback speed to exactly match the scene. Defaults to 'freeze' when omitted. Requires a video-scene voiceover.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"videos\"\n ],\n \"type\": \"object\"\n}", + 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}", Endpoint: "/v3/videos/batches", Method: "POST", BodyEncoding: "json", @@ -106,7 +106,7 @@ var VideoCreate = &command.Spec{ Name: "create", Summary: "Create Video", Description: "Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted.", - RequestSchema: "{\n \"description\": \"Discriminated union for POST /v3/videos request body.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar\": \"#/components/schemas/CreateVideoFromAvatar\",\n \"cinematic_avatar\": \"#/components/schemas/CreateVideoFromCinematicAvatar\",\n \"image\": \"#/components/schemas/CreateVideoFromImage\",\n \"studio\": \"#/components/schemas/CreateVideoFromStudio\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Create a video from a HeyGen avatar (video or photo avatar).\\n\\nProvide an avatar_id to use a previously created avatar. Supports all\\navatar types: studio_avatar, digital_twin, and photo_avatar. Optionally\\nset ``engine`` to select Avatar V for eligible avatars; when omitted, the\\nserver defaults to Avatar IV.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for avatar-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video by animating an arbitrary image.\\n\\nProvide an image via URL, asset ID, or inline base64. The image will be\\nanimated with lip-sync to the provided audio or generated speech.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output video aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the source's aspect ratio (avatar source frames or uploaded image), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to '16:9' when source dimensions can't be read.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Background settings for the video.\",\n \"nullable\": true,\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.\",\n \"enum\": [\n \"color\",\n \"image\"\n ],\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"value\": {\n \"description\": \"Hex color code (e.g. '#ff0000'). Required when type is 'color'.\",\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies when the audio is synthesized from `script`; a caller-supplied `audio_url` or `audio_asset_id` is unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"fit\": {\n \"description\": \"How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.\",\n \"enum\": [\n \"contain\",\n \"cover\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"image\": {\n \"description\": \"Image to animate. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion. Photo avatars only.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"output_format\": {\n \"default\": \"mp4\",\n \"description\": \"Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.\",\n \"enum\": [\n \"mp4\",\n \"webm\"\n ],\n \"type\": \"string\"\n },\n \"remove_background\": {\n \"description\": \"Remove the avatar background. Video avatars must be trained with matting enabled.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n },\n \"resolution\": {\n \"description\": \"Output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'image' for image-based video creation.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"image\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a video from a text prompt plus avatar and asset references (Cinematic Avatar).\\n\\nCinematic Avatar generates a video from a natural-language ``prompt`` guided by\\nreference content: one to three avatar looks and optional reference assets\\n(images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is\\nno script or voice — motion and speech are driven entirely by the prompt and\\nthe supplied references. Backed by the Seedance generation pipeline.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16', '1:1'. Defaults to '16:9'.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"1:1\"\n ],\n \"type\": \"string\"\n },\n \"auto_duration\": {\n \"default\": false,\n \"description\": \"Let the model choose the video length. When true, omit duration.\",\n \"type\": \"boolean\"\n },\n \"avatar_id\": {\n \"description\": \"Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"duration\": {\n \"description\": \"Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.\",\n \"nullable\": true,\n \"type\": \"integer\"\n },\n \"enhance_prompt\": {\n \"default\": false,\n \"description\": \"Enable server-side prompt enhancement.\",\n \"type\": \"boolean\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Natural-language prompt describing the video to generate.\",\n \"type\": \"string\"\n },\n \"references\": {\n \"description\": \"Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"nullable\": true,\n \"type\": \"array\"\n },\n \"resolution\": {\n \"default\": \"720p\",\n \"description\": \"Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.\",\n \"enum\": [\n \"720p\",\n \"1080p\"\n ],\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'cinematic_avatar' for prompt-and-reference video creation.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"prompt\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Create a single video by composing an ordered list of whole-frame scenes.\\n\\nThe server owns layout and center-crops each scene to the global output\\ncanvas. Output settings are global (one per request); a single video_id is\\nreturned and rendering is all-or-nothing. MP4 only in v1 — the output\\ncontainer is fixed and ``output_format`` is not exposed.\",\n \"properties\": {\n \"aspect_ratio\": {\n \"default\": \"16:9\",\n \"description\": \"Global output aspect ratio. Supported values: '16:9', '9:16', '4:5', '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is center-cropped to this canvas.\",\n \"enum\": [\n \"16:9\",\n \"9:16\",\n \"4:5\",\n \"5:4\",\n \"1:1\",\n \"auto\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"brand_glossary_id\": {\n \"description\": \"Brand glossary ID controlling how custom terms are pronounced in generated speech (for example, saying 'HeyGen' as 'hey-jen'). Applies to every scene whose audio is synthesized from a script; scenes that supply their own audio URL or audio asset are unaffected. Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_id\": {\n \"description\": \"Caller-defined identifier echoed back in the webhook payload.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"callback_url\": {\n \"description\": \"Webhook URL to receive a POST notification when the video is ready.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"caption\": {\n \"description\": \"Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.\",\n \"nullable\": true,\n \"properties\": {\n \"file_format\": {\n \"default\": \"srt\",\n \"description\": \"Output format for the sidecar caption file.\",\n \"enum\": [\n \"srt\"\n ],\n \"type\": \"string\"\n },\n \"style\": {\n \"description\": \"Visual style for burning captions into the rendered video. Omit for sidecar-only captions.\",\n \"enum\": [\n \"default\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"folder_id\": {\n \"description\": \"Destination folder ID in the caller's workspace. Omit, pass null, or pass an empty string to place the video at the workspace root. Supported only for single-video creation; batch video items cannot set their own destination folder.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"resolution\": {\n \"description\": \"Global output video resolution.\",\n \"enum\": [\n \"4k\",\n \"1080p\",\n \"720p\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"scenes\": {\n \"description\": \"Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.\",\n \"items\": {\n \"discriminator\": {\n \"mapping\": {\n \"avatar_video\": \"#/components/schemas/AvatarVideoScene\",\n \"image\": \"#/components/schemas/ImageScene\",\n \"video\": \"#/components/schemas/VideoScene\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"A whole-frame speaking scene backed by an avatar.\",\n \"properties\": {\n \"input\": {\n \"description\": \"Scene source ('type': 'avatar'): an avatar_id plus one audio source. The avatar_id accepts any avatar look — video avatars and photo avatars alike (pass a photo avatar's look id to get a talking photo). The scene duration is derived server-side from the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Public URL of an audio file to lip-sync. Mutually exclusive with script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"avatar_id\": {\n \"description\": \"HeyGen avatar ID (video avatar or photo avatar look ID).\",\n \"type\": \"string\"\n },\n \"background\": {\n \"description\": \"Optional scene background composited behind the avatar. Color-only in v1: pass {\\\"type\\\": \\\"color\\\", \\\"color\\\": \\\"#RRGGBB\\\"}. Other background types are not yet supported.\",\n \"discriminator\": {\n \"mapping\": {\n \"color\": \"#/components/schemas/StudioColorBackgroundInput\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Solid-color background for an ``avatar_video`` studio scene.\\n\\nStudio v1 supports solid-color backgrounds.\",\n \"properties\": {\n \"color\": {\n \"description\": \"Background color as a 6-digit hex string, e.g. '#1a2b3c'.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Background type discriminator. Must be 'color'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"color\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"engine\": {\n \"description\": \"Engine configuration for video generation. Pass {\\\"type\\\": \\\"avatar_v\\\"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted.\",\n \"discriminator\": {\n \"mapping\": {\n \"avatar_iii\": \"#/components/schemas/AvatarIIIEngineConfig\",\n \"avatar_iv\": \"#/components/schemas/AvatarIVEngineConfig\",\n \"avatar_v\": \"#/components/schemas/AvatarVEngineConfig\"\n },\n \"propertyName\": \"type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Avatar V engine configuration with cross-reference-driven animation.\",\n \"properties\": {\n \"reference_look_id\": {\n \"description\": \"Optional look to use as the animation reference. When provided, it must be a `digital_twin` look accessible to your workspace and in the same avatar group as `avatar_id` (`studio_avatar` and `photo_avatar` looks are rejected). When omitted, video avatars self-reference and photo avatars select from their group's eligible candidates, preferring digital twins (ready first, then processing / upgrading), then curated public studio looks. A photo avatar whose group has no eligible reference renders directly from its image without one; motion_prompt is rejected in that case. A non-public `digital_twin` reference, whether provided or selected automatically, must also satisfy its group's consent requirements.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar IV engine configuration (default behavior).\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iv'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Avatar III engine configuration.\\n\\nA single engine value that resolves to the right product by the avatar's\\nlook type (mirrors how ``avatar_iv`` already serves both photo and video\\navatars):\\n\\n- video avatar looks (``digital_twin``, ``studio_avatar``) -\\u003e Digital Twin\\n (supports 4K)\\n- ``photo_avatar`` look -\\u003e Photo Avatar (no 4K output)\\n\\nNot supported for raw image input (``type: \\\"image\\\"``).\\n``motion_prompt`` and ``expressiveness`` are not supported with this engine.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"expressiveness\": {\n \"description\": \"Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; rejected when engine.type is 'avatar_v'.\",\n \"enum\": [\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"motion_prompt\": {\n \"description\": \"Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine, and for photo avatars on 'avatar_v' when the avatar's group has no animation reference (no digital twin or curated reference look).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"script\": {\n \"description\": \"Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar' for an avatar-driven scene source.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback).\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"avatar_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": {\n \"description\": \"Must be 'avatar_video' for an avatar speaking scene.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"input\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame still-image scene: either silent (held for ``duration``) or narrated.\\n\\nExactly one mode must be chosen:\\n- silent: set ``duration`` (seconds) and no audio source.\\n- narrated: set exactly one audio source (script + voice_id, audio_url, or\\n audio_asset_id) and omit ``duration`` — the scene length follows the audio.\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"duration\": {\n \"description\": \"Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be \\u003e 0 and \\u003c= 300.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"script\": {\n \"description\": \"Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Still image to display. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'image' for a still-image scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale).\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"A whole-frame scene backed by an existing video clip.\\n\\nOptional ``playback`` exposes the audio volume / mute capability; when\\nomitted the clip plays at its source volume.\\n\\nFor optional voiceover / narration, supply at most one audio source\\n(``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the *same*\\naudio inputs a narrated ``image`` scene accepts. When present, the narration\\ndrives the scene length and ``playback.mode`` controls whether the clip\\nfreezes, loops, or changes speed to fit that duration. When omitted the clip\\nplays full-length as before. The clip's own audio level is still governed by\\n``playback`` (the two compose).\",\n \"properties\": {\n \"audio_asset_id\": {\n \"description\": \"Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"audio_url\": {\n \"description\": \"Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"playback\": {\n \"description\": \"Optional playback capability: narrated-clip alignment 'mode', audio 'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and keep the clip's source volume.\",\n \"nullable\": true,\n \"properties\": {\n \"mode\": {\n \"description\": \"How a narrated clip aligns to the voiceover-driven scene duration. 'freeze' plays once and holds the last frame; 'loop' repeats the clip; 'fit_to_scene' adjusts playback speed to exactly match the scene. Defaults to 'freeze' when omitted. Requires a video-scene voiceover.\",\n \"enum\": [\n \"freeze\",\n \"loop\",\n \"fit_to_scene\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"mute\": {\n \"default\": false,\n \"description\": \"If True, force the clip silent regardless of 'volume'.\",\n \"type\": \"boolean\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Clip audio volume. 1.0 = source level (default), 0.0 = silent.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"script\": {\n \"description\": \"Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"source\": {\n \"description\": \"Video clip to include. Accepts URL, asset ID, or base64-encoded data.\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": {\n \"description\": \"Must be 'video' for a video-clip scene.\",\n \"type\": \"string\"\n },\n \"voice_id\": {\n \"description\": \"Voice ID for text-to-speech. Required when script is provided.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"voice_settings\": {\n \"description\": \"Voice tuning parameters (speed, pitch, locale) for a script voiceover.\",\n \"nullable\": true,\n \"properties\": {\n \"engine_settings\": {\n \"description\": \"Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.\",\n \"discriminator\": {\n \"mapping\": {\n \"elevenlabs\": \"#/components/schemas/ElevenLabsEngineSettings\",\n \"fish\": \"#/components/schemas/FishEngineSettings\",\n \"starfish\": \"#/components/schemas/StarfishEngineSettings\"\n },\n \"propertyName\": \"engine_type\"\n },\n \"nullable\": true,\n \"oneOf\": [\n {\n \"description\": \"Engine-specific voice settings for ElevenLabs-backed voices.\\n\\nSupports model, stability, similarity_boost, style, and use_speaker_boost.\\nWhen using eleven_v3, stability must be 0, 0.5, or 1.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"The model ID to use for ElevenLabs.\",\n \"enum\": [\n \"eleven_multilingual_v2\",\n \"eleven_turbo_v2_5\",\n \"eleven_flash_v2_5\",\n \"eleven_v3\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity_boost\": {\n \"description\": \"The similarity boost parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"The stability parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"style\": {\n \"description\": \"The style parameter for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"use_speaker_boost\": {\n \"description\": \"Whether to use speaker boost for ElevenLabs.\",\n \"nullable\": true,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-specific voice settings for Fish Audio-backed voices.\\n\\nInherits Fish's tuning fields (model, stability, similarity).\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Fish Audio model version (default 's1').\",\n \"enum\": [\n \"s1\",\n \"s2-pro\"\n ],\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"similarity\": {\n \"description\": \"Similarity parameter; how closely to match the source voice.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"stability\": {\n \"description\": \"Stability parameter; higher is more consistent.\",\n \"nullable\": true,\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Engine-selection for Starfish-backed voices.\\n\\nStarfish has no user-tunable settings today; set ``engine_type='starfish'`` to force\\nStarfish routing on voices that support multiple engines.\",\n \"properties\": {\n \"engine_type\": {\n \"description\": \"Engine type discriminator. Must be 'starfish' for Starfish-backed voices.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"engine_type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"locale\": {\n \"description\": \"Locale/accent hint for multi-lingual voices (e.g. 'en-US').\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"pitch\": {\n \"default\": 0,\n \"description\": \"Pitch adjustment in semitones. -50 to +50.\",\n \"type\": \"number\"\n },\n \"speed\": {\n \"default\": 1,\n \"description\": \"Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).\",\n \"type\": \"number\"\n },\n \"volume\": {\n \"default\": 1,\n \"description\": \"Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.\",\n \"type\": \"number\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"source\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"title\": {\n \"description\": \"Display title for the video in the HeyGen dashboard.\",\n \"nullable\": true,\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Must be 'studio' for scene-composition video creation.\",\n \"type\": \"string\"\n },\n \"watermark\": {\n \"description\": \"Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.\",\n \"nullable\": true,\n \"properties\": {\n \"image\": {\n \"description\": \"Image asset to use as the watermark overlay (PNG or JPEG).\",\n \"discriminator\": {\n \"mapping\": {\n \"asset_id\": \"#/components/schemas/AssetId\",\n \"base64\": \"#/components/schemas/AssetBase64\",\n \"url\": \"#/components/schemas/AssetUrl\"\n },\n \"propertyName\": \"type\"\n },\n \"oneOf\": [\n {\n \"description\": \"Asset input via publicly accessible HTTPS URL.\",\n \"properties\": {\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"Publicly accessible HTTPS URL for the asset\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"url\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via HeyGen asset ID from the asset upload endpoint.\",\n \"properties\": {\n \"asset_id\": {\n \"description\": \"HeyGen asset ID from the asset upload endpoint\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"asset_id\"\n ],\n \"type\": \"object\"\n },\n {\n \"description\": \"Asset input via base64-encoded content.\",\n \"properties\": {\n \"data\": {\n \"description\": \"Base64-encoded file content\",\n \"type\": \"string\"\n },\n \"media_type\": {\n \"description\": \"MIME type of the encoded content (e.g. \\\"image/png\\\")\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Input type discriminator\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\",\n \"media_type\",\n \"data\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"opacity\": {\n \"default\": 1,\n \"description\": \"Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.\",\n \"type\": \"number\"\n },\n \"placement\": {\n \"description\": \"Watermark placement. Defaults to bottom-right with standard margins when omitted.\",\n \"nullable\": true,\n \"properties\": {\n \"offset_x\": {\n \"description\": \"Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"offset_y\": {\n \"description\": \"Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.\",\n \"nullable\": true,\n \"type\": \"number\"\n },\n \"position\": {\n \"default\": \"bottom_right\",\n \"description\": \"Anchor corner for the watermark.\",\n \"enum\": [\n \"top_left\",\n \"top_right\",\n \"bottom_left\",\n \"bottom_right\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n },\n \"scale\": {\n \"default\": 1,\n \"description\": \"Scale multiplier for the watermark image. 1.0 renders at native size.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"image\"\n ],\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"type\",\n \"scenes\"\n ],\n \"type\": \"object\"\n }\n ]\n}", + 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}", 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", @@ -223,8 +223,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, read together rather than assembled from separate calls. 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 are withheld to keep this version small and are returned on request.", - 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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available.\",\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\\n**This is a deliberately minimal set, not everything the video records about an avatar.** It\\ncovers what a v3 create request can set per avatar, so what is read back is what can be sent\\nback. A video may hold further per-avatar values — including some an older create surface\\naccepts per character — and those are not returned in this version. The set grows additively as\\ncallers ask for a value, so a field appearing later is not a breaking change.\\n\\nResolution is the omission worth naming, because one is returned but not here: a v3 create\\ncarries a single global resolution, so it is reported on the video. That video-level value is\\nthe request's own output resolution and **not** a summary of what the avatars hold — on a video\\nwhose avatars were given resolutions individually, the two are separate inputs and can differ.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available — the stored link is an expired signature and there is no current one to re-sign from. Present, it is not guaranteed to resolve: it may point at a host the customer supplied, and a signed link expires. An image with no URL carries only its id and type, which is an image this read could not link to rather than an element this API does not describe.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available — the stored link is an expired signature and there is no current one to re-sign from. Present, it is not guaranteed to resolve: it may point at a host the customer supplied, and a signed link expires.\",\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. The absence of content fields is the assertion,\\nso nothing has to be added when a category graduates to being described.\\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 whose stored link is a signature this read\\ncould not renew carries no ``url``, leaving ``{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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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 identifies what an element is rather than how it is stored. 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\\nReturned as a node with its children under it, because the scene does not list those children\\nitself — a scene holding one group of five images lists one element while five things render.\\nOmitting the container would erase its contents rather than merely its label, and flattening the\\nchildren up into the scene's own list would rebuild the draft's flat, pointer-based layout on the\\npublic surface, which is the thing this tree exists to spare a caller.\\n\\nA caller walking a scene's composition therefore has to recurse. A mask matters more than a group\\nhere: a group conveys linkage this response does not express, while a mask conveys clipping, so\\npresenting a masked image as a plain image would assert a composition that renders differently in\\nkind.\",\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\\n**This is a deliberately minimal set, not everything the video records about an avatar.** It\\ncovers what a v3 create request can set per avatar, so what is read back is what can be sent\\nback. A video may hold further per-avatar values — including some an older create surface\\naccepts per character — and those are not returned in this version. The set grows additively as\\ncallers ask for a value, so a field appearing later is not a breaking change.\\n\\nResolution is the omission worth naming, because one is returned but not here: a v3 create\\ncarries a single global resolution, so it is reported on the video. That video-level value is\\nthe request's own output resolution and **not** a summary of what the avatars hold — on a video\\nwhose avatars were given resolutions individually, the two are separate inputs and can differ.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available — the stored link is an expired signature and there is no current one to re-sign from. Present, it is not guaranteed to resolve: it may point at a host the customer supplied, and a signed link expires. An image with no URL carries only its id and type, which is an image this read could not link to rather than an element this API does not describe.\",\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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available — the stored link is an expired signature and there is no current one to re-sign from. Present, it is not guaranteed to resolve: it may point at a host the customer supplied, and a signed link expires.\",\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. The absence of content fields is the assertion,\\nso nothing has to be added when a category graduates to being described.\\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 whose stored link is a signature this read\\ncould not renew carries no ``url``, leaving ``{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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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 identifies what an element is rather than how it is stored. 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. Minted once when the video's editor document is created, and stable across edits and regeneration.\",\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. Absent when no durable link is available — the stored link is an expired signature and there is no current one to re-sign from. Present, it is not guaranteed to resolve: it may point at a host the customer supplied, and a signed link expires.\",\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 stored size matches no such value, which is a video whose 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.\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}", Endpoint: "/v3/videos/{video_id}/scenes", Method: "GET", BodyEncoding: "",