API per generare video con l'IA: text-to-video in TypeScript

Un’API di generazione video IA trasforma un prompt in video tramite un’esecuzione asincrona: avvia Video Generator, controlla l’ID restituito e leggi l’URL del video dalle risorse dell’esecuzione completata. L’SDK TypeScript di Pipe2 espone direttamente queste operazioni pubbliche, perciò un’integrazione text-to-video può rimanere compatta.

Eseguire text-to-video con l’SDK TypeScript

Installa @pipe2-ai/sdk, inserisci un token Pipe2 in PIPE2_TOKEN ed esegui questo modulo con Node. L’esempio usa una sola azione osservabile e una breve sequenza temporale per dare al generatore un’inquadratura chiara da produrre.

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 stessa richiesta alla pipeline, separata dall’autenticazione e dal controllo dello stato, è:

{
  "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 documentazione dell’SDK TypeScript descrive installazione, autenticazione, esecuzioni delle pipeline, stato, sottoscrizioni, caricamenti e operazioni sui crediti.

Capire il flusso di esecuzione, controllo e risorsa

RunPipeline riceve lo slug della pipeline e un oggetto JSON di input. Restituisce gli identificatori della nuova esecuzione invece di tenere aperta la richiesta fino al termine della generazione. Conserva run_pipeline.run_id, perché è l’identificatore usato da GetPipelineRun.

Ogni controllo restituisce il record aggiornato. Un’esecuzione completed può contenere le risorse generate e l’esempio stampa l’URL della prima. Un’esecuzione failed include un messaggio di errore che l’integrazione deve mostrare o registrare. In produzione, imposta anche un limite di tempo complessivo e considera un’esecuzione assente come errore, anziché continuare all’infinito.

Per un piccolo script è sufficiente controllare ogni pochi secondi. Se un servizio richiede aggiornamenti continui, l’SDK offre anche WatchPipelineRun come iterabile asincrono dello stesso stato.

Iniziare con l’input valido più semplice

La richiesta contiene solo prompt, l’input utile minimo per text-to-video, e lascia il selettore del modello su Auto. Video Generator può anche usare fotogrammi iniziali o finali e riferimenti facoltativi di immagini, video o audio. Durata, risoluzione, proporzioni e limiti dei riferimenti supportati dipendono dal percorso di modello compatibile.

Aggiungi un controllo solo se il prodotto lo richiede. Potrebbero servire proporzioni specifiche per la destinazione, un’immagine per preservare l’identità o una clip più lunga che richieda un altro percorso compatibile. Prima di inviare una richiesta più costosa o ricca di media, chiama EstimatePipelineCost con gli stessi pipeline_slug e input.

Scrivere prompt adatti a una singola inquadratura

Un’API non elimina la necessità di un brief preciso. Descrivi l’azione visibile, il comportamento della camera, l’ambiente, i tempi e il suono. Mantieni l’azione fisicamente realizzabile nella durata prevista.

L’esempio usa due intervalli temporali ma un solo evento continuo: l’aeroplano gira e poi atterra. Non richiede cambi di luogo, vari personaggi o montaggi. È quindi più facile controllare la continuità del movimento, la forma dell’oggetto, l’atterraggio e l’audio.

Per una produzione più ampia, genera e approva le singole inquadrature prima di montarle. La guida su come creare video con l’IA tratta pianificazione, revisione, montaggio, sottotitoli e finitura dopo questa chiamata API.

Gestire esplicitamente autenticazione ed errori

Crea il client con un token Pipe2 e conservalo sul server o in una variabile d’ambiente locale protetta. Non inserirlo nel codice inviato al browser, non registrarlo nel repository e non includerlo nell’input della pipeline.

Separa gli errori di invio dagli errori dell’esecuzione. Una richiesta può fallire prima dell’avvio perché non autenticata, non valida o incapace di riservare i crediti necessari. Un’esecuzione creata correttamente può poi terminare con failed; controlla error_message. Usa gli URL delle risorse solo dopo lo stato completed.

Se il flusso parte da un’immagine, caricala o referenziala tramite il flusso di risorse documentato nell’SDK e consulta la guida pratica per trasformare un’immagine in video.