Transkription und Dialogbearbeitung
Die Dialogbearbeitung hat drei Schritte. Transkribiere zuerst das Ausgangsmaterial. Höre dir dann die Wortänderungen in der Vorschau an und erstelle mit dieser Vorschau eine Lipsync-Generierung. Transkriptions- und Vorschauaufträge laufen asynchron. Bewahre ihre IDs auf, damit deine Anwendung die Statusabfrage nach einem Verbindungsabbruch fortsetzen kann.
Ausgangsmaterial vorbereiten
Für Transkription und Dialogbearbeitung müssen die Medien im Speicher von Sync liegen. Folge für lokale oder extern gehostete Dateien der Anleitung zum Dateiupload. Fordere eine Upload-URL an, lade die Dateidaten hoch und registriere die Datei. Bewahre die URL und die Asset-ID des hochgeladenen Ausgangsvideos auf.
Für die Transkription musst du genau eines der Felder sourceVideoUrl und sourceAudioUrl angeben. Wenn du bereits extrahiertes Audio übergibst, entfällt die Extraktion auf dem Server. Für eine Dialogbearbeitung brauchst du die URL des Ausgangsvideos und die Wort-Zeitmarken auf dessen Timeline. Verwende dafür das Transkript des Videos selbst.
Video transkribieren
Beim Einreichen erhältst du 201 mit einem Auftrag. Frage GET /v2/transcriptions/{id} mit demselben API-Schlüssel ab, bis status den Wert COMPLETED oder FAILED hat. Warte während der Verarbeitung vor jeder Abfrage die in retryAfterMs angegebene Anzahl Millisekunden. Wenn genügend historische Daten vorliegen, gibt estimate.estimatedFinishAt den voraussichtlichen Abschlusszeitpunkt an. Speichere nach Abschluss das gesamte transcript mitsamt Segment- und Wort-IDs, Zeitmarken und Sprecherinformationen. speakerCount und das optionale Feld difficulty beschreiben das Ausgangsmaterial. Die Schwierigkeitsangabe dient nur zur Information.
Jedes Wort kann in confidence einen Wert für die Zuverlässigkeit der Texterkennung enthalten. Prüfe Segmente mit speakerLabelFlags. Diese Warnungen garantieren keine korrekte Sprecherzuordnung. Behalte beim Einreichen des Transkripts die Sprecher-IDs und Wort-Zeitmarken bei.
Die Wort-Zeitmarken startMs und endMs sind absolute Millisekunden ab Beginn des Ausgangsmaterials. Ohne startMs in der Anfrage gilt null als Startwert. endMs muss größer als startMs sein. Ein explizit gewählter Transkriptionsbereich darf höchstens 60 Minuten lang sein. Wenn du maxSourceSeconds angibst, muss der Wert positiv sein und darf 3,600 nicht überschreiten. Anfragen mit identischem Ausgangsmaterial und identischem Bereich verwenden einen bestehenden Auftrag. Für eine Transkription werden keine Generierungscredits abgezogen.
Liegt endMs hinter dem Ende des Ausgangsmaterials, wird der Wert auf dessen Ende begrenzt. Das Feld sourceEndMs des Auftrags gibt das tatsächlich verwendete Ende an. Kann die Dauer des Ausgangsvideos beim Einreichen nicht ermittelt werden, bleibt der angegebene Bereich bestehen. Liegt startMs am oder hinter dem Ende des Ausgangsvideos, erhältst du 422 mit startMs in errors[0].path. Die API erstellt dann keinen Auftrag.
Änderungen in der Vorschau anhören
Sende das zurückgegebene Transkript unverändert und beschreibe die Änderungen separat. Eine Operation mit kind: "change" ersetzt ein Wort anhand seiner wordId. Eine Operation mit kind: "remove" listet die wordIds aufeinanderfolgender Wörter auf. Gib 1–100 Operationen an.
Wenn die Stimme den Ersatztext falsch aussprechen würde, etwa einen Namen in einem personalisierten Video, füge der Operation change das Feld pronunciation mit einer Lautumschreibung im Klartext hinzu. Die Stimme liest die Umschreibung vor. In den Änderungen und im Ergebnistranskript des Auftrags bleibt replacement erhalten.
Schreibe die Lautumschreibung wie ein normales Wort, ohne Bindestriche oder komplett großgeschriebene Silben. Die Stimme kann Großbuchstaben einzeln aussprechen, sodass aus „shiv-AWN“ beispielsweise „shiv A W N“ wird. Kurze Namen können von Aufnahme zu Aufnahme unterschiedlich klingen. Höre dir die Vorschau an und erstelle bei Bedarf eine neue. Eine Lautumschreibung besteht aus 1–100 Zeichen. Erlaubt sind Buchstaben, Leerzeichen, Bindestriche, Apostrophe und Punkte. Mindestens ein Buchstabe ist erforderlich. Phonem-Markup wird nicht unterstützt. Satzzeichen am Ende von replacement beeinflussen weiterhin die Betonung. Eine remove-Operation mit pronunciation wird mit 400 abgelehnt.
Das folgende Python-Beispiel verwendet das Transkript eines abgeschlossenen Transkriptionsauftrags und ersetzt dessen erstes Wort. Setze TRANSCRIPTION_ID auf die ID deines abgeschlossenen Transkriptionsauftrags. Prüfe das ausgewählte Wort, bevor du das Beispiel auf deinen eigenen Dialog anwendest.
Ein neuer Auftrag gibt 201 zurück. Wiederhole eine Anfrage nach einer Zeitüberschreitung oder einem vorübergehenden Fehler mit demselben Idempotency-Key und demselben Body. Eine gleichwertige Wiederholung gibt 200, den ursprünglichen Auftrag und Idempotency-Replayed: true zurück. Verwende für eine neue oder überarbeitete Änderung einen neuen Schlüssel. Siehe Idempotente Anfragen.
Frage GET /v2/dialogue-edits/{id} ab, bis der Status COMPLETED, COMPLETED_PARTIAL oder FAILED lautet. Beide Abschlussstatus sind endgültig und können abspielbares Vorschau-Audio enthalten. Höre dir previewAudioUrl an, bevor du fortfährst. previewDurationMs, resultTranscript und resultSlots beschreiben den Zeitablauf nach der Bearbeitung. previewAssetId ist stets null. Für Lipsync mit der Vorschau übergib die ID des Dialogauftrags als dialogueEdit: { id } (siehe unten).
Prüfe partialDetail, bevor du eine Vorschau renderst. Die Einträge in failedSlots nennen den Index und den Fehlercode der betroffenen resultSlots. Wenn reason den Wert background_bed_missing hat, fehlt der Vorschau der Hintergrundton des Originals. Höre dir die Vorschau an und erstelle bei Bedarf eine überarbeitete Fassung.
Reiche zum Überarbeiten der Vorschau einen weiteren Auftrag mit angepassten Änderungen ein. Du kannst die voiceId des vorherigen Auftrags übergeben, um dessen geklonte Stimme wiederzuverwenden, wenn deine Organisation sie mit demselben Pool von gemeinsam genutzten oder verbundenen ElevenLabs-Schlüsseln verwendet hat. rerunOfJobId hält fest, auf welchen vorherigen Auftrag mit COMPLETED oder COMPLETED_PARTIAL in deiner Organisation sich der neue Auftrag bezieht. Das Feld dient nur zur Dokumentation der Herkunft und löst weder eine Wiederholung noch eine idempotente Verarbeitung aus. Hinweise, die diese Bedingungen nicht erfüllen, werden ignoriert.
Die Dialogbearbeitung unterstützt nur Videos mit einer sprechenden Person. Wenn speakerCount im Transkript größer als 1 ist, lehnt die API die Bearbeitung mit 422 dialogue_edit_unsupported ab. Dabei wird nichts erstellt oder berechnet. Bei Authentifizierung per API-Schlüssel muss die Dialogbearbeitung das ganze Video umfassen. Lass dazu startMs und endMs weg. Das gesamte Ausgangsmaterial muss das Dialoglimit von 10 Minuten einhalten. Per Sitzung authentifizierte Clients können einen Bereich von höchstens 10 Minuten wählen. Es gelten weiterhin die Vorgaben für Abrechnung, Planung, Dauer und Anfragerate.
Lipsync mit der freigegebenen Vorschau erzeugen
Sende dialogueEdit: { "id": "..." } mit genau einem Eingabevideo. Verwende das Originalvideo, auf dem die Bearbeitung beruht. Gib dessen URL oder registrierte Asset-ID an. Lass Audio- und Bildeingaben sowie segments und dubParams weg.
Bei neuen Vorschauen sind segmentLipsyncEnabled und sectionExpansionEnabled beide true. Erstelle eine neue Vorschau, wenn bei einer älteren Vorschau einer der Werte false ist. Der Zeitablauf des Ergebnisses folgt dem bearbeiteten Audio. Fahre mit den üblichen Statusabfragen und Webhooks für Generierungen fort. Die Abrechnung und Limits für Generierungen gelten weiterhin.
Wenn du Multipart-Formulardaten sendest, codiere dialogueEdit und input als JSON-Zeichenfolgen. Dieser Ablauf lehnt Datei-Parts für hochgeladene Videos, Audios und Bilder ab. Verweise auf das ursprüngliche Ausgangsmaterial, da ein erneuter Upload des Videos die Referenz nicht ersetzt.
Mehrere Vorschauen in einem Batch rendern
Um mehrere Varianten eines Videos zu erstellen, etwa eine pro Empfängername, erstelle je Variante eine Vorschau und rendere alle zusammen mit der Batch API. Dafür brauchst du Scale oder höher und eine Freigabe für deine Organisation. Unabhängig davon sind Batch-Zeilen mit dialogueEdit im Early Access und werden pro Organisation freigeschaltet.
- Erstelle die erste Vorschau und warte, bis sie fertig ist. Übergib ihre
voiceIdbei jeder weiteren Vorschau desselben Videos, damit die Stimme nur einmal geklont wird. - Verteile deine Vorschauanfragen so, dass du das Limit von 30 pro Minute einhältst.
- Höre dir einige Vorschauen an, bevor du einen großen Batch einreichst. Füge
pronunciationfür Namen hinzu, die die Stimme falsch ausspricht. - Reiche pro fertiger Vorschau eine Zeile mit demselben Ausgangsvideo und
dialogueEdit: {"id": "..."}ein. Validiere den Batch zuerst mitdry_run.
Das Zeilenformat und die Ablehnungscodes findest du unter Zeilen für Dialogbearbeitungen. Ein vollständiges Skript findest du unter Personalisierte Videonachrichten.
Ablehnungen und fehlgeschlagene Aufträge behandeln
Abrechnungssperren können 402 zurückgeben. Für die Dauer des bearbeiteten Dialogs gelten zusätzlich die Tariflimits. Weitere Fehler bei Transkriptionsaufträgen sind EXTRACTION_FAILED, PROVIDER_FAILED, TIMEOUT und UNKNOWN. Dialogaufträge können bei der Extraktion, beim Klonen der Stimme, bei zu kurzen Stimmproben, bei der Synthese, wegen der Länge der Bearbeitung oder Quelle, bei der Planung, durch Zeitüberschreitungen oder aus unbekannten Gründen fehlschlagen. Prüfe error.code und error.message des Auftrags vor einem neuen Versuch. Eine Statusabfrage startet einen fehlgeschlagenen Auftrag nicht neu.

