動画生成(マルチゲートウェイ)
テキストプロンプトからAI動画を生成します。4つの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はこの機能群の中で唯一、ステートフルなマルチターン編集を提供するプロバイダーです。Gemini Omni用のプロンプトを作成する前に、レイヤー3 gemini-omni の権威あるプロンプトガイド(参照画像タグ、タイムコード構文、編集プロンプトルール)を参照してください。
推奨プレミアムデフォルト — Seedance 2.0。 プレミアムゲートウェイ(FAL_KEY → seedance_video、またはHeyGenのVideo Agent / Avatar Shotsパス)が設定されている場合、Seedance 2.0はシネマティック、トレーラー、高忠実度クリップワークの推奨デフォルトです。これは、この機能群の中で単一パスでのネイティブ同期オーディオ、マルチショット生成、ディレクターレベルのカメラ制御、引用されたダイアログからのリップシンクを提供する唯一のモデルであり、2026年初頭時点でArtificial Analysis Eloで第1位にランクされています。ユーザーに特定の理由(予算、プロバイダーの好み、VEOのようなフォトリアルな風景やKlingのような特定のアニメスタイルなど)がある場合にのみ、Seedance 2.0から切り替えてください。Seedance 2.0の権威あるプロンプトおよびパラメータガイドについては、レイヤー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": "海岸沿いの都市の夕日をドローンで撮影した映像"}}'
デフォルトワークフロー
POST /v1/workflows/executionsをworkflow_type: "GenerateVideoNode"とプロンプトとともに呼び出します- 応答で
execution_idを受け取ります - ステータスが
completedになるまで、GET /v1/workflows/executions/{id}を10秒ごとにポーリングします - 出力から返された
video_urlを使用します
動画生成の実行
エンドポイント
POST https://api.heygen.com/v1/workflows/executions
リクエストフィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
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 | プロバイダー固有の設定オーバーライド |
プロバイダー
| プロバイダー | 値 | 説明 |
|---|---|---|
| VEO 3.1 | "veo_3_1" | Google VEO 3.1(デフォルト、最高品質) |
| VEO 3.1 Fast | "veo_3_1_fast" | より高速なVEO 3.1バリアント |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Fast | "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": "海岸沿いの都市をゴールデンアワーにドローンで撮影した映像、シネマティックな照明",
"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"
}
}
ベストプラクティス
- プロンプトは具体的に記述する — カメラの動き、照明、スタイル、雰囲気の詳細を含めます
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は一時的である — 生成された動画は速やかにダウンロードまたは保存してください