Video Generation (HeyGen API)

Generate AI videos from text prompts. Supports multiple providers (VEO 3.1, Kling, Sora, Runway, Seedance), configurable aspect ratios, and optional reference images for image-to-video generation.

Authentication

All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{"workflow_type": "GenerateVideoNode", "input": {"prompt": "A drone shot flying over a coastal city at sunset"}}'

Default Workflow

• Call POST /v1/workflows/executions with workflow_type: "GenerateVideoNode" and your prompt

• Receive a execution_id in the response

• Poll GET /v1/workflows/executions/{id} every 10 seconds until status is completed

• Use the returned video_url from the output

Execute Video Generation

Endpoint

POST https://api.heygen.com/v1/workflows/executions

Request Fields

Field Type Req Description

workflow_type

string Y Must be "GenerateVideoNode"

input.prompt

string Y Text description of the video to generate

input.provider

string

Video generation provider (default: "veo_3_1" ). See Providers below.

input.aspect_ratio

string

Aspect ratio (default: "16:9" ). Common values: "16:9" , "9:16" , "1:1"

input.reference_image_url

string

Reference image URL for image-to-video generation

input.tail_image_url

string

Tail image URL for last-frame guidance

input.config

object

Provider-specific configuration overrides

Providers

Provider Value Description

VEO 3.1 "veo_3_1"

Google VEO 3.1 (default, highest quality)

VEO 3.1 Fast "veo_3_1_fast"

Faster VEO 3.1 variant

VEO 3 "veo3"

Google VEO 3

VEO 3 Fast "veo3_fast"

Faster VEO 3 variant

VEO 2 "veo2"

Google VEO 2

Kling Pro "kling_pro"

Kling Pro model

Kling V2 "kling_v2"

Kling V2 model

Sora V2 "sora_v2"

OpenAI Sora V2

Sora V2 Pro "sora_v2_pro"

OpenAI Sora V2 Pro

Runway Gen-4 "runway_gen4"

Runway Gen-4

Seedance Lite "seedance_lite"

Seedance Lite

Seedance Pro "seedance_pro"

Seedance Pro

LTX Distilled "ltx_distilled"

LTX Distilled (fastest)

curl

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A drone shot flying over a coastal city at golden hour, cinematic lighting", "provider": "veo_3_1", "aspect_ratio": "16:9" } }'

TypeScript

interface GenerateVideoInput { prompt: string; provider?: string; aspect_ratio?: string; reference_image_url?: string; tail_image_url?: string; config?: Record<string, any>; }

interface ExecuteResponse { data: { execution_id: string; status: "submitted"; }; }

async function generateVideo(input: GenerateVideoInput): Promise<string> { const response = await fetch("https://api.heygen.com/v1/workflows/executions", { method: "POST", headers: { "X-Api-Key": process.env.HEYGEN_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ workflow_type: "GenerateVideoNode", input, }), });

const json: ExecuteResponse = await response.json(); return json.data.execution_id; }

Python

import requests import os

def generate_video( prompt: str, provider: str = "veo_3_1", aspect_ratio: str = "16:9", reference_image_url: str | None = None, tail_image_url: str | None = None, ) -> str: payload = { "workflow_type": "GenerateVideoNode", "input": { "prompt": prompt, "provider": provider, "aspect_ratio": aspect_ratio, }, }

if reference_image_url:
    payload["input"]["reference_image_url"] = reference_image_url
if tail_image_url:
    payload["input"]["tail_image_url"] = tail_image_url

response = requests.post(
    "https://api.heygen.com/v1/workflows/executions",
    headers={
        "X-Api-Key": os.environ["HEYGEN_API_KEY"],
        "Content-Type": "application/json",
    },
    json=payload,
)

data = response.json()
return data["data"]["execution_id"]

Response Format

{ "data": { "execution_id": "node-gw-v1d2e3o4", "status": "submitted" } }

Check Status

Endpoint

GET https://api.heygen.com/v1/workflows/executions/{execution_id}

curl

curl -X GET "https://api.heygen.com/v1/workflows/executions/node-gw-v1d2e3o4"
-H "X-Api-Key: $HEYGEN_API_KEY"

Response Format (Completed)

{ "data": { "execution_id": "node-gw-v1d2e3o4", "status": "completed", "output": { "video": { "video_url": "https://resource.heygen.ai/generated/video.mp4", "video_id": "abc123" }, "asset_id": "asset-xyz789" } } }

Polling for Completion

async function generateVideoAndWait( input: GenerateVideoInput, maxWaitMs = 600000, pollIntervalMs = 10000 ): Promise<{ video_url: string; video_id: string; asset_id: string }> { const executionId = await generateVideo(input); console.log(Submitted video generation: ${executionId});

const startTime = Date.now(); while (Date.now() - startTime < maxWaitMs) { const response = await fetch( https://api.heygen.com/v1/workflows/executions/${executionId}, { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } } ); const { data } = await response.json();

switch (data.status) {
  case "completed":
    return {
      video_url: data.output.video.video_url,
      video_id: data.output.video.video_id,
      asset_id: data.output.asset_id,
    };
  case "failed":
    throw new Error(data.error?.message || "Video generation failed");
  case "not_found":
    throw new Error("Workflow not found");
  default:
    await new Promise((r) => setTimeout(r, pollIntervalMs));
}

}

throw new Error("Video generation timed out"); }

Usage Examples

Simple Text-to-Video

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A person walking through a sunlit park, shallow depth of field" } }'

Image-to-Video

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "Animate this product photo with a slow zoom and soft particle effects", "reference_image_url": "https://example.com/product-photo.png", "provider": "kling_pro" } }

Vertical Format for Social Media

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A trendy coffee shop interior, camera slowly panning across the counter", "aspect_ratio": "9:16", "provider": "veo_3_1" } }

Fast Generation with LTX

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "Abstract colorful shapes morphing and flowing", "provider": "ltx_distilled" } }

Best Practices

• Be descriptive in prompts — include camera movement, lighting, style, and mood details

• Default to VEO 3.1 for highest quality; use ltx_distilled or veo3_fast when speed matters

• Use reference images for image-to-video generation — great for animating product photos or still images

• Video generation is the slowest workflow — allow up to 5 minutes, poll every 10 seconds

• Aspect ratio matters — use 9:16 for social media stories/reels, 16:9 for landscape, 1:1 for square

• Output includes asset_id — use this to reference the generated video in other HeyGen workflows

• Output URLs are temporary — download or save generated videos promptly