create-video

Send an optimized prompt to POST /v1/video_agent/generate with your X-Api-Key header, optionally setting config.duration_sec, orientation, and avatar_id. The API returns a video_id, which you poll via GET /v2/videos/{video_id} until the status is completed.

Use Video Agent for quick prompt-based generation where the AI handles scripting and scenes. Use the standard v2/video/generate API when you need precise control over specific avatars, exact scripts, per-scene configuration, or multi-scene composition.

Video generation typically takes 5-15 minutes, but can exceed 20 minutes during peak load or for longer scripts. Set polling timeouts of 15-20 minutes and consider webhooks for production systems instead of continuous polling.

HeyGen supports 720p and 1080p in landscape (16:9), portrait (9:16), and square (1:1) formats. Custom dimensions are allowed between 128px and 4096px per side, and both width and height must be even numbers.

Poor results usually come from layout language like screen coordinates, unnamed visual styles, B-roll scenes under 5 seconds, or content written as lists instead of narratives. Use the prompt optimizer guidelines with named styles, layered motion graphics, and scene rotation.

Call GET /v2/user/remaining_quota with your X-Api-Key header to retrieve remaining and used credits. Check quota before generating videos, since 1080p videos consume roughly 1.5x the base credit rate of 720p.