Generación de Video (Multi-Pasarela)
Genera videos con IA a partir de indicaciones de texto. Soporta múltiples proveedores a través de cuatro rutas de API:
| Pasarela | Variable de Entorno | Proveedores | Herramienta |
|---|---|---|---|
| fal.ai | FAL_KEY | Seedance 2.0 (estándar + rápida), 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 Oficial | KLING_API_KEY | Kling oficial Classic, Turbo y video Omni básico | kling_official_video |
| API de Gemini | GEMINI_API_KEY / GOOGLE_API_KEY | Gemini Omni Flash (generación + edición conversacional) | gemini_omni_video |
Edición iterativa — Gemini Omni. Cuando la solicitud implica refinar un clip existente (agregar/eliminar objetos, cambiar estilo, iluminación o texto en pantalla) en lugar de regenerarlo, Gemini Omni Flash es el único proveedor en el conjunto con edición de múltiples turnos con estado. Consulta la Capa 3 gemini-omni para la guía de indicaciones autorizada (etiquetas de imagen de referencia, sintaxis de código de tiempo, reglas de indicaciones de edición) antes de escribir cualquier indicación para él.
Valor predeterminado premium preferido — Seedance 2.0. Cuando cualquier pasarela premium está configurada (FAL_KEY → seedance_video, o la ruta de Video Agent / Avatar Shots de HeyGen), Seedance 2.0 es la opción predeterminada preferida para trabajos cinematográficos, de tráiler y de clips de alta fidelidad. Es el único modelo en el conjunto con audio sincronizado nativo en una sola pasada, generación de múltiples tomas, control de cámara a nivel de director y sincronización de labios a partir de diálogos citados, y ocupa el puesto #1 en el Elo de Artificial Analysis a principios de 2026. Cambia solo cuando el usuario tenga una razón específica (presupuesto, preferencia de proveedor, estilo como VEO para paisajes fotorrealistas o Kling para un look anime específico). Consulta la Capa 3 seedance-2-0 para la guía autorizada de indicaciones y parámetros.
IMPORTANTE: Siempre usa video_selector en lugar de llamar directamente a las herramientas de los proveedores. El selector maneja las comprobaciones de disponibilidad, la comparación de costos y el fallback automático, y su motor de puntuación ya se inclina hacia Seedance 2.0 para intenciones cinematográficas.
Autenticación
Usa la pasarela configurada que mejor se adapte a los proveedores disponibles del usuario y a sus objetivos de costo/calidad.
- HeyGen: Establece
HEYGEN_API_KEYpara acceder a la pasarela multimodelo. - fal.ai: Establece
FAL_KEYpara acceder a Kling, MiniMax y Veo a través de fal.ai. - Kling Oficial: Establece
KLING_API_KEYpara acceder a la API directa oficial de Kling a través deprovider="kling_official". - API de Gemini: Establece
GEMINI_API_KEYoGOOGLE_API_KEYpara acceder a la generación de video Gemini Omni y a la edición conversacional.
No describas ninguna pasarela como la predeterminada o la mejor opción sin verificar primero el registro y la adecuación de la tarea actual.
fal.ai Kling (kling_video, provider="kling") y Kling Oficial (kling_official_video, provider="kling_official") son rutas diferentes. No reutilices las URL de la cola de fal.ai, FAL_KEY o el comportamiento de carga de imágenes cuando se selecciona el proveedor oficial.
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": "Una toma de dron volando sobre una ciudad costera al atardecer"}}'
Flujo de Trabajo Predeterminado
- Llama a
POST /v1/workflows/executionsconworkflow_type: "GenerateVideoNode"y tu indicación - Recibe un
execution_iden la respuesta - Consulta
GET /v1/workflows/executions/{id}cada 10 segundos hasta que el estado seacompleted - Usa la
video_urldevuelta de la salida
Ejecutar Generación de Video
Endpoint
POST https://api.heygen.com/v1/workflows/executions
Campos de Solicitud
| Campo | Tipo | Obl. | Descripción |
|---|---|---|---|
workflow_type | string | S | Debe ser "GenerateVideoNode" |
input.prompt | string | S | Descripción de texto del video a generar |
input.provider | string | Proveedor de generación de video (predeterminado: "veo_3_1"). Ver Proveedores a continuación. | |
input.aspect_ratio | string | Relación de aspecto (predeterminado: "16:9"). Valores comunes: "16:9", "9:16", "1:1" | |
input.reference_image_url | string | URL de imagen de referencia para generación de video a partir de imagen | |
input.tail_image_url | string | URL de imagen final para guía del último fotograma | |
input.config | object | Anulaciones de configuración específicas del proveedor |
Proveedores
| Proveedor | Valor | Descripción |
|---|---|---|
| VEO 3.1 | "veo_3_1" | Google VEO 3.1 (predeterminado, mayor calidad) |
| VEO 3.1 Rápida | "veo_3_1_fast" | Variante más rápida de VEO 3.1 |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Rápida | "veo3_fast" | Variante más rápida de VEO 3 |
| VEO 2 | "veo2" | Google VEO 2 |
| Kling Pro | "kling_pro" | Modelo Kling Pro |
| Kling V2 | "kling_v2" | Modelo 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 Destilado | "ltx_distilled" | LTX Destilado (más rápido) |
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": "Una toma de dron volando sobre una ciudad costera a la hora dorada, iluminación cinematográfica",
"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"]
Formato de Respuesta
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "submitted"
}
}
Verificar Estado
Endpoint
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"
Formato de Respuesta (Completado)
{
"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"
}
}
}
Sondeo hasta Completar
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(`Generación de video enviada: ${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 || "La generación de video falló");
case "not_found":
throw new Error("Flujo de trabajo no encontrado");
default:
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("La generación de video excedió el tiempo de espera");
}
Ejemplos de Uso
Texto a Video Simple
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": "Una persona caminando por un parque soleado, profundidad de campo reducida"
}
}'
Imagen a Video
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Anima esta foto de producto con un zoom lento y efectos de partículas suaves",
"reference_image_url": "https://example.com/product-photo.png",
"provider": "kling_pro"
}
}
Formato Vertical para Redes Sociales
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Interior de una cafetería moderna, cámara desplazándose lentamente sobre el mostrador",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Generación Rápida con LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Formas coloridas abstractas que se transforman y fluyen",
"provider": "ltx_distilled"
}
}
Mejores Prácticas
- Sé descriptivo en las indicaciones — incluye movimiento de cámara, iluminación, estilo y detalles de ambiente
- Usa Seedance 2.0 (a través de
seedance_video) como predeterminado para trabajos cinematográficos y con mucho movimiento cuandoFAL_KEYesté configurado — audio sincronizado en una sola pasada, múltiples tomas, sincronización de labios, cámara a nivel de director. Usa VEO 3.1 / Sora V2 Pro cuando el usuario quiera específicamente el personaje en movimiento de Google u OpenAI; usaltx_distilledoveo3_fastsolo cuando la velocidad sea la restricción estricta - Usa imágenes de referencia para la generación de video a partir de imagen — ideal para animar fotos de productos o imágenes fijas
- La generación de video es el flujo de trabajo más lento — permite hasta 5 minutos, consulta cada 10 segundos
- La relación de aspecto importa — usa
9:16para historias/reels de redes sociales,16:9para paisaje,1:1para cuadrado - La salida incluye
asset_id— úsalo para referenciar el video generado en otros flujos de trabajo de HeyGen - Las URL de salida son temporales — descarga o guarda los videos generados rápidamente