KI-Videogenerierungs-API: Text-zu-Video mit TypeScript

Eine KI-Videogenerierungs-API macht aus einem Prompt über einen asynchronen Run ein Video: Video Generator starten, die zurückgegebene Run-ID abfragen und nach Abschluss die Video-URL aus den Assets lesen. Das TypeScript-SDK von Pipe2 stellt diese öffentlichen Operationen direkt bereit, sodass eine Text-zu-Video-Integration klein bleiben kann.

Text-zu-Video mit dem TypeScript-SDK ausführen

Installiere @pipe2-ai/sdk, lege ein Pipe2-Token in PIPE2_TOKEN ab und führe dieses Modul mit Node aus. Das Beispiel beschreibt eine einzige beobachtbare Handlung mit kurzer Zeitleiste, damit der Generator eine klar umrissene Einstellung erzeugen kann.

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));
}

Dieselbe Pipeline-Anfrage ohne Authentifizierung und Polling sieht so aus:

{
  "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."
  }
}

Die Dokumentation des TypeScript-SDKs behandelt Installation, Authentifizierung, Pipeline-Runs, Statusabfragen, Subscriptions, Uploads und Credit-Operationen.

Run-, Polling- und Asset-Ablauf verstehen

RunPipeline erhält den Pipeline-Slug und ein JSON-Eingabeobjekt. Statt die Anfrage bis zum Ende der Videogenerierung offen zu halten, gibt die Operation Kennungen für den neuen Run zurück. Bewahre run_pipeline.run_id auf, denn GetPipelineRun verwendet genau diese ID.

Jede Abfrage liefert den aktuellen Run-Datensatz. Ein Run mit completed kann die erzeugten Assets enthalten; das Beispiel gibt die URL des ersten Assets aus. Ein Run mit failed enthält eine Fehlermeldung, die eine Integration anzeigen oder protokollieren sollte. Produktionscode sollte zusätzlich ein eigenes Gesamtzeitlimit setzen und einen nicht vorhandenen Run als Fehler behandeln.

Für ein kleines Skript reicht Polling alle paar Sekunden. Benötigt ein Dienst laufende Aktualisierungen, stellt das SDK mit WatchPipelineRun auch ein asynchrones Iterable für denselben Run-Status bereit.

Mit der einfachsten gültigen Eingabe beginnen

Die Anfrage enthält nur prompt. Das ist die kleinste sinnvolle Text-zu-Video-Eingabe und lässt die Modellauswahl auf Auto. Video Generator kann außerdem Start- oder Endbilder sowie optionale Bild-, Video- oder Audio-Referenzen verarbeiten. Unterstützte Dauer, Auflösung, Seitenverhältnis und Referenzgrenzen hängen von der kompatiblen Modellroute ab.

Füge eine Einstellung nur hinzu, wenn die Produktanforderung sie verlangt. Ein bestimmtes Seitenverhältnis kann für das Zielmedium nötig sein, ein Referenzbild für die Identität und eine längere Einstellung für eine andere kompatible Route. Vor einer teureren oder medienreichen Anfrage kann EstimatePipelineCost mit identischem pipeline_slug und input die Kosten schätzen.

Prompts für eine generierte Einstellung formulieren

Auch eine API braucht ein präzises Shot-Briefing. Beschreibe sichtbare Handlung, Kameraverhalten, Umgebung, Timing und Ton. Die Handlung sollte in der verfügbaren Zeit physisch machbar sein.

Das Beispiel nutzt zwei Zeitabschnitte, aber ein zusammenhängendes Ereignis: Der Papierflieger kreist und landet anschließend. Es verlangt weder einen Ortswechsel noch mehrere Figuren oder Schnitte. Dadurch lassen sich Bewegungskontinuität, Objektform, Landung und Ton leichter prüfen.

Für eine größere Produktion sollten einzelne Einstellungen separat erzeugt und freigegeben werden. Der Leitfaden zum Erstellen von KI-Videos behandelt Planung, Prüfung, Montage, Untertitel und den Feinschliff nach diesem API-Aufruf.

Authentifizierung und Fehler ausdrücklich behandeln

Erzeuge den Client mit einem Pipe2-Token und bewahre dieses auf dem Server oder in einer geschützten lokalen Umgebungsvariable auf. Es gehört weder in ausgelieferten Browser-Code noch in ein Repository oder in die Pipeline-Eingabe.

Unterscheide Dispatch-Fehler von späteren Run-Fehlern. Eine Anfrage kann vor dem Start scheitern, wenn sie nicht authentifiziert oder ungültig ist oder die erforderlichen Credits nicht reserviert werden können. Ein erfolgreich angelegter Run kann später den Status failed erreichen; prüfe dann error_message. Asset-URLs sollten erst bei completed verwendet werden.

Beginnt der Ablauf mit einem Bild, lade das Asset über den dokumentierten SDK-Ablauf hoch oder referenziere es und nutze den Praxisleitfaden zu Bild-zu-Video mit KI.