Videotranslation (HeyGen)
Übersetzen und synchronisieren Sie bestehende Videos in mehrere Sprachen und bewahren Sie dabei die Lippenbewegungen sowie natürliche Sprachmuster. Sie können eine Video-URL oder eine HeyGen-Video-ID angeben – ohne das Video vorher in HeyGen erstellen zu müssen.
Authentifizierung
Alle Anfragen benötigen den X-Api-Key-Header. Setzen Sie die Umgebungsvariable HEYGEN_API_KEY.
curl -X POST "https://api.heygen.com/v2/video_translate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"video_url": "https://example.com/video.mp4", "output_language": "es-ES"}'
Standard-Workflow
- Geben Sie eine Video-URL oder eine HeyGen-Video-ID an
- Rufen Sie
POST /v2/video_translatemit der Zielsprache auf - Pollen Sie
GET /v2/video_translate/{translate_id}, bis der Statuscompletedist - Laden Sie das übersetzte Video von der zurückgegebenen URL herunter
Erstellen eines Übersetzungsauftrags
Anfragefelder
| Feld | Typ | Erf. | Beschreibung |
|---|---|---|---|
video_url | string | J* | URL des zu übersetzenden Videos (*oder video_id) |
video_id | string | J* | HeyGen-Video-ID (*oder video_url) |
output_language | string | J | Zielsprachcode (z. B. "es-ES") |
title | string | Name für das übersetzte Video | |
translate_audio_only | boolean | Nur Audio, kein Lip-Sync (schneller) | |
speaker_num | number | Anzahl der Sprecher im Video | |
callback_id | string | Benutzerdefinierte ID für Webhook-Tracking | |
callback_url | string | URL für Benachrichtigung bei Fertigstellung |
Entweder video_url oder video_id muss angegeben werden.
curl
curl -X POST "https://api.heygen.com/v2/video_translate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/original-video.mp4",
"output_language": "es-ES",
"title": "Spanish Version"
}'
TypeScript
interface VideoTranslateRequest {
video_url?: string;
video_id?: string;
output_language: string;
title?: string;
translate_audio_only?: boolean;
speaker_num?: number;
callback_id?: string;
callback_url?: string;
}
interface VideoTranslateResponse {
error: null | string;
data: {
video_translate_id: string;
};
}
async function translateVideo(config: VideoTranslateRequest): Promise<string> {
const response = await fetch("https://api.heygen.com/v2/video_translate", {
method: "POST",
headers: {
"X-Api-Key": process.env.HEYGEN_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify(config),
});
const json: VideoTranslateResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data.video_translate_id;
}
Python
import requests
import os
def translate_video(config: dict) -> str:
response = requests.post(
"https://api.heygen.com/v2/video_translate",
headers={
"X-Api-Key": os.environ["HEYGEN_API_KEY"],
"Content-Type": "application/json"
},
json=config
)
data = response.json()
if data.get("error"):
raise Exception(data["error"])
return data["data"]["video_translate_id"]
Unterstützte Sprachen
| Sprache | Code | Hinweise |
|---|---|---|
| Englisch (US) | en-US | Standard-Quellsprache |
| Spanisch (Spanien) | es-ES | Europäisches Spanisch |
| Spanisch (Mexiko) | es-MX | Lateinamerikanisch |
| Französisch | fr-FR | Standard-Französisch |
| Deutsch | de-DE | Standard-Deutsch |
| Italienisch | it-IT | Standard-Italienisch |
| Portugiesisch (Brasilien) | pt-BR | Brasilianisches Portugiesisch |
| Japanisch | ja-JP | Standard-Japanisch |
| Koreanisch | ko-KR | Standard-Koreanisch |
| Chinesisch (Mandarin) | zh-CN | Vereinfachtes Chinesisch |
| Hindi | hi-IN | Standard-Hindi |
| Arabisch | ar-SA | Modernes Hocharabisch |
Übersetzungsoptionen
Basis-Übersetzung (mit Lippen-Synchronisation)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
title: "Spanish Translation",
};
Audio-Only-Übersetzung (schneller, kein Lip-Sync)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
translate_audio_only: true,
};
Videos mit mehreren Sprechern
const config = {
video_url: "https://example.com/interview.mp4",
output_language: "fr-FR",
speaker_num: 2,
};
Erweiterte Optionen (v4 API)
Für mehr Kontrolle über die Übersetzung:
interface VideoTranslateV4Request {
input_video_id?: string;
google_url?: string;
output_languages: string[]; // Mehrere Sprachen in einem Aufruf
name: string;
srt_key?: string; // Benutzerdefinierte SRT-Untertitel
instruction?: string;
vocabulary?: string[]; // Begriffe, die unverändert bleiben sollen
brand_voice_id?: string;
speaker_num?: number;
keep_the_same_format?: boolean;
input_language?: string;
enable_video_stretching?: boolean;
disable_music_track?: boolean;
enable_speech_enhancement?: boolean;
srt_role?: "input" | "output";
translate_audio_only?: boolean;
}
Mehrere Ausgabesprachen
const config = {
input_video_id: "original_video_id",
output_languages: ["es-ES", "fr-FR", "de-DE"],
name: "Multi-language translations",
};
Benutzerdefiniertes Vokabular (bestimmte Begriffe erhalten)
const config = {
video_url: "https://example.com/product-demo.mp4",
output_language: "ja-JP",
vocabulary: ["SuperWidget", "Pro Max", "TechCorp"],
};
Benutzerdefinierte SRT-Untertitel
const config = {
video_url: "https://example.com/video.mp4",
output_language: "es-ES",
srt_key: "path/to/custom-subtitles.srt",
srt_role: "input",
};
Abfragen des Übersetzungsstatus
curl
curl -X GET "https://api.heygen.com/v2/video_translate/{translate_id}" \
-H "X-Api-Key: $HEYGEN_API_KEY"
TypeScript
interface TranslateStatusResponse {
error: null | string;
data: {
id: string;
status: "pending" | "processing" | "completed" | "failed";
video_url?: string;
message?: string;
};
}
async function getTranslateStatus(translateId: string): Promise<TranslateStatusResponse["data"]> {
const response = await fetch(
`https://api.heygen.com/v2/video_translate/${translateId}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const json: TranslateStatusResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data;
}
Abrufen des Abschlusses (Polling)
Übersetzungen dauern länger als die Standard-Videogenerierung – rechnen Sie mit bis zu 30 Minuten.
async function waitForTranslation(
translateId: string,
maxWaitMs = 1800000,
pollIntervalMs = 30000
): Promise<string> {
const startTime = Date.now();
while (Date.now() - startTime < maxWaitMs) {
const status = await getTranslateStatus(translateId);
switch (status.status) {
case "completed":
return status.video_url!;
case "failed":
throw new Error(status.message || "Translation failed");
default:
console.log(`Status: ${status.status}...`);
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("Translation timed out");
}
Kompletter Workflow
async function translateAndDownload(
videoUrl: string,
targetLanguage: string
): Promise<string> {
console.log(`Starting translation to ${targetLanguage}...`);
const translateId = await translateVideo({
video_url: videoUrl,
output_language: targetLanguage,
});
console.log(`Translation ID: ${translateId}`);
console.log("Processing translation...");
const translatedVideoUrl = await waitForTranslation(translateId);
console.log(`Translation complete: ${translatedVideoUrl}`);
return translatedVideoUrl;
}
const spanishVideo = await translateAndDownload(
"https://example.com/my-video.mp4",
"es-ES"
);
Batch-Übersetzung
Parallel in mehrere Sprachen übersetzen:
async function translateToMultipleLanguages(
sourceVideoUrl: string,
targetLanguages: string[]
): Promise<Record<string, string>> {
const results: Record<string, string> = {};
const translatePromises = targetLanguages.map(async (lang) => {
const translateId = await translateVideo({
video_url: sourceVideoUrl,
output_language: lang,
});
return { lang, translateId };
});
const translationJobs = await Promise.all(translatePromises);
for (const job of translationJobs) {
try {
const videoUrl = await waitForTranslation(job.translateId);
results[job.lang] = videoUrl;
} catch (error) {
results[job.lang] = `error: ${error.message}`;
}
}
return results;
}
const translations = await translateToMultipleLanguages(
"https://example.com/original.mp4",
["es-ES", "fr-FR", "de-DE", "ja-JP"]
);
Funktionen
- Lip Sync – Passt die Lippenbewegungen des Sprechers automatisch an die übersetzte Tonspur an
- Voice Cloning – Die übersetzte Tonspur behält die Stimmcharakteristiken des Originalsprechers bei
- Musikspur-Steuerung – Entfernen Sie optional Hintergrundmusik mit
disable_music_track: true - Sprachverbesserung – Verbessern Sie die Audioqualität mit
enable_speech_enhancement: true
Best Practices
- Qualität der Quelle – Verwenden Sie hochwertige Quellvideos für bessere Ergebnisse
- Klare Audiospur – Videos mit klarer Sprache werden besser übersetzt
- Einzelsprecher – Beste Ergebnisse mit Inhalten, die nur einen Sprecher haben
- Mäßiges Tempo – Sehr schnelle Sprache kann die Qualität beeinträchtigen
- Testen zuerst – Versuchen Sie es mit kürzeren Clips, bevor Sie lange Videos übersetzen
- Zusätzliche Zeit einplanen – Die Übersetzung dauert länger als die Videogenerierung (bis zu 30 Min.)
Fehlerbehandlung
Häufige Fehler und wie man sie behandelt:
async function safeTranslate(
videoUrl: string,
targetLanguage: string
): Promise<{ success: boolean; result?: string; error?: string }> {
try {
const url = await translateAndDownload(videoUrl, targetLanguage);
return { success: true, result: url };
} catch (error) {
if (error.message.includes("quota")) {
return { success: false, error: "Nicht genügend Credits" };
}
if (error.message.includes("duration")) {
return { success: false, error: "Video zu lang" };
}
if (error.message.includes("format")) {
return { success: false, error: "Nicht unterstütztes Videoformat" };
}
return { success: false, error: error.message };
}
}