ai-video-gen

$27

• 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