Generación de Video (Múltiples Pasarelas)
Genera videos AI a partir de indicaciones de texto. Compatible con 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ápido), 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 (añadir/eliminar objetos, cambiar estilo, modificar iluminación o texto en pantalla) en lugar de regenerarlo, Gemini Omni Flash es el único proveedor en el conjunto con edición iterativa de múltiples turnos y estado. Consulta la Capa 3 gemini-omni para la guía autorizada de indicaciones (etiquetas de imagen de referencia, sintaxis de código de tiempo, reglas 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 el valor predeterminado preferido para trabajos cinematográficos, de tráiler y 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álogo citado, y ocupa el #1 en Artificial Analysis Elo a principios de 2026. Cambia solo cuando el usuario tenga una razón específica (presupuesto, preferencia de proveedor, ajuste estilístico 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: Usa siempre video_selector en lugar de llamar a las herramientas del proveedor directamente. El selector maneja las comprobaciones de disponibilidad, la comparación de costos y la reasignación automática, 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 los objetivos de costo/calidad.
- HeyGen: Establece
HEYGEN_API_KEYpara acceder a la pasarela de múltiples modelos. - 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 oficial directa de Kling medianteprovider="kling_official". - API de Gemini: Establece
GEMINI_API_KEYoGOOGLE_API_KEYpara acceder a la generación de video Gemini Omni y 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 a 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 URLs de la cola de fal.ai, FAL_KEY o el comportamiento de carga de imágenes cuando se seleccione 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": "Un plano de dron sobrevolando 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 del resultado
Ejecutar Generación de Video
Endpoint
POST https://api.heygen.com/v1/workflows/executions
Campos de Solicitud
| Campo | Tipo | Oblig. | 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"). Consulta 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 generar imagen a video | |
input.tail_image_url | string | URL de imagen final para guiar el ú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ápido | "veo_3_1_fast" | Variante más rápida de VEO 3.1 |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Rápido | "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": "Un plano de dron sobrevolando una ciudad costera durante 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"
}
}
Consultar 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 para 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 agotó 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, poca profundidad de campo"
}
}'
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, la cámara se desplaza lentamente sobre la barra",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Generación Rápida con LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Formas abstractas y coloridas 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
- Predetermina a Seedance 2.0 (a través de
seedance_video) para trabajos cinematográficos y con movimiento cuandoFAL_KEYesté configurado: audio sincronizado en una sola pasada, múltiples tomas, sincronización de labios, cámara de nivel director. Usa VEO 3.1 / Sora V2 Pro cuando el usuario quiera específicamente el movimiento de personajes de Google o OpenAI; usaltx_distilledoveo3_fastsolo cuando la velocidad sea la restricción principal - Usa imágenes de referencia para generación de imagen a video — 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 apaisado,1:1para cuadrado - El resultado incluye
asset_id— úsalo para hacer referencia al video generado en otros flujos de trabajo de HeyGen - Las URLs de resultado son temporales — descarga o guarda los videos generados rápidamente