動画翻訳(HeyGen)
既存の動画を複数言語に翻訳・吹き替えし、リップシンクと自然な音声パターンを維持します。動画のURLまたはHeyGenビデオIDを指定するだけで、事前にHeyGenで動画を作成する必要はありません。
認証
すべてのリクエストには X-Api-Key ヘッダーが必要です。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"}'
デフォルトのワークフロー
- 動画のURLまたはHeyGenビデオIDを指定する
POST /v2/video_translateを呼び出してターゲット言語を指定するGET /v2/video_translate/{translate_id}をポーリングしてステータスがcompletedになるまで待つ- 返されたURLから翻訳済み動画をダウンロードする
翻訳ジョブの作成
リクエストフィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
video_url | string | Y* | 翻訳する動画のURL(*または video_id) |
video_id | string | Y* | HeyGenビデオID(*または video_url) |
output_language | string | Y | ターゲット言語コード(例: "es-ES") |
title | string | 翻訳後の動画の名前 | |
translate_audio_only | boolean | 音声のみ、リップシンクなし(高速) | |
speaker_num | number | 動画内の話者数 | |
callback_id | string | Webhook追跡用のカスタムID | |
callback_url | string | 完了通知用のURL |
video_url または video_id のいずれかを指定する必要があります。
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"]
対応言語
| 言語 | コード | 備考 |
|---|---|---|
| 英語(米国) | en-US | デフォルトのソース言語 |
| スペイン語(スペイン) | es-ES | ヨーロッパスペイン語 |
| スペイン語(メキシコ) | es-MX | ラテンアメリカ |
| フランス語 | fr-FR | 標準フランス語 |
| ドイツ語 | de-DE | 標準ドイツ語 |
| イタリア語 | it-IT | 標準イタリア語 |
| ポルトガル語(ブラジル) | pt-BR | ブラジルポルトガル語 |
| 日本語 | ja-JP | 標準日本語 |
| 韓国語 | ko-KR | 標準韓国語 |
| 中国語(北京語) | zh-CN | 簡体字中国語 |
| ヒンディー語 | hi-IN | 標準ヒンディー語 |
| アラビア語 | ar-SA | 現代標準アラビア語 |
翻訳オプション
基本翻訳(リップシンクあり)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
title: "Spanish Translation",
};
音声のみ翻訳(高速、リップシンクなし)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
translate_audio_only: true,
};
複数話者動画
const config = {
video_url: "https://example.com/interview.mp4",
output_language: "fr-FR",
speaker_num: 2,
};
高度なオプション(v4 API)
翻訳をより細かく制御するには:
interface VideoTranslateV4Request {
input_video_id?: string;
google_url?: string;
output_languages: string[]; // 一度に複数の言語を指定
name: string;
srt_key?: string; // カスタムSRT字幕
instruction?: string;
vocabulary?: string[]; // そのまま保持する用語
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;
}
複数の出力言語
const config = {
input_video_id: "original_video_id",
output_languages: ["es-ES", "fr-FR", "de-DE"],
name: "Multi-language translations",
};
カスタム語彙(特定の用語を保持)
const config = {
video_url: "https://example.com/product-demo.mp4",
output_language: "ja-JP",
vocabulary: ["SuperWidget", "Pro Max", "TechCorp"],
};
カスタムSRT字幕
const config = {
video_url: "https://example.com/video.mp4",
output_language: "es-ES",
srt_key: "path/to/custom-subtitles.srt",
srt_role: "input",
};
翻訳ステータスの確認
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;
}
完了までのポーリング
翻訳は標準的な動画生成よりも時間がかかります。最大30分を想定してください。
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 || "翻訳に失敗しました");
default:
console.log(`ステータス: ${status.status}...`);
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("翻訳がタイムアウトしました");
}
完全なワークフロー
async function translateAndDownload(
videoUrl: string,
targetLanguage: string
): Promise<string> {
console.log(`${targetLanguage}への翻訳を開始...`);
const translateId = await translateVideo({
video_url: videoUrl,
output_language: targetLanguage,
});
console.log(`翻訳ID: ${translateId}`);
console.log("翻訳を処理中...");
const translatedVideoUrl = await waitForTranslation(translateId);
console.log(`翻訳完了: ${translatedVideoUrl}`);
return translatedVideoUrl;
}
const spanishVideo = await translateAndDownload(
"https://example.com/my-video.mp4",
"es-ES"
);
バッチ翻訳
複数の言語に並行して翻訳:
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.message}`;
}
}
return results;
}
const translations = await translateToMultipleLanguages(
"https://example.com/original.mp4",
["es-ES", "fr-FR", "de-DE", "ja-JP"]
);
機能
- リップシンク — 翻訳された音声に合わせて話者の口の動きを自動調整
- 声のクローン — 翻訳された音声が元の話者の声の特徴と一致
- 音楽トラック制御 —
disable_music_track: trueで背景音楽をオプションで除去 - 音声強調 —
enable_speech_enhancement: trueで音質向上
ベストプラクティス
- ソースの品質が重要 — 高品質なソース動画を使用すると結果が向上
- クリアな音声 — 明瞭な発話の動画の方が翻訳品質が高い
- 単一話者 — 単一話者のコンテンツで最高の結果
- 適度なペース — 非常に速い発話は品質に影響する可能性あり
- 事前テスト — 長い動画を翻訳する前に短いクリップで試す
- 時間に余裕を持つ — 翻訳は動画生成より時間がかかる(最大30分)
エラーハンドリング
一般的なエラーとその対処方法:
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: "クレジットが不足しています" };
}
if (error.message.includes("duration")) {
return { success: false, error: "動画が長すぎます" };
}
if (error.message.includes("format")) {
return { success: false, error: "サポートされていない動画形式です" };
}
return { success: false, error: error.message };
}
}