The primary distinction lies in the balance between automation and granular control.

The Video Agent API takes a single text prompt and triggers the autonomous orchestration of avatar creation, script writing, and visual asset creation and layouts. It offers a full range of precise control while also allowing complete creative freedom. Great for massive content exploration, internal video creation and automation. It’s a true unique offering in the entire industry.

In comparison, the Standard Video Generation APIs have 2 main parts: 1) Avatar Video Generation and 2) Template Video Generation. Developers create Avatars and Video Templates using HeyGen’s Web platform which can then be used by the API. Even though it requires more setup, these APIs provide precise control needed for brand-consistent, high-production-value assets. Enterprise customers have created millions of videos through them to automate their content pipelines.

Yes, here are steps to use the Photo Avatar API

1. Upload Existing Photos (via Upload Asset API)
2. Create an Avatar Group: Create an Avatar Group by grouping photos of the same subject.
3. (optional) Train the Avatar Group: Once your Avatar Group is created, you can train the model to recognize the subject's unique features, expressions, and other elements to ensure it generates realistic avatars.
4. If you want to use Template Video Generation to generate “personalized” videos at Scale, you can use/replace the avatar by following this guide.

If you want to use the Avatar Video Generation, you can use /plug in the avatar by following this guide.

Yes, the API supports pure text-to-avatar generation through a structured descriptive framework that eliminates the need for external image assets. By providing specific parameters across eight required fields—including age, gender, ethnicity, and style—the AI synthesizes a unique, high-resolution persona. For example, selecting "East Asian" ethnicity with a "Professional" style and "Cinematic" lighting will prompt the engine to return a selection of unique Avatars and Looks, effectively allowing enterprises to scale diverse cast libraries that do not exist in the real world.

You can follow the guide here for prompt-to-avatar.

The template system is designed for high-efficiency "mail-merge" style video production, where a master layout acts as a container for dynamic data. Users first create or select a template via the Dashboard or API, then identify specific placeholders for text, images, or audio. By sending a single POST request to the template's generate endpoint with a JSON payload of variables, the system automatically renders unique video files for each recipient, making it the industry standard for personalized sales outreach and customized customer onboarding at scale.

To ensure the highest level of realism and lip-sync accuracy, the recommended "Golden Path" is to programmatically retrieve and utilize the default_voice_id associated with a specific avatar. This method guarantees that the vocal characteristics—such as gender, tone, and regional accent—are already optimized for that avatar's visual persona, significantly reducing the risk of "uncanny valley" effects. If a custom voice is required, developers should always filter the v2/voices list to match the avatar’s metadata to maintain audiovisual consistency.

Because high-fidelity AI video rendering is a resource-intensive process that can take several minutes, the API is designed to be used with an asynchronous, event-driven architecture via Webhooks. Instead of holding an open connection (which leads to timeouts), your application should register a webhook URL to receive an automated "push" notification once the avatar_video.success event triggers. This allows your backend to remain performant while only processing the video—via the provided video_url—the moment it becomes available.

The API provides a massive global reach, supporting over 40 languages and a library of more than 300 diverse voices, enabling seamless cross-border communication. Beyond simple text-to-speech in different languages, the platform offers "Video Translation" features that can take an existing video and translate the audio while simultaneously re-syncing the avatar’s lip movements to the new language. This ensures that the visual performance remains as authentic in Spanish or Japanese as it was in the original English recording.

HeyGen Video Translation can support 175 languages & dialects (according to here).