비디오 생성 (멀티 게이트웨이)
텍스트 프롬프트에서 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 |
권장 프리미엄 기본값 — Seedance 2.0. 프리미엄 게이트웨이가 설정되어 있을 때(FAL_KEY → seedance_video, 또는 HeyGen의 비디오 에이전트/아바타 샷 경로), Seedance 2.0은 시네마틱, 트레일러 및 고충실도 클립 작업에 선호되는 기본값입니다. 이 모델은 단일 패스 네이티브 동기화 오디오, 멀티 샷 생성, 감독 수준의 카메라 제어 및 인용된 대화의 립싱크를 지원하는 유일한 모델이며, 2026년 초 기준 Artificial Analysis Elo에서 1위를 차지했습니다. 사용자가 특정 이유(예산, 공급자 선호도, VEO의 사실적인 풍경이나 Kling의 특정 애니메이션 스타일과 같은 스타일 적합성)가 있는 경우에만 전환하십시오. 권위 있는 프롬프팅 및 매개변수 가이드는 레이어 3 seedance-2-0을 참조하십시오.
중요: 공급자 도구를 직접 호출하는 대신 항상 video_selector를 사용하십시오. 선택기는 가용성 확인, 비용 비교 및 자동 폴백을 처리하며, 점수 엔진은 이미 시네마틱 의도에 대해 Seedance 2.0을 선호하도록 설정되어 있습니다.
인증
사용 가능한 공급자와 비용/품질 목표에 가장 잘 맞는 설정된 게이트웨이를 사용하십시오.
- HeyGen:
HEYGEN_API_KEY를 설정하여 멀티 모델 게이트웨이에 액세스합니다. - fal.ai:
FAL_KEY를 설정하여 Kling, MiniMax 및 Veo에 액세스합니다.
레지스트리와 현재 작업 적합성을 먼저 확인하지 않고 어떤 게이트웨이를 기본값 또는 최상위 선택으로 설명하지 마십시오.
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"와 프롬프트를 사용하여POST /v1/workflows/executions호출- 응답에서
execution_id받기 - 상태가
completed가 될 때까지 10초마다GET /v1/workflows/executions/{id}폴링 - 출력에서 반환된
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": "골든 아워에 해안 도시 위를 비행하는 드론 샷, 시네마틱 조명",
"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"
}
}
모범 사례
- 프롬프트를 자세하게 작성 — 카메라 움직임, 조명, 스타일, 분위기 세부 정보 포함
- 시네마틱 및 모션 중심 작업의 경우 기본적으로 Seedance 2.0 사용 (
seedance_video통해) (FAL_KEY설정 시) — 단일 패스 동기화 오디오, 멀티 샷, 립싱크, 감독 수준의 카메라. 사용자가 특별히 Google 또는 OpenAI 모션 캐릭터를 원하는 경우 VEO 3.1 / Sora V2 Pro 사용; 속도가 중요한 제약 조건인 경우에만ltx_distilled또는veo3_fast사용 - 이미지-투-비디오 생성을 위해 참조 이미지 사용 — 제품 사진이나 정지 이미지 애니메이션에 적합
- 비디오 생성은 가장 느린 워크플로우 — 최대 5분까지 허용, 10초마다 폴링
- 종횡비 중요 — 소셜 미디어 스토리/릴에는
9:16, 가로에는16:9, 정사각형에는1:1사용 - 출력에는
asset_id포함 — 다른 HeyGen 워크플로우에서 생성된 비디오를 참조하는 데 사용 - 출력 URL은 임시적 — 생성된 비디오를 즉시 다운로드하거나 저장