影片生成 (多重閘道)
從文字提示詞生成 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 Official | 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 以取得權威提示詞指南 (參考圖片標籤、時間碼語法、編輯提示詞規則)。
首選 Premium 預設 — Seedance 2.0。 當任何 Premium 閘道已配置 (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 Official: 設定
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 Official (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"}}'
預設工作流程
- 使用
workflow_type: "GenerateVideoNode"和您的提示詞呼叫POST /v1/workflows/executions - 在回應中收到一個
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— 使用此 ID 在其它 HeyGen 工作流程中引用生成的影片 - 輸出 URL 是暫時的 — 請及時下載或儲存生成的影片