/ai-video-gen

name: ai-video-gen
description: |
  Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, and the Gemini API (Gemini Omni Flash).
allowed-tools: mcp__heygen__*
metadata:
  openclaw:
    requires:
      env_any:
        - HEYGEN_API_KEY
        - FAL_KEY
        - GEMINI_API_KEY
        - GOOGLE_API_KEY

Video Generation (Multi-Gateway)

Generate AI videos from text prompts. Supports multiple providers via two API gateways:

| Gateway | Env Variable | Providers | Tool | |---------|-------------|-----------|------| | **fal.ai** | `FAL_KEY` | **Seedance 2.0** (standard + fast), Kling v3/v2.1, MiniMax, VEO | `seedance_video`, `kling_video`, `minimax_video`, `veo_video` | | **HeyGen** | `HEYGEN_API_KEY` | VEO 3.1, Kling Pro, Sora v2, Runway Gen-4, Seedance Pro / Lite (1.x) | `heygen_video` | | **Gemini API** | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Gemini Omni Flash (generation + conversational editing) | `gemini_omni_video` |

**Iterative editing — Gemini Omni.** When the brief calls for *refining an existing clip* (add/remove objects, restyle, change lighting or on-screen text) rather than regenerating, Gemini Omni Flash is the only provider in the fleet with stateful multi-turn editing. See Layer 3 `gemini-omni` for the authoritative prompting guide (reference-image tags, timecode syntax, edit-prompt rules) before writing any prompt for it.

**Preferred premium default — Seedance 2.0.** When any premium gateway is configured (`FAL_KEY` → `seedance_video`, or HeyGen's Video Agent / Avatar Shots path), Seedance 2.0 is the preferred default for cinematic, trailer, and high-fidelity clip work. It is the only model in the fleet with **single-pass native synchronized audio, multi-shot generation, director-level camera control, and lip-sync from quoted dialogue**, and it ranks #1 on Artificial Analysis Elo as of early 2026. Switch off it only when the user has a specific reason (budget, provider preference, stylistic fit like VEO for photoreal landscape or Kling for specific anime look). See Layer 3 `seedance-2-0` for the authoritative prompting and parameter guide.

**IMPORTANT:** Always use `video_selector` instead of calling provider tools directly. The selector handles availability checks, cost comparison, and automatic fallback, and its scoring engine already biases toward Seedance 2.0 for cinematic intent.

Authentication

Use whichever configured gateway best matches the user's available providers and cost/quality goals.

• **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.

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

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> {
  con