Skip to main content
Projekt synchronisieren

Projekt synchronisieren

Erzeugen Sie die Stimmen und mischen Sie die Ausgabe eines bestehenden Projekts aus einem übersetzten SRT, das Sie bereitstellen. VoiceCheap übersetzt auf diesem Endpunkt nichts: keine Übersetzungs-Engine, keine SmartSync-Umformulierung, kein Glossar. Jeder Cue wird wörtlich auf dem passenden Segment des Projekttranskripts gesprochen und dann mit dem ursprünglichen Hintergrund, den Untertiteln und dem optionalen Lippensync gemischt, genau wie bei einer normalen Übersetzung. Nutzen Sie ihn, wenn die Übersetzung woanders entsteht (ein menschlicher Übersetzer, Ihre eigenen Werkzeuge, ein Automatisierungsablauf) und Sie VoiceCheap nur für die Stimmenerzeugung brauchen. Der Lauf ist asynchron: fragen Sie Übersetzungsstatus abrufen ab oder hören Sie auf die Webhooks.

Voraussetzungen

  • Das Projekt muss existieren und seine Transkription muss abgeschlossen sein: erstellen Sie es mit Projekt erstellen (nur Transkription) oder Übersetzung starten und warten Sie auf transcriptionStatus: "success".
  • Ihr SRT muss das Projekttranskript abdecken: jedes Transkriptsegment braucht mindestens einen Cue, und jeder Cue muss auf einem Segment liegen. Exportieren Sie das Transkript mit Projekttranskript exportieren und übersetzen Sie es Cue für Cue, damit die Zeitcodes erhalten bleiben.
  • Die Anfrage wird wie eine Übersetzung desselben Mediums abgerechnet, mit derselben Credit-Prüfung. Lippensync-Modi verbrauchen wie üblich zusätzliche Credits.

Gleichzeitige Ausführungsgrenze

Projekterstellung, Übersetzung und Vertonung prüfen alle das Limit Ihres Kontos für aktive Übersetzungen (höchstens 10, möglicherweise weniger). Nur laufende Übersetzungs- oder Vertonungsvorgänge belegen Plätze; Projekte mit reiner Transkription nicht. Bei Erreichen des Limits gibt die API CONCURRENT_TRANSLATION_LIMIT_REACHED (HTTP 429) zurück. Das geltende Limit steht in details.limit. Ein zweiter Lauf für dasselbe Projekt und dieselbe Zielsprache wird ebenfalls abgelehnt, solange einer läuft (TRANSLATION_ALREADY_IN_PROGRESS, HTTP 409).

Anfrage

Dieser Endpunkt akzeptiert einen JSON-Body (Content-Type: application/json). Boolesche und numerische Optionen werden als JSON-Werte gesendet, nicht als Zeichenketten.
string
erforderlich
Ihr VoiceCheap API-Schlüssel. Erhalten Sie einen von app.voicecheap.ai/page-api.

Pfadparameter

string
erforderlich
Die Projektkennung, die Projekt erstellen oder Übersetzung starten zurückgibt.

Body-Parameter

string
erforderlich
Die Sprache von translatedSrt, in Kleinbuchstaben, aus derselben Liste wie Übersetzung starten. Wenn das Projekt noch keine Arbeit für diese Sprache hat, wird eine erstellt und die Sprache dem Projekt hinzugefügt.
string
erforderlich
Der endgültige SRT-Inhalt in der Zielsprache (Cue-Nummer, Zeitzeile, Text). Maximal 1.000.000 Zeichen. Cues werden den Transkriptsegmenten über Zeitstempel zugeordnet: ein Cue, der innerhalb von 50 ms nach einem Segmentstart beginnt, wird diesem Segment zugewiesen, sonst dem Segment mit der größten Überlappung. Mehrere Cues auf einem Segment werden mit einem Leerzeichen verbunden. Zeitpunkt, Sprecher und Reihenfolge jedes gesprochenen Segments kommen immer aus dem Projekttranskript; Ihre Zeitcodes dienen nur der Zuordnung.
string
Ein https-Endpunkt, der ab jetzt die Webhook-Ereignisse für dieses Projekt empfängt und den auf dem Konto konfigurierten Endpunkt überschreibt.Standard: Der bereits im Projekt gespeicherte Endpunkt, danach der Webhook-Endpunkt des Kontos.
boolean
Die ursprüngliche Hintergrundaufnahme (Musik, Ambiente) unter den erzeugten Stimmen behalten.Standard: true
boolean
Die ursprüngliche Stimme leise unter der erzeugten Stimme behalten.Standard: false
number
Lautstärke der Originalstimme von 1 bis 70, wenn keepOriginalVoice aktiviert ist.Standard: 30
string
Stimmstrategie: cloning (die Sprecher des Projekts klonen) oder custom (eine Katalogstimme oder Ihre gespeicherte benutzerdefinierte Stimme verwenden).Standard: cloning
string
Erforderlich, wenn voiceMode custom ist. Verwenden Sie eine ID aus dubbing_voices_list: eine Katalogstimme oder eine vom authentifizierten Konto gespeicherte benutzerdefinierte Stimme. Die Teamabrechnung gewährt keinen Zugriff auf die gespeicherten Stimmen anderer Mitglieder.
string
Sprachisolierung, wenn keepBackgroundMusic aktiviert ist: studio oder realistic.Standard: studio
boolean
Untertitel in das Ausgabevideo einbrennen. Erfordert ein Videoprojekt.Standard: false
string
Untertiteltext, wenn subtitles aktiviert ist: translated (Ihr SRT) oder original (das Quelltranskript).Standard: translated
string
Lippensync starten, sobald die Synchronisation fertig ist: standard, pro oder studio. Plan-, Dauer- und Credit-Regeln sind dieselben wie bei Übersetzung starten. Erfordert ein Videoprojekt.Standard: Feld weglassen, um den Lippensync zu überspringen.
boolean
Aktive-Sprecher-Erkennung für den angeforderten Lippensync-Lauf aktivieren.Standard: false
object
Feineinstellung des Stimmklonens als JSON-Objekt mit stability und similarity zwischen 0 und 1. Nur mit voiceMode: "cloning". Hinweise zu jedem Wert stehen bei Übersetzung starten.
array
Zeitbereiche der Quelle, die in der Originalsprache bleiben, als [{ "startTime": 10.2, "endTime": 12.8 }]. Erfordert ein Videoprojekt und keepBackgroundMusic: true, kann nicht mit keepOriginalVoice kombiniert werden und darf Transkriptsegmente nicht überlappen.

Antwort

boolean
erforderlich
Bei erfolgreichen Anfragen immer true.
string
erforderlich
Eine lesbare Bestätigung.
string
erforderlich
Das Projekt, das synchronisiert wird.
string
erforderlich
Die Übersetzungsarbeit für targetLanguage. Sie entspricht workId in den Endpunkten für Status, Details und Transkript.
number
erforderlich
Grobe Verarbeitungsschätzung in Minuten: fünf Minuten Verarbeitung je angefangener Minute des Quellmediums.
Response

Den Lauf verfolgen

Das Projekt wechselt in den Workflow translation, sobald die Synchronisation startet. Übersetzungsstatus abrufen folgt daher dem neuen Lauf: status geht von processing zu success (mit translatedVideoUrl und translatedAudioUrl) oder failed (mit error). Die Webhooks project.translation.completed und project.translation.failed werden mit derselben targetLanguage gesendet. In Projektdetails abrufen meldet die übersetzte Version settings.dubbingMode: "dub-only" und settings.smartSync: false. Ausrichtungsfehler treten auf, nachdem die POST-Anfrage angenommen wurde. Der Status-Endpunkt gibt status: "failed" mit error.code und error.message zurück; der Webhook project.translation.failed enthält denselben Code und dieselbe Nachricht. TRANSLATED_SRT_UNMATCHED_CUES nennt die nicht zugeordneten Cue-Nummern in der Nachricht, TRANSLATED_SRT_MISSING_SEGMENTS die Segmentindizes ohne Cue. Diese asynchronen Antworten enthalten kein strukturiertes details-Feld. Korrigieren Sie die SRT-Datei und rufen Sie den Endpunkt erneut auf: Die fehlgeschlagene Version bleibt im Projektverlauf, und eine neue wird erstellt.

Tempo prüfen

Exportieren Sie das übersetzte Transkript als JSON mit Projekttranskript exportieren. Jedes Segment trägt finalSpeedFactor, das Verhältnis zwischen der erzeugten Sprache und dem Segmentfenster. Kürzen Sie die Cues, die ungefähr über 1.3 liegen, und starten Sie die Synchronisation erneut mit dem überarbeiteten SRT.

Beispielablauf

Eine typische Automatisierung (zum Beispiel ein n8n- oder Make-Szenario) verkettet die Endpunkte so:
  1. POST /v1/projects mit dem Medium, targetLanguage und einer expliziten originalLanguage (nur Transkription).
  2. Fragen Sie GET /v1/translate/{projectId}/status ab, bis transcriptionStatus success ist, oder warten Sie auf den Webhook project.created.
  3. POST /v1/projects/{projectId}/transcript mit { "source": "original", "outputFormat": "srt" } und übersetzen Sie die Cues, wobei Nummerierung und Zeitcodes erhalten bleiben.
  4. POST /v1/projects/{projectId}/dub mit dem übersetzten SRT.
  5. Fragen Sie den Status-Endpunkt ab, bis status success ist, oder warten Sie auf project.translation.completed.
  6. Laden Sie translatedVideoUrl herunter (oder lipSync.videoUrl, wenn Lippensync angefordert wurde).
  7. DELETE /v1/translate/{projectId}, sobald die Ausgaben bei Ihnen gespeichert sind.

Fehler

Ausrichtungsfehler, die während der Ausführung erkannt werden (TRANSLATED_SRT_UNMATCHED_CUES, TRANSLATED_SRT_MISSING_SEGMENTS), liefert der Status-Endpunkt und der fehlgeschlagene Webhook, nicht diese Anfrage.