API de generación de vídeo con IA: texto a vídeo con TypeScript

Una API de generación de vídeo con IA convierte un prompt en vídeo mediante una ejecución asíncrona: inicia Video Generator, consulta el ID recibido y lee la URL del vídeo entre los recursos de la ejecución completada. El SDK de TypeScript de Pipe2 expone directamente estas operaciones públicas, por lo que una integración de texto a vídeo puede ser compacta.

Ejecutar texto a vídeo con el SDK de TypeScript

Instala @pipe2-ai/sdk, guarda un token de Pipe2 en PIPE2_TOKEN y ejecuta este módulo con Node. El ejemplo plantea una sola acción observable y una cronología breve para que el generador tenga un plano claro que producir.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  prompt: '[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music.',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'video-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Video generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

La misma solicitud al pipeline, separada de la autenticación y de las consultas de estado, es:

{
  "pipeline_slug": "video-generator",
  "input": {
    "prompt": "[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music."
  }
}

La documentación del SDK de TypeScript explica la instalación, la autenticación, las ejecuciones, la consulta de estado, las suscripciones, las subidas y las operaciones de créditos.

Entender el flujo de ejecución, consulta y recurso

RunPipeline recibe el slug del pipeline y un objeto JSON de entrada. Devuelve los identificadores de la nueva ejecución en lugar de mantener abierta la petición hasta que termine la generación. Conserva run_pipeline.run_id: es el identificador que utiliza GetPipelineRun.

Cada consulta devuelve el registro actual. Una ejecución con estado completed puede incluir los recursos generados, y el ejemplo imprime la URL del primero. Una ejecución con estado failed incluye un mensaje de error que conviene mostrar o registrar. En producción, establece además un tiempo límite global y considera un error que la ejecución no exista, en vez de consultar indefinidamente.

Consultar cada pocos segundos basta para un script pequeño. Si un servicio necesita actualizaciones en directo, el SDK ofrece también WatchPipelineRun como iterable asíncrono sobre el mismo estado.

Empezar con la entrada válida más sencilla

La solicitud solo incluye prompt, la entrada útil mínima para texto a vídeo, y deja el selector de modelo en Auto. Video Generator también admite fotogramas iniciales o finales y referencias opcionales de imagen, vídeo o audio. Las duraciones, resoluciones, relaciones de aspecto y cantidades de referencias compatibles dependen de la ruta de modelo elegida.

Añade un control únicamente cuando el producto lo necesite. Puede ser imprescindible una relación de aspecto concreta, una imagen para conservar la identidad o un clip más largo que requiera otra ruta compatible. Antes de enviar una solicitud más costosa o con más medios, llama a EstimatePipelineCost con el mismo pipeline_slug y el mismo input.

Escribir prompts adecuados para un solo plano

Una API no sustituye un buen briefing. Describe la acción visible, el comportamiento de la cámara, el entorno, los tiempos y el sonido, y limita la acción a lo que pueda ocurrir físicamente en ese intervalo.

El ejemplo usa dos tramos temporales dentro de un único suceso continuo: el avión gira y luego aterriza. No exige cambiar de lugar, coordinar varios personajes ni encadenar montajes. Así es más fácil revisar la continuidad, la forma del objeto, el aterrizaje y el audio.

Para una producción mayor, genera y aprueba cada plano por separado antes de montarlos. La guía para crear vídeos con IA explica la planificación, la revisión, el montaje, los subtítulos y el acabado posterior a esta llamada.

Tratar de forma explícita la autenticación y los fallos

Crea el cliente con un token de Pipe2 y mantenlo en el servidor o en una variable de entorno local segura. No lo incluyas en código enviado al navegador, en el repositorio ni dentro de la entrada del pipeline.

Distingue los errores de envío de los fallos de ejecución. La solicitud puede fallar antes de crear una ejecución si no está autenticada, no es válida o no puede reservar los créditos necesarios. Una ejecución creada correctamente puede acabar después con failed; consulta error_message. Usa las URL de los recursos solo cuando el estado sea completed.

Si el proceso comienza con una imagen, súbela o referénciala mediante el flujo de recursos documentado por el SDK y consulta la guía práctica para convertir una imagen en vídeo.