PixVerse-Lip-Sync-API-Tutorial: Hochladen, Generieren, Abfragen und Überprüfen

AI Overview

Was benötigt die PixVerse-Lip-Sync-API?

Geben Sie ein Videoreferenzmaterial und eine Sprachquelle an. Das Video kann entweder eine von PixVerse generierte source_video_id oder ein hochgeladenes video_media_id sein; die Sprachquelle kann entweder ein hochgeladenes Audiofile oder ein TTS-Sprecher mit Skript sein.

Welcher Endpunkt erstellt eine Lip-Sync-Aufgabe?

Senden Sie POST /openapi/v2/video/lip_sync/generate mit Ihrem API-Schlüssel, einer neuen Trace-ID und einer gültigen Kombination aus Video und Audio. Bei erfolgreicher Auftragserstellung erhalten Sie eine video_id, jedoch noch keine fertige Datei.

Wie erkenne ich, dass das Ergebnis bereit ist?

Rufen Sie GET /openapi/v2/video/result/{id} wiederholt mit der zurückgegebenen video_id ab. Laut PixVerse-Dokumentation bedeutet Status 5 „wird generiert“, Status 1 „erfolgreich“; erst dann darf die zurückgegebene Video-URL verwendet werden.

Kann ich Text statt einer Audiodatei verwenden?

Ja. Wählen Sie einen integrierten oder benutzerdefinierten TTS-Sprecher aus und übergeben Sie lip_sync_tts_speaker_id zusammen mit lip_sync_tts_content. Kombinieren Sie diesen Weg nicht in derselben Anfrage mit einer nicht verwandten Audio-Media-ID.

Wählen Sie Video und Stimme vor dem API-Aufruf

Dieser PixVerse-Lip-Sync-API-Tutorial richtet sich auf eine spezifische Aufgabe: Eine gewählte Sprachzeile auf ein bestehendes bewegtes Gesicht zu legen, das asynchrone Ergebnis abzurufen und zu entscheiden, ob die Mundbewegung nutzbar ist. Falls Sie zunächst den Basisclip erstellen müssen, ist eine kurze Sprecheraufnahme einfacher zu bewerten als ein schneller Schnitt, eine Profil-zu-Front-Drehung oder ein durch Hände verdecktes Gesicht. Diesen Basisclip können Sie mithilfe eines Bild-zu-Video-Workflows, einer PixVerse-Generierung oder mit Filmmaterial erstellen, für das Sie die Nutzungsrechte besitzen.

Die offizielle PixVerse-Sprach-Anleitung nennt zwei Möglichkeiten, das Bild bereitzustellen. Ein vom API generierter Clip besitzt bereits eine video_id, die als source_video_id übergeben wird. Ein externer Clip wird über den Media-Endpunkt hochgeladen und liefert eine media_id, die als video_media_id übergeben wird. Diese IDs sind nicht austauschbar. Notieren Sie sich in Ihrer eigenen Auftragsprotokollierung jeweils die Herkunft neben jeder ID, damit bei einem späteren Wiederholungsversuch nicht versehentlich eine hochgeladene Media-Nummer im Feld für generierte Videos eingesetzt wird.

Für die Sprachquelle wählen Sie entweder eine fertige Aufnahme mit audio_media_id oder einen Text-zu-Sprache-Weg mit lip_sync_tts_speaker_id und lip_sync_tts_content. Die vier möglichen Kombinationen bilden eine 2×2-Matrix: generiertes oder hochgeladenes Video gekoppelt mit aufgenommenem Audio oder TTS. Eine Sprachprobe, die zur Erstellung eines benutzerdefinierten Sprechers dient, erfüllt eine andere Funktion als das endgültige Audio, das für eine Lip-Sync-Aufgabe hochgeladen wird – auch wenn beide über einen Media-Upload-Schritt laufen.

Die Standbilder dienen redaktionellen Zwecken und zeigen eine fiktive erwachsene Moderatorin; sie stellen weder PixVerse-Ausgaben noch einen Nachweis für Lip-Sync-Genauigkeit dar. Sie verdeutlichen, warum ein klar sichtbares Gesicht und ein unverdeckter Mund bei der Auswahl des Quellclips entscheidend sind.

Original redaktionelles Standbild, kein PixVerse-Ergebnis. Ein frontal und ruhig gefilmtes Gesicht ist eine praktische erste Eingabe zur Überprüfung der Sprachsynchronisation.

Halten Sie den ersten Test bescheiden: ein sichtbarer Sprecher, ein kurzer Satz, saubere Aussprache und wenig Kamerabewegung. Der Sprach-Narrativ-Leitfaden und die Media-Upload-Referenz nennen derzeit unterschiedliche Funktionsbegrenzungen für Lip-Sync-Uploads; behandeln Sie daher kopierte Größen- oder Dauerangaben nicht als universell gültige Regel. Prüfen Sie die aktuelle, endpunktspezifische Dokumentation und halten Sie die erste Probe deutlich kurz. PixVerse-API-Guthaben sind unabhängig von der Web-App-Mitgliedschaft; vergewissern Sie sich vor dem Start eines Stapelauftrags, dass ausreichend Guthaben vorhanden ist.

Externe Medien hochladen – ohne IDs zu verwechseln

Falls Sie bereits eine von PixVerse generierte video_id besitzen, überspringen Sie den Video-Upload. Andernfalls laden Sie ein unterstütztes externes Video über POST /openapi/v2/media/upload hoch und speichern die zurückgegebene Resp.media_id als video_media_id. Laden Sie eine aufgenommene Sprachspur über denselben Media-Endpunkt hoch und speichern Sie deren zurückgegebene Resp.media_id als audio_media_id. PixVerse listet gängige Videotypen wie MP4, MOV und WebM sowie Audiotypen wie MP3, WAV, M4A und AAC auf; prüfen Sie vor dem Transfer Format und aktuelle Funktionsbegrenzungen.

Benennen Sie Artefakte nach ihrem Zweck: speaker-base-v1.mp4, line-01-clean-v1.wav sowie einen Auftragsdatensatz mit ihren Media-IDs. Stellen Sie sicher, dass das Gesicht zum Zeitpunkt des Sprachbeginns sichtbar ist, entfernen Sie unerwünschte Stillephasen und prüfen Sie, ob der Quellclip genügend Mundbewegung für die neue Sprachzeile bietet.

Original redaktionelles Standbild. Die Dreiviertelansicht bietet dem Gutachter mehr Tiefeninformationen, erschwert aber das Verbergen von Zähnen, Kiefer und Lippenkanten, falls die Synchronisation driftet.

Für TTS überspringen Sie den Upload einer fertigen Audioaufnahme. Rufen Sie die Sprachliste ab, wählen Sie eine integrierte Sprecher-ID aus oder erstellen Sie eine benutzerdefinierte Stimme anhand einer separat hochgeladenen, genehmigten Sprachprobe. Gehen Sie nicht davon aus, dass auto für jede Sprache geeignet ist; speichern Sie stattdessen die tatsächlich ausgewählte Sprecher-ID. Für mehrere Sprecher erstellen Sie separate Clips und fügen diese später zusammen.

Der Leitfaden zum Native-Audio-Video erklärt, warum Stimme, Umgebungsgeräusche und Bewegung gemeinsam bewertet werden müssen. Holen Sie die Einwilligung zur Nutzung des Gesichts oder der Stimme einer realen Person ein und kennzeichnen Sie synthetische Sprache dort, wo dies erforderlich ist.

Senden Sie genau eine gültige Generierungsanfrage

Die offizielle Generierungsroute lautet https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate. PixVerse erwartet für jede neue API-Anfrage ein API-KEY und eine neue Ai-trace-id. Speichern Sie den Schlüssel serverseitig – nicht in Browser-JavaScript oder einem Artikelbeispiel. Die Wiederverwendung einer Trace-ID kann ein früheres Ergebnis zurückliefern, anstatt eine beabsichtigte neue Aufgabe zu starten; protokollieren Sie daher jede Trace-ID zusammen mit ihren Eingabe-IDs, der Skriptversion und der Antwort.Diese Platzhalteranfrage verwendet ein von PixVerse generiertes Quellvideo sowie hochgeladene End-Audio-Datei. Ersetzen Sie die Beispielzahlen durch IDs, die von Ihrem eigenen Konto zurückgegeben werden; diese Anfrage wurde für diesen Artikel nicht ausgeführt.

curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
  -H "API-KEY: $PIXVERSE_API_KEY" \
  -H "Ai-trace-id: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"source_video_id":123456,"audio_media_id":234567}'

Für ein externes Video ersetzen Sie source_video_id durch video_media_id. Für Text-zu-Sprache ersetzen Sie audio_media_id durch beide Felder lip_sync_tts_speaker_id und lip_sync_tts_content. Dies sind alternative Pfade – keine vier Felder, die wahllos ausgefüllt werden sollen. Der Antwort-Wrapper verwendet ErrCode, ErrMsg und Resp; bei erfolgreicher Auftragserstellung ist Resp.video_id die zu speichernde Kennung. Sie stellt jedoch keine Bestätigung dar, dass eine abspielbare Datei vollständig generiert wurde.

Validieren Sie vor dem Aufruf genau einen Videoid-Typ und einen Sprachmodus; lehnen Sie ein leeres TTS-Skript ab. Loggen Sie die zurückgegebenen Credits, ohne einen festen Preis hartzucodieren. Verknüpfen Sie jede Zeile und jede Auftragsantwort mit einer stabilen Shot-ID, z. B. einer First-and-Last-Frame-Übergabe für visuelle Kontinuität.

Pollen Sie den Auftrag und halten Sie das Ergebnis nachvollziehbar

Nach der Auftragserstellung verwenden Sie GET /openapi/v2/video/result/{id} mit der zurückgegebenen video_id. PixVerse dokumentiert Status 5 als „wird generiert“ und Status 1 als „erfolgreich“. Eine erfolgreiche HTTP-Antwort oder ErrCode: 0 aus dem Erstellungsaufruf bedeutet lediglich, dass der Auftrag akzeptiert wurde – nicht, dass das bewegte Ergebnis Ihre Überprüfung bestanden hat. Sobald der Status 1 lautet, rufen Sie die Ausgabe-URL aus dem Ergebnis ab und speichern Sie eine Kopie gemäß Ihrer üblichen Asset-Richtlinie, bevor die URL abläuft oder sich die Zugriffsregeln ändern.

Status 7 ist dokumentiert als „Inhaltlich ablehnendes Moderationsergebnis“, Status 8 als „Generierungsfehler“. Behandeln Sie beide Fälle als abgebrochene Aufträge statt endlos zu pollern. Ein Produktions-Poller sollte eine begrenzte Wartezeit, ein Backoff-Verfahren und eine dauerhafte Aufzeichnung des zuletzt beobachteten Status enthalten. Falls Ihr Worker neu gestartet wird, setzen Sie die Ausführung anhand der gespeicherten video_id fort, anstatt denselben kostenpflichtigen Auftrag erneut zu erstellen. Verwenden Sie für gezielt neue Anfragen eine neue Trace-ID, aber generieren Sie keine Retries, solange ein langsamer Auftrag lediglich noch in Verarbeitung ist.

Originaler redaktioneller Still. Eine Weitwinkelaufnahme prüft, ob die Gesichts-Timing-Lesbarkeit erhalten bleibt, während der Darsteller sich bewegt – doch kein Still kann echte Lippen-Synchronisation belegen.

Führen Sie ein gut lesbares Protokoll mit Shot-ID, Video- und Sprach-IDs, Trace-ID, generierter video_id, finaler URL und Prüfungsentscheidung. Speichern Sie niemals Anmeldeinformationen in diesem Prüfungsprotokoll. Die PixVerse Agent-Workflow-Anleitung behandelt den umfassenderen Workflow vom Briefing bis zum Shot.

Überprüfen Sie Mundbewegung, Audio und Schnittgrenzen

Sehen Sie sich die finale bewegte Datei zunächst mit Ton in normaler Geschwindigkeit an, danach in reduzierter Geschwindigkeit um ausgewählte Silben herum. Wählen Sie einen Satz mit sichtbaren bilabialen Lauten wie p, b und m sowie einem längeren offenen Vokal. Achten Sie auf eine Mundschließung vor diesen Konsonanten, eine plausible Öffnung beim Vokal sowie darauf, dass die Sprache ohne störenden Verzug beginnt und endet. Dies ist eine redaktionelle Inspektionsmethode – kein berichteter Benchmark und keine Behauptung einer gemessenen PixVerse-Erfolgsquote.

Vergleichen Sie die Ausgabe mit der Quelle: Blickrichtung, Identität, Kiefer, Beleuchtung und Zähne sollten sich nicht abrupt verändern. Prüfen Sie sowohl Nahaufnahmen als auch den gesamten Clip. Diese Stills stellen kein PixVerse-„vorher/nachher“-Ergebnis dar.

Originaler redaktioneller Still. Profilansichten enthüllen Kiefer- und Lippenkontur-Fehler, die ein frontal ausgerichtetes Vorschaubild verbergen kann.

Der unten abspielbare Clip ist ein bereits existierendes, reales bewegtes Seedance-Dialogbeispiel. Er steht unabhängig von der PixVerse-API und vom abgebildeten Referenten; er dient ausschließlich dazu, die Inspektion von Stimme und Mundbewegung in voller Bewegung greifbar zu machen. Er demonstriert weder ein von PixVerse generiertes Lip-Sync-Ergebnis noch einen Leistungsvergleich.

Unabhängiges Seedance-Dialogbeispiel zur vollbewegten Lippen- und Stimminspection

Spielen Sie die gesamte Aussage ab und bewerten Sie Mund, Stimme, Kopfbewegung und Schnitt gemeinsam; dies ist keine PixVerse-Ausgabe.

Verwenden Sie eine einfache Akzeptanzkarte: „Bestanden“, wenn die Aussage verständlich ist, am vorgesehenen Taktschlag beginnt, die Sprecheridentität bewahrt und einer Betrachtung in Normalgeschwindigkeit standhält; „Korrektur erforderlich“, falls nur die Schnittgrenze oder die Audio-Ausschnittsgrenze fehlerhaft ist; „Abgelehnt“, falls Form des Mundes, Gesicht oder Timing systematisch versagen. Die Freigabe sollte sich auf die bewegte Datei – nicht auf das Poster – stützen. Ein separates Lip-Sync-Workflow-Beispiel kann beim Vergleich allgemeiner Prüfgewohnheiten helfen, doch dessen Anbietersteuerungen sind nicht austauschbar mit den Feldern der PixVerse-API.

Beheben Sie Fehler auf der richtigen Ebene und organisieren Sie die Auslieferung

Falls die API eine Anfrage ablehnt, prüfen Sie Antwort und Parameterpaar. Achten Sie auf vertauschte Videoid-Typen, die Verwendung einer Stimmsample-ID als End-Audio, fehlende TTS-Felder oder eine wiederverwendete Trace-ID. Überprüfen Sie Autorisierung, Credits, Medientyp, Limits und Parallelität. Fügen Sie niemals einen API-Schlüssel in einen Support-Screenshot ein.Wenn der Job erfolgreich ist, die Ausgabe jedoch fehlerhaft erscheint, wird eine Änderung des Endpunkts wahrscheinlich keine mangelhafte Quellgeometrie beheben. Verwenden Sie stattdessen einen ruhigeren Clip, eine deutlichere Stimme, weniger Verdeckung, eine kürzere Äußerung und ein Gesicht, das im Bild bleibt. Falls die Synchronisation nur beim ersten Wort versagt, prüfen Sie den Audio-Vorspann und den Startbildschirm des Videos; falls sie nur an einem Schnitt versagt, passen Sie die Schnittgrenze und den Raumton an. Behalten Sie die beste genehmigte Aufnahme bei, während Sie ausschließlich die schwache Zeile erneut verarbeiten.

Seedance Agent kommt nach Vorliegen des API-Ergebnisses zum Einsatz: Halten Sie den genehmigten Basisclip, die Sprachversion, die generierte Ausgabe, die Akzeptanznotizen und die Entscheidung zur Zusammenstellung gemeinsam fest; planen oder ersetzen Sie eine einzelne Aufnahme, ohne das gesamte Werk neu zu erstellen. Es kann die Organisation von Referenzen und die Überprüfung koordinieren, führt jedoch keinen nicht getesteten PixVerse-API-Aufruf aus oder zertifiziert kein PixVerse-Ergebnis. Bewahren Sie bei der Kombination von Ausgaben verschiedener Anbieter stets eine klare Herkunftsnachweisbarkeit auf.

Fazit

Ein zuverlässiger PixVerse-Lip-Sync-API-Workflow wählt einen einzigen Videoidentifikationstyp und einen einzigen Sprachmodus, lädt nur die erforderlichen Medien hoch, sendet genau eine gut formatierte Anfrage mit einer neuen Trace-ID, wartet darauf, dass die zurückgegebene video_id abgeschlossen ist, und bewertet das tatsächliche bewegte Ergebnis. Halten Sie die aktuelle PixVerse-Dokumentation als maßgebliche Quelle für Grenzwerte und Abrechnungsinformationen fest und trennen Sie die redaktionelle Akzeptanz klar von der Aufgabenerstellung. Wenn mehrere genehmigte Zeilen zu einer kohärenten Lieferung zusammengeführt werden müssen, organisieren Sie die Referenzen, Überprüfungen und die endgültige Zusammenstellung in Seedance Agent.