HeyGen Video Agent
HeyGen Video Agent is an AI video production model that generates complete, multi-scene videos from a single text prompt. It automates the full production pipeline — scriptwriting, avatar selection, shot planning, B-roll integration, motion graphics, captions, and editing — producing broadcast-ready videos with consistent branding. The agent supports customizable avatars, voice cloning, and iterative editing without full regeneration, enabling scalable video content creation for marketing, training, and social media.
API Options
Platform-level options for task execution and delivery.
-
taskType
string required value: videoInference -
Identifier for the type of task being performed
-
taskUUID
string required UUID v4 -
UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.
-
outputType
string default: URL -
Video output type.
Allowed values 1 value
-
outputFormat
string default: MP4 -
Specifies the file format of the generated output. The available values depend on the task type and the specific model's capabilities.
- `MP4`: Widely supported video container (H.264), recommended for general use.
- `WEBM`: Optimized for web delivery.
- `MOV`: QuickTime format, common in professional workflows (Apple ecosystem).
Allowed values 3 values
-
outputQuality
integer min: 20 max: 99 default: 95 -
Compression quality of the output. Higher values preserve quality but increase file size.
-
webhookURL
string URI -
Specifies a webhook URL where JSON responses will be sent via HTTP POST when generation tasks complete. For batch requests with multiple results, each completed item triggers a separate webhook call as it becomes available.
Learn more 1 resource
- Webhooks PLATFORM
- Webhooks
-
deliveryMethod
string default: async -
Determines how the API delivers task results.
Allowed values 1 value
- Returns an immediate acknowledgment with the task UUID. Poll for results using getResponse. Required for long-running tasks like video generation.
Learn more 1 resource
- Task Polling PLATFORM
-
uploadEndpoint
string URI -
Specifies a URL where the generated content will be automatically uploaded using the HTTP PUT method. The raw binary data of the media file is sent directly as the request body. For secure uploads to cloud storage, use presigned URLs that include temporary authentication credentials.
Common use cases:
- Cloud storage: Upload directly to S3 buckets, Google Cloud Storage, or Azure Blob Storage using presigned URLs.
- CDN integration: Upload to content delivery networks for immediate distribution.
// S3 presigned URL for secure upload https://your-bucket.s3.amazonaws.com/generated/content.mp4?X-Amz-Signature=abc123&X-Amz-Expires=3600 // Google Cloud Storage presigned URL https://storage.googleapis.com/your-bucket/content.jpg?X-Goog-Signature=xyz789 // Custom storage endpoint https://storage.example.com/uploads/generated-image.jpgThe content data will be sent as the request body to the specified URL when generation is complete.
-
safety
object -
Content safety checking configuration for video generation.
Properties 2 properties
-
safety»checkContentcheckContent
boolean default: false -
Enable or disable content safety checking. When enabled, defaults to
fastmode.
-
safety»modemode
string default: none -
Safety checking mode for video generation.
Allowed values 3 values
- Disables checking.
- Checks key frames.
- Checks all frames.
-
-
ttl
integer min: 60 -
Time-to-live (TTL) in seconds for generated content. Only applies when
outputTypeisURL.
-
includeCost
boolean default: false -
Include task cost in the response.
-
numberResults
integer min: 1 max: 4 default: 1 -
Number of results to generate. Each result uses a different seed, producing variations of the same parameters.
Inputs
Input resources for the task (images, audio, etc). These must be nested inside the inputs object.
inputs object. Generation Parameters
Core parameters for controlling the generated content.
-
model
string required value: heygen:video-agent@0 -
Identifier of the model to use for generation.
Learn more 3 resources
-
positivePrompt
string required min: 1 max: 10000 -
Text prompt describing elements to include in the generated output.
Learn more 2 resources
-
width
integer paired with height -
Width of the generated media in pixels.
Learn more 2 resources
-
height
integer paired with width -
Height of the generated media in pixels.
Learn more 2 resources
-
duration
integer min: 5 max: 300 -
Length of the generated video in seconds. The total number of frames produced is determined by duration multiplied by the model's frame rate (fps).
Origami Space Museum Explainer
{
"taskType": "videoInference",
"taskUUID": "86e70d5b-f263-4e53-91ea-e82552155a19",
"model": "heygen:video-agent@0",
"positivePrompt": "Create a polished 45-second educational brand video about a fictional 'Origami Space Museum' opening for families and school groups. Use a warm, curious, intelligent tone. Feature a presenter avatar as the host in several scenes, speaking directly to camera, with clean on-screen captions and tasteful motion graphics. Structure the video in multiple scenes: 1) an energetic opening with the host introducing the museum, 2) B-roll of towering folded-paper planets, suspended paper satellites, and intricate paper astronaut suits in a grand gallery, 3) a section highlighting interactive exhibits where children learn how folds mirror engineering principles, 4) a fast-paced montage of exhibit labels, hands folding geometric paper modules, and animated diagrams showing how flat sheets become complex structures, 5) a closing invitation with date, location, and family-friendly call to action. Visual style: contemporary educational promo, bright but refined palette of cobalt, cream, brass, and coral, crisp lighting, cinematic transitions, subtle depth of field, upbeat soundtrack feel implied by editing rhythm. Keep branding cohesive and premium. Make the host confident, approachable, and articulate. Emphasize that the full video should feel professionally produced from one prompt, with seamless scriptwriting, scene planning, captions, B-roll integration, and final edit.",
"width": 1280,
"height": 720,
"duration": 45,
"inputs": {
"avatar": "Judy_ConfidentSpeaking_Front_public"
}
}{
"taskType": "videoInference",
"taskUUID": "86e70d5b-f263-4e53-91ea-e82552155a19",
"videoUUID": "e376860e-f194-4542-9ddf-169ea920bf8e",
"videoURL": "https://vm.runware.ai/video/os/a19d05/ws/5/vi/e376860e-f194-4542-9ddf-169ea920bf8e.mp4",
"cost": 1.4667
}Midnight Vinyl Listening Lounge
{
"taskType": "videoInference",
"taskUUID": "43c178fb-21ac-412f-bd55-41ff237dff22",
"model": "heygen:video-agent@0",
"positivePrompt": "Create a 45-second polished presenter-led video introducing a boutique vinyl subscription club called Needle & Note. Use the provided input image as the speaking avatar. Tone: warm, sophisticated, inviting, and contemporary. Structure the video as a short branded promo with multiple scenes: opening hook from the host, close-up lifestyle B-roll of records sliding from sleeves, a turntable spinning, hands placing an album on a shelf, stylish membership box details, on-screen bullet points for monthly curated picks, member perks, and surprise collector extras, then return to the host for a concise call to action. Visual style: moody listening room with walnut shelves, velvet chair, amber practical lights, record stacks, subtle floating text graphics, elegant lower thirds, clean captions, smooth edits, premium social ad finish. Keep branding cohesive with cream, burgundy, and brass accents. Make the host confident and natural, with clear speech pacing and energetic but refined delivery.",
"width": 1280,
"height": 720,
"duration": 45,
"inputs": {
"image": "https://assets.runware.ai/assets/inputs/83a440ae-c93c-458f-b34e-ebbca07571a0.jpg"
}
}{
"taskType": "videoInference",
"taskUUID": "43c178fb-21ac-412f-bd55-41ff237dff22",
"videoUUID": "0dca7e78-989f-47e6-9940-03e6870a53ea",
"videoURL": "https://vm.runware.ai/video/os/a22d05/ws/5/vi/0dca7e78-989f-47e6-9940-03e6870a53ea.mp4",
"cost": 1.1489
}Art Deco Jewelry Atelier
{
"taskType": "videoInference",
"taskUUID": "2f01f65c-c0bb-498f-aa6b-60bf7279f6bb",
"model": "heygen:video-agent@0",
"positivePrompt": "Create a 45-second premium brand video in 16:9 using the provided image as the speaking presenter avatar. Theme: a boutique jewelry house introducing a new collection inspired by Art Deco geometry and modern craftsmanship. Structure the video as a complete polished production with scriptwriting, scene changes, tasteful lower-thirds, animated title cards, captions, B-roll inserts, and seamless editing. Open with an elegant intro frame in a refined atelier interior with brass details, velvet trays, gemstone close-ups, and sketch illustrations. The presenter speaks directly to camera with poised, luxurious energy and clear marketing delivery. Include scenes showing macro shots of rings, necklaces, and earrings rotating on neutral backdrops; artisans sketching facets and setting stones; close views of tools, polished metal, and gemstone sparkle; branded graphic overlays highlighting design principles such as symmetry, craftsmanship, heirloom quality, and custom fitting. Use a warm, sophisticated color palette of emerald, cream, black, and brushed gold. Keep the pacing smooth and upscale, with subtle camera motion, soft depth of field, and premium commercial lighting. Add readable on-screen captions and tasteful motion graphics that feel suitable for social ads or a website hero video. End with a memorable call-to-action inviting viewers to book a private styling appointment and discover the collection.",
"width": 1280,
"height": 720,
"duration": 45,
"inputs": {
"image": "https://assets.runware.ai/assets/inputs/db734229-9702-4029-bd38-4dc6c28a4779.jpg"
}
}{
"taskType": "videoInference",
"taskUUID": "2f01f65c-c0bb-498f-aa6b-60bf7279f6bb",
"videoUUID": "95f49fa8-40ec-4986-bbcc-a6d94e57a683",
"videoURL": "https://vm.runware.ai/video/os/a20d05/ws/5/vi/95f49fa8-40ec-4986-bbcc-a6d94e57a683.mp4",
"cost": 1.7524
}Retro Tech Product Showcase
{
"taskType": "videoInference",
"taskUUID": "d2c3787e-85bf-452e-80ea-b94baec35701",
"model": "heygen:video-agent@0",
"positivePrompt": "Create a sleek 30-second horizontal product-launch video in a retro-futuristic tech brand style. Use the provided image as the speaking avatar. The presenter introduces a fictional pocket device called 'PulseKey', a smart everyday gadget that organizes notes, payments, and travel access in one elegant object. Structure the video like a premium social ad with multiple scenes: an opening hero introduction with bold motion graphics, a presenter segment explaining the product benefit in clear concise language, stylish cutaway moments showing imagined close-ups of brushed metal surfaces, glowing interface details, and hands using the device in a modern apartment and night city setting, then a final call-to-action frame. Keep the editing energetic but polished, with confident startup-launch tone, vivid teal and warm amber accents, subtle film grain, clean captions, and smooth transitions. The avatar should remain natural, engaging, and centered when speaking, with the overall result feeling like a finished branded campaign video.",
"width": 1280,
"height": 720,
"duration": 30,
"inputs": {
"image": "https://assets.runware.ai/assets/inputs/0050d10b-8dc3-46c7-ba85-38b6da1ce559.jpg"
}
}{
"taskType": "videoInference",
"taskUUID": "d2c3787e-85bf-452e-80ea-b94baec35701",
"videoUUID": "3c619fc5-53bb-4106-a8c4-0a595f1fd62b",
"videoURL": "https://vm.runware.ai/video/os/a07d11/ws/5/vi/3c619fc5-53bb-4106-a8c4-0a595f1fd62b.mp4",
"cost": 0.758
}