Veo-Referenzbilder-API-Tutorial: Von Assets zum Video

AI Overview

Wie viele Referenzbilder kann die Veo-API verwenden?

Veo 3.1 akzeptiert bis zu drei Referenzbilder pro Person, Charakter oder Produkt. Verwenden Sie stattdessen einer großen, unzusammenhängenden Bildauswahl lieber eine kleine, kohärente Bildgruppe, die Identität, Materialien und Form deutlich zeigt.

Sind Referenzbilder dasselbe wie erste und letzte Frames?

Nein. referenceImages steuert die Konsistenz von Motiv oder Stil, während image den ersten Frame festlegt und lastFrame den Endpunkt begrenzt. Wählen Sie den passenden Modus je nachdem, was unbedingt konstant bleiben muss.

Welches Veo-Modell unterstützt Referenzbilder?

Die aktuelle Gemini API-Dokumentation von Google listet Referenzbilder für Veo 3.1 und Veo 3.1 Fast auf – nicht jedoch für Veo 3.1 Lite oder Veo 3.0. Generierungen mit Referenzbildern haben eine Dauer von acht Sekunden.

Was sollte eine API-Integration speichern?

Speichern Sie die IDs der Eingabe-Assets, den normalisierten Prompt, das Modell und die Konfiguration, den Namen der Operation, die endgültige Datei sowie das Prüfergebnis. Diese Aufzeichnung ermöglicht es, einen fehlgeschlagenen Shot reproduzierbar nachzustellen, statt bei jedem erneuten Versuch im Blindflug zu agieren.

Wählen Sie den Referenzmodus vor dem Codieren

Die praktische Aufgabe hinter einem Veo-Referenzbilder-API-Tutorial besteht nicht nur darin, Base64-Daten zu senden. Entwickler müssen wissen, welcher visuelle Steuerungsmodus zum jeweiligen Shot passt, welche Felder zusammengehören und wie sie vorgehen sollen, wenn die Ausgabe ein Produktdetail ignoriert oder vom Charakter abweicht.

Ein neues Referenzsets-Konzept, das speziell für diesen Leitfaden entwickelt wurde. Der Fahrer, die Safranjacke, die Bernsteinbrille und das kobaltfarbene Motorrad bilden klare Ankerpunkte für Kontinuität; es wird nicht als Veo-Benchmark präsentiert.

Beginnen Sie damit, einen der drei Modi auszuwählen:

Der Unterschied ist entscheidend. Ein Charakterporträt in referenceImages dient als Orientierungshilfe – nicht als Garantie dafür, dass der erste gerenderte Frame dieses Porträt pixelgenau wiedergibt. Umgekehrt fixiert ein Start-image die initiale Komposition, bietet aber keine drei separaten Sichtweisen auf die Identität. Mischen Sie keine Konzepte im Prompt und machen Sie dann die API dafür verantwortlich, die falsche Einschränkung gewählt zu haben.

Laut der aktuellen Gemini API-Tabelle von Google unterstützt referenceImages bis zu drei VideoGenerationReferenceImage-Objekte in Veo 3.1 und Veo 3.1 Fast. Veo 3.1 Lite unterstützt dieses Feld nicht. Eine Anfrage mit Referenzbildern erzeugt ein einzelnes Video mit einer Dauer von acht Sekunden, unterstützt Quer- und Hochformat und kann in 720p, 1080p oder 4K über die vollständigen Veo-3.1-Routen generiert werden. Höhere Auflösungen erhöhen Latenz und Kosten – validieren Sie daher den Shot-Vertrag, bevor Sie die Auslieferung hochskalieren.

Für eine umfassendere Erklärung auf Schnittstellenebene vor dem Aufbau des Endpunkts siehe der Google Flow- und Veo-Workflow-Leitfaden.

Bereiten Sie Referenzbilder und Prompt vor

Erstellen Sie einen kohärenten Asset-Satz

Verwenden Sie Referenzbilder, die sich hinsichtlich der Identität einig sind. Ein nützliches Dreier-Bildpaket könnte beispielsweise eine saubere Ansicht von Gesicht und Kleidung, eine Darstellung der Produktgeometrie sowie ein kleines Accessoire enthalten, das unbedingt erhalten bleiben muss. Halten Sie Farbtemperatur, Objektivverzerrung und Proportionen kompatibel. Wenn ein Bild ein kobaltfarbenes Motorrad zeigt und ein anderes ein unterschiedliches Chassis in Marineblau, kann der Prompt nicht zuverlässig entscheiden, welche Geometrie maßgeblich ist.

Charakterreferenz: Prüfen Sie Gesichtsform, Haarsilhouette, Jackenpaneele und bernsteinfarbene Brillengläser. Eine gut lesbare Referenz ist nützlicher als ein dramatisches, aber verschwommenes Porträt.

Produktreferenz: Die gesamte Radgeometrie, die Rahmensilhouette, die kobaltfarbenen Paneele, die Jacke und die Brille sind unter neutralem Licht nach Regen sichtbar.

Vor der kostenpflichtigen Anfrage sollten Sie die Bilder vorverarbeiten. Bestätigen Sie den MIME-Typ, lehnen Sie leere Dateien ab, decodieren Sie einmal, um Beschädigungen frühzeitig zu erkennen, und behalten Sie das ursprüngliche Seitenverhältnis bei – es sei denn, Ihre Pipeline schneidet gezielt zu. Speichern Sie eine Prüfsumme und eine interne Asset-ID. Da Base64 die Anfragengröße erhöht, vermeiden Sie wiederholtes Encodieren überdimensionierter Masterdateien, wenn ein korrekt dimensionierter Ableger alle sichtbaren Details bewahrt.

Formulieren Sie einen erhaltungsorientierten Prompt

Ein guter Prompt sagt Veo nicht nur, was geschieht, sondern auch, was stabil bleiben soll. Verwenden Sie diese wiederverwendbare Reihenfolge:

Mittlere Tracking-Aufnahme. Die silberhaarige Fahrerin in der Safranjacke fährt das matter kobaltfarbene Motorrad entlang einer nassen Küstenstraße bei Sonnenaufgang. Bewahren Sie ihr Gesicht, die kurze Bob-Silhouette, die bernsteinfarbenen Visierbrillen, die Jackenpaneele, die Karosseriegeometrie des Motorrads, die Anzahl der Räder und die kobaltfarbene Oberfläche. Meeresspray bewegt sich natürlich; die Kamera folgt parallel, ohne zu rotieren. Native Wind-, Reifen- und ferne Brandungsgeräusche; kein Dialog, kein Text, kein Logo.Benennen Sie Referenzen anhand sichtbarer Merkmale statt anhand von Dateinamen. Halten Sie pro Acht-Sekunden-Aufnahme genau eine Hauptaktion und eine Kamerabewegung fest. Widersprüchliche Anweisungen wie „feststehende Kamera“ und „schnelle Orbit-Bewegung“ erzeugen ein Koordinationsproblem, das kein Referenzbild lösen kann. Die Anleitung zur Bild-zu-Video-Eingabeaufforderung enthält ein kompaktes Muster aus Subjekt–Aktion–Kamera–Erhaltung, das Sie wiederverwenden können.

Senden Sie eine Veo 3.1-Anfrage

Erstellen Sie Asset-Referenzen in JavaScript

Mit der aktuellen @google/genai-Bibliothek SDK stellen Sie jedes vorbereitete Bild als Objekt dar, das die Felder imageBytes und mimeType enthält, und umschließen es dann mit referenceType: 'asset'. Die Bibliothek SDK liest den API-Schlüssel aus Ihrer Umgebung aus; speichern Sie ihn stets auf dem Server, niemals im Browser-JavaScript.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

Feldnamen können zwischen den Oberflächen Gemini API und Vertex AI variieren. Binden Sie daher die Version von SDK explizit fest und validieren Sie sie anhand der offiziellen Dokumentation für den Endpunkt, den Sie tatsächlich bereitstellen. Kopieren Sie nicht die JSON-Struktur eines Drittanbieter-Wrapper in einen Google-Endpunkt. Protokollieren Sie stattdessen ein redigiertes Anfragemanifest – nicht die vollständige Base64-Nutzlast.

Verwenden Sie zunächst 720p für den ersten Akzeptanztest. Nachdem Identität, Bewegung, Kamera und Audio bestanden wurden, wiederholen Sie die genehmigte Konfiguration in der erforderlichen Auslieferungsauflösung. Falls Ihre Anwendung über mehrere Anbieter hinweg leitet, erklärt der Leitfaden „Aggregator versus direkter API-Zugriff“, warum ein normalisierter Auftragsdatensatz zuverlässiger ist als anbieterspezifische UI-Zustandsmerkmale.

Abfragen, Herunterladen und Speichern der Ausgabe

Die Videoerzeugung durch Veo erfolgt asynchron. Der erste Aufruf gibt eine lang laufende Operation zurück – nicht die fertige MP4-Datei. Fragen Sie mittels des Operationsnamens in einem sinnvollen Intervall ab, brechen Sie nach einer begrenzten Timeout-Dauer ab und speichern Sie die Operations-ID dauerhaft ab, damit ein Worker-Neustart die Operation fortsetzen und keine doppelte Aufgabe einreichen kann.

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Google behält generierte Videos derzeit zwei Tage lang auf seinen Servern. Laden Sie sie daher zeitnah in Ihren eigenen Speicher herunter. Stellen Sie sicher, dass die Datei existiert, eine nicht-null Länge aufweist, als Video decodierbar ist und der erwarteten Dauer entspricht. Speichern Sie einen Poster-Frame zur Überprüfung – behandeln Sie diesen Frame jedoch niemals als Nachweis dafür, dass die gesamte Bewegung fehlerfrei ist.

Veo 3.1-Kinovideo-Beispiel für die Prüfung des gesamten Clips

Sehen Sie sich den kompletten Clip auf Identität, Umgebung, Kamera und Audio-Kontinuität hin an. Eine bewegte Datei enthüllt Fehler, die ein einzelner attraktiver Frame verbergen kann.

Konsistenz prüfen und Fehler behandeln

Überprüfen Sie mithilfe eines festen Akzeptanzrasters

Prüfen Sie jede Ausgabe zunächst in normaler Geschwindigkeit und anschließend erneut im Bereich der komplexesten Bewegung. Dokumentieren Sie für jedes Mal dieselben Kriterien als „Bestanden“, „Zu überarbeiten“ oder „Abgelehnt“:

Die alternative Komposition ändert Zeit und Bildausschnitt, behält aber dieselben Kontinuitätsanker bei. Verwenden Sie solche Frames, um zu beurteilen, ob die Asset-Identität eine Szenenänderung übersteht.

Wenn bei jeder Ausgabe dasselbe Merkmal verloren geht, liegt wahrscheinlich ein Fehler in der Referenz oder in der Hierarchie der Eingabeaufforderung vor. Wenn die Fehler zufällig variieren, halten Sie die Eingaben konstant und führen Sie den Vorgang erneut aus, bevor Sie sämtliche Inhalte neu formulieren. Falls die Komposition exakt auf ein vorgegebenes Endbild enden muss, wechseln Sie zu image plus lastFrame, anstatt weitere Erhaltungsanweisungen zu referenceImages hinzuzufügen.

Seedance Produkt-Bewegungs-Ausgabe zum Vergleich von Geometrie und kontrolliertem Kameraverhalten

Dies ist ein anderes Modell und ein anderer Aufnahmetyp, der hier lediglich als Beispiel für eine Real-Bewegungs-Überprüfung – nicht als Veo-Benchmark – eingefügt wurde. Wenden Sie dieselbe Geometrie- und Kamera-Prüfsystematik an.

Trennen Sie Provider-Fehler von kreativen Fehlern. Authentifizierungsprobleme, Quotenüberschreitungen, ungültige MIME-Typen, nicht unterstützte Konfigurationen, Sicherheitsfilterung, Timeouts sowie ein abgeschlossener, aber nicht verwendbarer Clip erfordern jeweils unterschiedliche Reaktionen. Automatisieren Sie nur das erneute Versenden bei vorübergehenden Transport- oder Dienstfehlern. Bei abgelehnten Eingabeaufforderungen oder schlechten visuellen Ergebnissen ist eine manuelle Überprüfung erforderlich – nicht eine unbegrenzte, kostenpflichtige Wiederholungsschleife.Vor dem endgültigen Export bestätigen Sie den Lieferzyklus anhand der AI-Videobildrate-Anleitung, da die generierte Bildrate von 24 fps und die Plattform-Lieferungseinstellungen zwar miteinander verbunden, aber nicht austauschbar sind.

Integrieren Sie sie in einen Seedance Agent-Workflow

Die reine Veo-API eignet sich gut, wenn ein Entwickler bereits über eigene Speicherinfrastruktur für Assets, Versionsverwaltung für Prompts, Polling-Mechanismen für Operationen, Genehmigungsprozesse und Wiederholungsrichtlinien verfügt. Seedance Agent ist nützlich, wenn die eigentliche Aufgabe mehr als einen API-Aufruf umfasst: z. B. die Umwandlung eines kurzen Briefings in eine Shotliste, die Zuweisung von Referenzrollen, die Auswahl eines unterstützten Modells pro Shot, die Überprüfung realer Ausgaben und das erneute Ausführen nur der fehlgeschlagenen Segmente.

Für die Fahrersequenz kann ein Agent das Porträt, das Motorrad und die Brille einmal registrieren; eine Küsten-Tracking-Aufnahme und einen „Blue-Hour“-Abschluss als separate Jobs erstellen; ihre Aufbewahrungsregeln synchron halten; und beide Clips zur Genehmigung freigeben. Die API bleibt dabei die Generierungsschicht, während der Agent den Produktionsstatus verwaltet. Dadurch werden versehentliche doppelte Anfragen reduziert und verhindert, dass späte Prompt-Änderungen stumm die kanonische Asset-Menge verändern.

Messen Sie die Kosten pro genehmigtem Sekundenwert – nicht nach abgeschlossenen Anfragen. Vergleichen Sie Veo 3.1 mit anderen Ansätzen hinsichtlich Identitätsstabilität, nutzbarer Endungen, Review-Zeit und Anzahl der Wiederholungen mithilfe des Seedance-2.5- versus-Veo-3.1-Vergleichs. Das Ziel besteht nicht darin, jeden Shot zwangsläufig durch ein einziges Modell zu führen; vielmehr geht es darum, eine konsistente Sequenz mit der geringstmöglichen Zahl vermeidbarer Überarbeitungen auszuliefern.

Fazit

Eine zuverlässige Integration der Veo-Referenzbilder-API beginnt damit, den richtigen Steuerungsmodus zu wählen, bis zu drei kohärente Asset-Referenzen vorzubereiten, einen klaren Motion-and-Preservation-Prompt zu formulieren, eine gültige Veo-3.1-Anfrage zu senden, den langlaufenden Vorgang persistent zu speichern, die Ausgabe vor Ablauf der Aufbewahrungsfrist herunterzuladen und den gesamten Clip anhand eines festgelegten Bewertungsrasters zu prüfen. Halten Sie flüchtige API-Wiederholungsversuche separat von kreativen Neuausführungen und wechseln Sie zur Interpolation zwischen erstem und letztem Frame, sobald exakte Endpunkte wichtiger sind als flexible Asset-Anleitungen; benötigt das Projekt jedoch Shot-Planung, gemeinsame Referenzen, Modell-Routing, Genehmigungen und gezielte Neuausführungen rund um den API-Aufruf, starten Sie den Workflow mit Seedance Agent →