Back to Details

ai-video-gen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Video Generation (Multi-Gateway)

AI视频生成（多网关）

Generate AI videos from text prompts. Supports multiple providers via four API paths:
GatewayEnv VariableProvidersTool
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
Kling Official
KLING_API_KEY
Kling official Classic, Turbo, and basic Omni video
kling_official_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.
根据文本提示生成AI视频，通过四个API路径支持多个提供商：
网关环境变量提供商工具
fal.ai
FAL_KEY
Seedance 2.0（标准版+极速版）、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
Kling官方
KLING_API_KEY
Kling官方经典版、极速版及基础Omni视频
kling_official_video
Gemini API
GEMINI_API_KEY
/ 
GOOGLE_API_KEY
Gemini Omni Flash（生成+对话式编辑）
gemini_omni_video
迭代式编辑——Gemini Omni。当需求是优化现有片段（添加/移除对象、重新风格化、更改灯光或屏幕文字）而非重新生成时，Gemini Omni Flash是当前支持多轮有状态编辑的唯一提供商。在为其编写任何提示之前，请查看第3层
gemini-omni
中的权威提示指南（参考图像标签、时间码语法、编辑提示规则）。
首选高级默认模型——Seedance 2.0。当配置了任意高级网关时（
FAL_KEY
→ 
seedance_video
，或HeyGen的Video Agent / Avatar Shots路径），Seedance 2.0是制作电影级、预告片级及高保真片段的首选默认模型。它是当前唯一支持单通道原生同步音频、多镜头生成、导演级相机控制以及引用对话唇形同步的模型，截至2026年初在Artificial Analysis Elo排名中位列第一。仅当用户有特定理由（预算、提供商偏好、风格适配，如使用VEO生成逼真风景或Kling生成特定动漫风格）时，才切换其他模型。请查看第3层
seedance-2-0
中的权威提示和参数指南。
重要提示： 请始终使用
video_selector
而非直接调用提供商工具。该选择器会处理可用性检查、成本对比和自动降级，其评分引擎已针对电影级需求优先推荐Seedance 2.0。

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.
  • 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.
bash
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"}}'
选择与用户可用提供商及成本/质量目标最匹配的已配置网关。
  • HeyGen： 设置
    HEYGEN_API_KEY
    以访问多模型网关。
  • fal.ai： 设置
    FAL_KEY
    以通过fal.ai访问Kling、MiniMax和Veo。
  • Kling官方： 设置
    KLING_API_KEY
    ，通过
    provider="kling_official"
    访问Kling官方直连API。
  • Gemini API： 设置
    GEMINI_API_KEY
    或
    GOOGLE_API_KEY
    以访问Gemini Omni视频生成和对话式编辑功能。
在未检查注册信息和当前任务适配性之前，请勿将任何网关描述为默认或首选选项。
fal.ai Kling（
kling_video
，
provider="kling"
）和Kling官方（
kling_official_video
，
provider="kling_official"
）是不同路径。当选择官方提供商时，请勿复用fal.ai队列URL、
FAL_KEY
或图像上传行为。
bash
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
  1. 调用
    POST /v1/workflows/executions
    ，传入
    workflow_type: "GenerateVideoNode"
    和你的提示词
  2. 在响应中获取
    execution_id
  3. 每10秒轮询一次
    GET /v1/workflows/executions/{id}
    ，直到状态变为
    completed
  4. 使用返回结果中
    output
    里的
    video_url

Execute Video Generation

执行视频生成

Endpoint

端点

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

Request Fields

请求字段

FieldTypeReqDescription
workflow_type
stringYMust be 
"GenerateVideoNode"
input.prompt
stringYText description of the video to generate
input.provider
stringVideo generation provider (default: 
"veo_3_1"
). See Providers below.
input.aspect_ratio
stringAspect ratio (default: 
"16:9"
). Common values: 
"16:9"
, 
"9:16"
, 
"1:1"
input.reference_image_url
stringReference image URL for image-to-video generation
input.tail_image_url
stringTail image URL for last-frame guidance
input.config
objectProvider-specific configuration overrides
字段类型必填描述
workflow_type
string是必须为
"GenerateVideoNode"
input.prompt
string是要生成视频的文本描述
input.provider
string视频生成提供商（默认值：
"veo_3_1"
），详见下方提供商列表
input.aspect_ratio
string宽高比（默认值：
"16:9"
），常见值：
"16:9"
, 
"9:16"
, 
"1:1"
input.reference_image_url
string图像转视频生成所用的参考图像URL
input.tail_image_url
string用于最后一帧引导的尾部图像URL
input.config
object提供商特定的配置覆盖项

Providers

提供商

ProviderValueDescription
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)
提供商值描述
VEO 3.1
"veo_3_1"
Google VEO 3.1（默认，最高质量）
VEO 3.1 极速版
"veo_3_1_fast"
更快的VEO 3.1变体
VEO 3
"veo3"
Google VEO 3
VEO 3 极速版
"veo3_fast"
更快的VEO 3变体
VEO 2
"veo2"
Google VEO 2
Kling Pro
"kling_pro"
Kling Pro模型
Kling V2
"kling_v2"
Kling V2模型
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（最快）

curl

curl示例

bash
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"
    }
  }'
bash
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

TypeScript示例

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;
}
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

Python示例

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"]
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

响应格式

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

Check Status

检查状态

Endpoint

端点

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

curl

curl示例

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

Response Format (Completed)

完成状态响应格式

json
{
  "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"
    }
  }
}
json
{
  "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

轮询等待完成

typescript
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");
}
typescript
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

简单文本转视频

bash
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"
    }
  }'
bash
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

图像转视频

json
{
  "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"
  }
}
json
{
  "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

社交媒体竖版格式

json
{
  "workflow_type": "GenerateVideoNode",
  "input": {
    "prompt": "A trendy coffee shop interior, camera slowly panning across the counter",
    "aspect_ratio": "9:16",
    "provider": "veo_3_1"
  }
}
json
{
  "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

使用LTX快速生成

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

Best Practices

最佳实践

  1. Be descriptive in prompts — include camera movement, lighting, style, and mood details
  2. Default to Seedance 2.0 (via 
    seedance_video
    ) for cinematic and motion-led work     when 
    FAL_KEY
    is set — single-pass synced audio, multi-shot, lip-sync, director-level camera. Use VEO 3.1 / Sora V2 Pro when the user specifically wants Google or OpenAI motion character; use 
    ltx_distilled
    or 
    veo3_fast
    only when speed is the hard constraint
  3. Use reference images for image-to-video generation — great for animating product photos or still images
  4. Video generation is the slowest workflow — allow up to 5 minutes, poll every 10 seconds
  5. Aspect ratio matters — use 
    9:16
    for social media stories/reels, 
    16:9
    for landscape, 
    1:1
    for square
  6. Output includes 
    asset_id
     — use this to reference the generated video in other HeyGen workflows
  7. Output URLs are temporary — download or save generated videos promptly
  1. 提示词要详细——包含相机运动、灯光、风格和氛围细节
  2. 当配置
    FAL_KEY
    时，电影级和运动主导的工作默认使用Seedance 2.0（通过
    seedance_video
    ）    ——支持单通道同步音频、多镜头、唇形同步、导演级相机控制。仅当用户明确需要Google或OpenAI的运动风格时，使用VEO 3.1 / Sora V2 Pro；仅当速度为硬性约束时，使用
    ltx_distilled
    或
    veo3_fast
  3. 图像转视频生成使用参考图像——非常适合为产品照片或静态图像添加动画
  4. 视频生成是最慢的工作流——允许最长5分钟等待时间，每10秒轮询一次
  5. 宽高比很重要——社交媒体故事/短视频使用
    9:16
    ，横屏使用
    16:9
    ，方形使用
    1:1
  6. 输出包含
    asset_id
    ——可用于在其他HeyGen工作流中引用生成的视频
  7. 输出URL是临时的——请及时下载或保存生成的视频