Text zu Videos über die API hinzufügen: Workflows für Untertitel und Overlays

Warum Text auf Videos ein API-Designproblem ist und nicht nur ein Prompt

Text zu einem generierten Video hinzuzufügen wirkt wie eine Zeile Prompt: Beschreibe die Untertitel, sende die Anfrage, erhalte einen Clip mit Text. In der Praxis ist der Prompt jedoch nicht mehr der interessante Teil, sobald Untertitel lesbar, zeitlich getaktet, lokalisierbar oder szenenübergreifend wiederverwendbar sein müssen. Die Architektur ist es.

Es gibt zwei praktikable Wege, und sie führen zu unterschiedlichen Codebasen:

• Nativer Text zur Generierungszeit. Du lässt das Videomodell den Text als Teil der Szene rendern. Eine Anfrage, ein Asset, keine Nachbearbeitung.
• Sauberes Material plus Overlays. Du generierst zuerst Material ohne Text (oder forderst eine textlose Komposition an) und setzt Untertitel und Overlays dann in einem zweiten Rendering-Schritt zusammen.

Warum ist das mehr als eine Frage der Ästhetik? Weil alles Nachgelagerte von dieser Entscheidung abhängt. Wenn der Text in den generierten Pixeln steckt, kannst du ihn nicht einfach neu gestalten, übersetzen, zeitlich an die Sprache anpassen oder einen Tippfehler korrigieren, ohne den Clip neu zu generieren. Wenn der Text in einem separaten Overlay liegt, kontrollierst du Layout, Schriftart und Timing, aber du besitzt jetzt selbst einen Renderer und hast einen zusätzlichen Request in der Pipeline.

Der Rest dieses Leitfadens behandelt Text auf Videos als das, was er in der Produktion meist wird: ein Datenproblem (welcher Text, wo, wann) plus ein Rendering-Problem (wer ihn zeichnet). Sobald du diese beiden trennst, werden die API-Aufrufe unkompliziert, und du kannst zwischen Generierungs-Backends wechseln, ohne die Untertitel-Logik neu zu schreiben.

Ein nützliches mentales Modell ist, immer drei Dinge auseinanderzuhalten: Inhalt (der Text selbst), Timing (wann er erscheint) und Darstellung (Schriftart, Position, Stil). Die native Generierung komprimiert alle drei in einen undurchsichtigen Schritt. Overlays halten alle drei explizit und bearbeitbar. Keine der beiden ist generell besser; das Ziel ist zu wissen, worauf du dich festlegst, bevor du die Integration schreibst.

Weg eins: Nativer Bildschirmtext über Prompts zur Generierungszeit

Nativer Text bedeutet, dass das Generierungsmodell die Zeichen in die Videoframes zeichnet. Du erhältst ein einzelnes Ausgabe-Asset mit eingebranntem Text, und die Pipeline bleibt kurz: Prompt erstellen, absenden, abfragen, ausliefern.

Was in den Prompt gehört

Die vom Modell gerenderte Typografie ist unvorhersehbarer als zusammengesetzter Text, behandle den Prompt also als enge Anweisung und nicht als Ort, an dem du das gesamte Designsystem beschreibst. Praktische Hinweise:

• Halte den Text kurz. Ein paar Wörter pro Shot. Lange Sätze führen leicht zu Rechtschreibabweichungen und überfülltem Layout.
• Setze wörtliche Strings in Anführungszeichen. Wenn der Text exakt erscheinen muss, setze ihn in Anführungszeichen und verlange genau diesen Text. Vage Beschreibungen erzeugen vage Ergebnisse.
• Gib Position und Stil ausdrücklich an. „Großer weißer Text zentriert im unteren Drittel“ ist ausführbar. „Schöner Titel“ nicht.
• Ein Textelement pro Shot. Titel, Untertitel und Wasserzeichen im selben Clip zu verlangen, vervielfacht die Fehlermodi.
• Gib die Sprache an. Wenn der Text nicht Englisch ist, sag es, denn die Glyphen-Abdeckung variiert.

Was du erwarten solltest

Behandle die Ausgabe als Entwurf, nicht als Spezifikation. Selbst gute Ergebnisse können Glyphenverzerrungen, inkonsistente Abstände oder teilweise durch Bewegung verdeckte Zeichen aufweisen. Prüfe gerenderte Frames immer vor der Auslieferung; eine billige programmatische Prüfung plus ein menschlicher Blick auf die ersten und letzten Frames mit Text fängt die meisten Probleme ab.

Wann dieser Weg gewinnt

Wenn Text beiläufig und atmosphärisch ist, ist nativer Text die richtige Standardwahl: Schilder auf einer Hintergrundstraße, stilisierte Logos auf Produkten, kurze Titelkarren, die du bei Fehlern gern neu generierst. Er gewinnt auch, wenn du dir einen zweiten Rendering-Schritt schlicht nicht leisten kannst, etwa bei eng getakteten Workflows, in denen ein Request pro Clip das Budget ist.

Der Preis ist Kontrolle. Jede Änderung an Formulierung, Stil oder Timing bedeutet eine neue Generierungsanfrage, und die Ergebnisse sind zwischen Wiederholungen nicht deterministisch. Entwirf deine Prompts und deine Speicherung so, dass neu generierte Clips alte sauber ersetzen.

Weg zwei: Sauberes Material generieren und Text selbst zusammensetzen

Der Overlay-Weg teilt die Arbeit in zwei Teile. Zuerst generierst du bewusst textloses Material. Dann setzt du Untertitel und Overlays darauf zusammen, entweder mit einem Rendering-Dienst oder deiner eigenen Medien-Pipeline.

Zuerst sauberes Material generieren

Verlange eine textlose Komposition: Beschreibe Szene, Motiv, Kamerabewegung und Licht und vermeide ausdrücklich, Text auf dem Bildschirm zu verlangen. Wenn das Modell dazu neigt, Schilder oder UI-Text zu erfinden, erwähne, dass das Bild keinen lesbaren Text enthalten soll. Die Ausgabe hier ist ein Basis-Asset – ein stabiler Input, den du mit vielen Textvarianten wiederverwenden kannst.

Nachgelagerte Komposition

Der Overlay-Schritt verbraucht zwei Inputs: das Basis-Asset und eine strukturierte Untertitel-/Overlay-Nutzlast. Weil du den Renderer kontrollierst, bekommst du Eigenschaften, die Prompts nicht garantieren können:

• Bestimmte Schriftarten und -größen. Dieselbe Nutzlast rendert jedes Mal identisch, was für Markenkonsistenz wichtig ist.
• Präzises Timing. Untertitel können framegenau an Sprache, Musikbeats oder Szenenwechsel ausgerichtet werden.
• Sicherheitsbereiche und Layout-Regeln. Du kannst Ränder erzwingen, Gesichter und Schlüsselmotive meiden und Text innerhalb plattformspezifischer Sicherheitsbereiche halten.
• Günstige Iteration. Einen Tippfehler korrigieren oder Untertitel übersetzen heißt, das Overlay neu zu rendern, nicht das Video neu zu generieren.
• Komponierbarkeit. Wasserzeichen, Bauchbinden und Untertitel lassen sich unabhängig schichten und pro Ausgabe ein- und ausschalten.

Die Abwägungen

Der Overlay-Weg tauscht Modellabhängigkeit gegen Pipeline-Komplexität. Du fügst einen zweiten Request hinzu, brauchst irgendwo einen Speicher für Zwischen-Assets und besitzt die Rendering-Konfiguration. Im Gegenzug wird Text zu Daten, die du versionieren, testen und ersetzen kannst. Für alles mit echtem Untertitelbedarf – barrierefreie Untertitel, mehrsprachige Varianten, templatisierte Social-Formate – lohnt sich dieser Handel fast immer.

Ein praktisches Muster ist, Overlays nicht-destruktiv zu rendern: Basis-Asset und Untertitel-Nutzlast als einzige Wahrheitsquelle behandeln und das zusammengesetzte Video als abgeleitetes Artefakt betrachten, das du jederzeit neu erzeugen kannst.

Eine Untertitel-Nutzlast entwerfen, die unter beiden Wegen überlebt

Wenn du die Untertiteldaten gut entwirfst, wird die Wahl zwischen nativer Generierung und Overlays zu einem Rendering-Detail statt zu einem Neuschreiben. Das Ziel ist eine einzige Nutzlast, die sich sowohl als Prompt serialisieren lässt für nativen Text als auch einem Renderer zuführen lässt für Overlays.

Kernfelder

Modelliere jedes Textelement als Objekt, wobei Inhalt, Timing und Darstellung getrennt bleiben:

{
  "track": "captions",
  "items": [
    {
      "text": "Everything you need to know",
      "start": 0.0,
      "end": 2.4,
      "style": { "role": "title", "align": "center", "position": "lower_third" },
      "lang": "en"
    }
  ]
}

Wichtige Designentscheidungen:

• Zeit in Sekunden, als Fließkommazahl. Verwende eine einzige Zeitbasis im gesamten Projekt und rechne nur beim Rendern in Frames um.
• Stil nach Rolle statt nach absoluten Werten. Benenne Rollen wie title, caption und lower_third und löse sie im Renderer in Schriftarten und -größen auf. Das macht die Nutzlast formatübergreifend portabel.
• Track-Namen. Trenne Tracks wie captions, titles und watermark, damit du Tracks pro Ausgabe ein- oder ausschalten kannst.
• Sprach-Tag pro Element. Sowohl die Schriftartauswahl als auch spätere Übersetzungs-Pipelines brauchen es.
• Keine Darstellungsinformationen im Textfeld einbacken. Packe niemals Stilhinweise in den Text; dafür ist das Style-Objekt da.

Ein Schema, das beide Wege versorgt

Für die native Generierung schreibst du einen kleinen Adapter, der die wichtigsten Elemente auswählt und in Prompt-Anweisungen umwandelt: der wörtliche Text, seine Position und ein Stil-Deskriptor. Mache diesen Adapter bewusst verlustbehaftet – natives Rendering kann ohnehin nie einem vollständigen Untertitel-Track folgen.

Für Overlays übergibst du die Nutzlast an den Renderer, der Rollen und Positionen auflöst und jedes Element innerhalb seines Zeitfensters zeichnet.

Der Gewinn: Dein Anwendungscode baut ein Untertitelobjekt, und der Wechsel von nativ zu Overlay (oder zurück für einen bestimmten Clip) ist eine Konfigurationsänderung, keine Datenmigration.

Ein funktionierender Overlay-Request, Schritt für Schritt

Hier ist die Sequenz für den Overlay-Weg, ausgedrückt als API-Schritte. Die genauen Endpunktnamen und Parameter hängen vom Anbieter ab, aber die Form ist stabil, und eine dünne Abstraktionsschicht hält sie backendübergreifend stabil.

Schritt 1: Generierung des sauberen Materials absenden

POST /video/generations
{
  "prompt": "A slow dolly shot through a modern office, no on-screen text, natural light",
  "duration_seconds": 6,
  "aspect_ratio": "16:9"
}

Halte den Prompt textfrei und speichere die zurückgegebene Task-ID.

Schritt 2: Abfragen, bis das Material bereit ist

GET /video/generations/{job_id}

Frage mit Backoff statt in einer engen Schleife ab. Behandle Zustände wie queued, running, succeeded und failed als erstklassige Zustände im Code und persistiere die URL oder ID des Ergebnis-Assets, damit ein Absturz das Generierungsergebnis nicht verliert.

Schritt 3: Overlay-Rendering absenden

POST /video/overlays
{
  "source_asset": "asset_abc123",
  "captions": {
    "track": "captions",
    "items": [
      { "text": "Shipping today", "start": 0.4, "end": 2.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" },
      { "text": "No rebuild required", "start": 2.2, "end": 4.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" }
    ]
  }
}

Beachte, dass die Overlay-Anfrage nur das Quell-Asset und die Textdaten trägt. Sie generiert das Material nicht neu, und genau das macht Iteration günstig.

Schritt 4: Das zusammengesetzte Ergebnis abrufen

Frage den Overlay-Task genauso ab wie den Generierungs-Task und hole dir dann das finale Asset. Speichere Basis-Asset, Untertitel-Nutzlast und Ausgabe zusammen, damit die Komposition reproduzierbar ist.

Kapsele die Schritte 1–4 im Code in eine Funktion, die einen Prompt und eine Untertitel-Nutzlast entgegennimmt und das finale Asset zurückgibt. Diese Funktion ist deine eigentliche Schnittstelle; die einzelnen Endpunkte sind austauschbare Implementierungsdetails.

Zuverlässigkeitsprüfungen vor der Veröffentlichung

Videotext-Pipelines scheitern auf leise Weise: abgeschnittene Untertitel, falsch übersetzte Zeilen, neu generierte Clips, die nie aufgeräumt werden. Füge Prüfungen hinzu, bevor Nutzer diese sehen.

Gerenderten Text validieren

• Nativer Weg: Sample Frames am Anfang und Ende jedes Textfensters und prüfe sie. Automatisiere grundlegende Lesbarkeitsprüfungen, wo möglich, aber behalte einen manuellen Review-Schritt für kundenorientierten Text bei, weil die Modelltypografie unvorhersehbar degenerieren kann.
• Overlay-Weg: Validiere die Nutzlast vor dem Rendern – Zeiten jedes Elements überlappen sich nicht, liegen innerhalb der Clip-Dauer und verwenden unterstützte Sprachen und Rollen. Prüfe nach dem Rendern Stichproben-Frames an Elementgrenzen, um zu bestätigen, dass nichts abgeschnitten wurde.

Wiederholungen sicher machen

• Idempotenz-Schlüssel auf absendenden Requests, damit ein wiederholter Netzwerkaufruf keine doppelten Generierungs-Tasks erzeugt.
• Zustandsmaschine pro Task: queued → running → succeeded/failed, persistiert, damit ein Neustart fortsetzt statt neu zu beginnen.
• Begrenzte Abfragen mit Backoff und Timeout, die einen klaren Fehler liefern statt einer Endlosschleife.
• Zwischen-Assets speichern. Wenn der Overlay-Schritt fehlschlägt, solltest du nicht für die Neugenerierung von Material bezahlen, das du bereits hast.

Kosten über die gesamte Kette kontrollieren

Der Overlay-Weg hat zwei abrechenbare Schritte – Generierung und Rendering – also überwache beide. Verfolge, wie oft du Material neu generierst versus nur Overlays neu renderst; wenn die Material-Neugenerierung dominiert, passt deine Aufteilung nativ/Overlay für diese Arbeitslast vielleicht nicht. Cache finale Assets nach (Basis-Asset, Untertitel-Nutzlast), damit wiederholte Anfragen für dieselbe Ausgabe kostenlos sind.

Beobachtbarkeit

Protokolliere Prompts, Hashes der Untertitel-Nutzlast, Task-IDs und finale Asset-IDs zusammen. Wenn ein Nutzer einen Untertitelfehler meldet, willst du in Sekunden feststellen können, ob das Problem in der Generierung, den Daten oder dem Rendering liegt. Halte die Untertitel-Nutzlast als versionierte einzige Wahrheitsquelle, damit du immer erklären kannst, was der Renderer zeichnen sollte.

Wähle deinen Standard-Workflow

Nimm das als Startregel und überprüfe sie, während das Produkt wächst.

Wähle nativen Text, wenn Text dekorativ oder beiläufig ist, die Formulierung kurz bleibt, du Neugenerierung als Korrekturweg akzeptierst und ein zweiter Rendering-Schritt für den Clip keine Ingenieurszeit wert ist.

Wähle den Overlay-Weg, wenn Text exakt, zeitlich getaktet, übersetzt, neu gestaltet oder über mehrere Ausgaben hinweg wiederverwendet werden muss. Untertitel, Unterzeilen, Bauchbinden und templatisierte Marketingformate landen fast immer hier. Der zusätzliche Request ist der Preis für Determinismus.

Hybride Ansätze sind sinnvoll. Viele Teams generieren standardmäßig sauberes Material, verlassen sich bei allem Wichtigen auf Overlays und behalten nativen Text für einmalige Stimmungsaufnahmen. Weil beide Wege dieselbe Untertitel-Nutzlast verbrauchen, kannst du diese Entscheidung pro Clip treffen, ohne deine Daten speziell behandeln zu müssen.

Was auch immer du wählst: Halte die Integration hinter einer dünnen Abstraktion – eine Funktion, die einen Prompt und eine Untertitel-Nutzlast entgegennimmt und das finale Asset zurückgibt. Diese Grenze ist genau das, was dir erlaubt, Generierungs-Backends zu wechseln, Rendering-Optionen hinzuzufügen oder einen einzelnen Clip zwischen Workflows zu verschieben, ohne die Untertitel-Logik anzutasten, die du dir mühsam erarbeitet hast.