视频生成(多网关)
从文本提示词生成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官方 Classic、Turbo和基础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。
身份验证
使用最适合用户可用提供商和成本/质量目标的已配置网关。
- 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或图像上传行为。
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"}}'
默认工作流程
- 调用
POST /v1/workflows/executions,workflow_type: "GenerateVideoNode"并提供提示词 - 在响应中接收
execution_id - 每10秒轮询
GET /v1/workflows/executions/{id},直到状态为completed - 使用输出中返回的
video_url
执行视频生成
端点
POST https://api.heygen.com/v1/workflows/executions
请求字段
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
workflow_type | string | Y | 必须为 "GenerateVideoNode" |
input.prompt | string | Y | 要生成的视频的文本描述 |
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 | 提供商特定的配置覆盖 |
提供商
| 提供商 | 值 | 描述 |
|---|---|---|
| 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 -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"]
响应格式
{
"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(`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");
}
使用示例
简单的文本到视频
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"
}
}'
图像到视频
{
"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"
}
}
社交媒体竖版格式
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "A trendy coffee shop interior, camera slowly panning across the counter",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
使用LTX进行快速生成
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Abstract colorful shapes morphing and flowing",
"provider": "ltx_distilled"
}
}
最佳实践
- 提示词要详细 — 包括摄像机运动、光照、风格和情绪细节
- 当设置了
FAL_KEY时,优先使用Seedance 2.0(通过seedance_video)用于电影和运动主导的工作 — 单通道同步音频、多镜头、唇形同步、导演级摄像机。当用户特别想要Google或OpenAI的运动角色时,使用VEO 3.1 / Sora V2 Pro;仅当速度是硬约束时才使用ltx_distilled或veo3_fast - 使用参考图像 进行图像到视频生成 — 非常适合为产品照片或静态图像添加动画
- 视频生成是最慢的工作流程 — 最多等待5分钟,每10秒轮询一次
- 宽高比很重要 — 社交媒体故事/短视频使用
9:16,横屏使用16:9,正方形使用1:1 - 输出包含
asset_id— 使用它来引用其他HeyGen工作流程中生成的视频 - 输出URL是临时的 — 及时下载或保存生成的视频