REST API ReferenceEndpointsTools

Generate avatar clip

Generate a talking-head avatar video by pairing an ACTOR entity with an audio file, typically from a prior text-to-speech result.

Authentication

AuthorizationBearer
API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

Request

This endpoint expects an object.
actorEntityIdstringRequired

The id of a built-in stock actor or an ACTOR entity (e.g. vg_enti_...) with an image reference.

audioFileIdstringRequired

File id of an AUDIO file (e.g. vg_file_...), typically from a prior text-to-speech result. Upload a file first via POST /v1/files/upload or generate one with POST /v1/tools/text-to-speech, then pass the returned id here.

avatarQualityenumOptional

Avatar generation quality tier. Optional; when omitted, your account’s Default AI quality for avatars is used.

watermarkModeenumOptionalDefaults to AUTO

Controls whether the VideoGen watermark is applied to the output. AUTO applies the watermark unless you have a Pro plan. VIDEO_GEN always applies it. NONE removes the watermark (requires Pro; returns an error if you don’t have it).

numResultsintegerOptional1-100Defaults to 1
Number of output results to generate. Defaults to 1.
isOutputTemporarybooleanOptionalDefaults to false

When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false.

hideFromUibooleanOptionalDefaults to false
When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

Response

Execution accepted; poll until complete.

toolExecutionIdstring

Execution id (e.g. vg_tool_...).