ai-video-gen Checked

• **HeyGen:** Set HEYGEN_API_KEY to access the multi-model gateway.
• **fal.ai:** Set FAL_KEY to access Kling, MiniMax, and Veo through fal.ai.
• **Kling Official:** Set KLING_API_KEY to access Kling's official direct API via provider="kling_official".
• **Gemini API:** Set GEMINI_API_KEY or GOOGLE_API_KEY to access Gemini Omni video generation and conversational editing.

Do not describe any gateway as the default or top choice without checking the registry and current task fit first.

fal.ai Kling (kling_video, provider="kling") and Kling Official (kling_official_video, provider="kling_official") are different paths. Do not reuse fal.ai queue URLs, FAL_KEY, or image upload behavior when the official provider is selected.

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

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

2. Receive a execution_id in the response

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

4. 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 Completio