视频生成 (HeyGen API)

根据文本提示生成 AI 视频。支持多种提供商（VEO 3.1、Kling、Sora、Runway、Seedance），可配置宽高比，并支持可选的参考图像用于图像到视频的生成。

身份验证

所有请求都需要 X-Api-Key 请求头。设置 HEYGEN_API_KEY 环境变量。

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": "无人机拍摄日落时分的沿海城市"}}'

默认工作流程

1. 使用 workflow_type: "GenerateVideoNode" 和你的提示词调用 POST /v1/workflows/executions
2. 在响应中获取 execution_id
3. 每 10 秒轮询 GET /v1/workflows/executions/{id}，直到状态变为 completed
4. 从输出中获取返回的 video_url

执行视频生成

端点

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

请求字段

提供商

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": "无人机拍摄日落黄金时刻的沿海城市，电影级照明",
      "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"]

响应格式

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

检查状态

端点

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"

响应格式（完成）

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

轮询完成

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(`已提交视频生成：${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 || "视频生成失败");
      case "not_found":
        throw new Error("工作流未找到");
      default:
        await new Promise((r) => setTimeout(r, pollIntervalMs));
    }
  }

  throw new Error("视频生成超时");
}

使用示例

简单文本生成视频

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": "一个人在阳光明媚的公园里行走，浅景深"
    }
  }'

图像生成视频

{
  "workflow_type": "GenerateVideoNode",
  "input": {
    "prompt": "让这张产品照片动起来，缓慢推近并添加柔和粒子效果",
    "reference_image_url": "https://example.com/product-photo.png",
    "provider": "kling_pro"
  }
}

社交媒体竖版格式

{
  "workflow_type": "GenerateVideoNode",
  "input": {
    "prompt": "时尚咖啡店室内，镜头缓慢划过吧台",
    "aspect_ratio": "9:16",
    "provider": "veo_3_1"
  }
}

使用 LTX 快速生成

{
  "workflow_type": "GenerateVideoNode",
  "input": {
    "prompt": "抽象彩色形状流动变形",
    "provider": "ltx_distilled"
  }
}

最佳实践

1. 提示词要描述详细 — 包含相机运动、光线、风格和氛围细节
2. 默认使用 VEO 3.1 以获得最高质量；当速度重要时使用 ltx_distilled 或 veo3_fast
3. 使用参考图像 进行图像到视频生成 — 非常适合动画化产品照片或静态图像
4. 视频生成是最慢的工作流 — 最多允许 5 分钟，每 10 秒轮询一次
5. 宽高比很重要 — 社交媒体故事/短视频使用 9:16，横屏使用 16:9，正方形使用 1:1
6. 输出包含 asset_id — 在 HeyGen 的其他工作流中使用此 ID 引用生成的视频
7. 输出 URL 是临时的 — 及时下载或保存生成的视频