dubbing

ElevenLabs Dubbing

元の話者の声を保ちながら、音声や動画をほかの言語に吹き替えます。ファイルまたは URL からプロジェクトを作成し、元の文字起こしを確認・編集して、1 つ以上の対象言語を追加し、セグメントごとに翻訳を調整して、出力を再生成できます。

重要: Dubbing Projects API を使用してください。SDK では elevenlabs.dubbing.project.*、REST では /v1/dubbing/project エンドポイントを使用します。レガシーの v1 dubbing インターフェース（client.dubbing.create()、client.dubbing.get()、client.dubbing.audio.get()、または /v1/dubbing 単体のルート）は使用しないでください。これは以前の吹き替え API で、現在は API リファレンスの Legacy にあります。

セットアップ（コードを書く前に実施）: このプロジェクトで ELEVENLABS_API_KEY が設定されていない場合は、まずアプリのフォルダーから npx -y @elevenlabs/cli@latest onboard init を実行し、表示される手順に従ってください。ユーザーがサインインすると、プロジェクト用のキーが保存されるため、誰も手動でキーをコピーする必要はありません。それ以外の場合は、インストールガイドを参照してください。elevenlabs CLI と SDK は ELEVENLABS_API_KEY を自動的に読み取ります。REST のベース URL は https://api.elevenlabs.io で、API キーは xi-api-key ヘッダーに指定します。

概念

概念	意味
プロジェクト	メディア（ファイルまたは URL）とその元の文字起こしをまとめたものです。1 回だけ準備（文字起こし）され、その後は言語を追加する間、ready の状態になります。
元の文字起こし	ソースから文字起こしされた編集可能なセグメント（テキスト、話者、タイミング）です。すべての言語の翻訳元となる唯一の情報源です。
言語（対象）	吹き替えの出力言語です。それぞれに固有の文字起こし（元のセグメントと各セグメントの翻訳）と、吹き替え音声の出力があります。
リビジョン	独立した単調増加カウンターです。元の文字起こしを編集するとプロジェクトの revision が増加し、翻訳の編集や、該当する元の文字起こしの編集を行うと、その言語の revision が増加します。言語の output_revision は、現在の音声が生成されたリビジョンです。revision より小さい場合、出力は古くなっています。

推奨する操作順序: 言語を追加する前に、元の文字起こしを確定してください。翻訳は元の文字起こしから作成されるため、先に元の文字起こしを修正しておけば、すべての言語が正しいテキストから始まります。言語の処理が完了した後で元の文字起こしを編集すると、その言語は stale になり、（料金が発生する）再生成が必要になります。

Enterprise: 文字起こしの編集と再生成は、Enterprise ワークスペースでのみ利用できます。プロジェクトの作成、言語の追加、吹き替え音声のダウンロードは、すべてのプランで利用できます。

ワークフロー

1. 作成：ファイルまたは URL からプロジェクトを作成 → queued
2. ポーリング：プロジェクトが ready になるまで確認
3. 元の文字起こしを確認して確定（セグメントの編集・追加・削除）
4. 追加：対象ごとに言語を 1 つ追加 → queued → processing → completed
5. completed になったら、各言語の outputs.lossless_audio をダウンロード
6. 必要に応じて、セグメントごとに翻訳を調整 → 言語が stale になる
7. 言語を再生成 → 新しい出力で再び completed

クイックスタート（Python）

import os
import time
import requests
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

# 1. Create a project from a local file (or pass source_url=... instead of file)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Q3 marketing video",
    )

# 2. Wait for the source media to be transcribed
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("Project preparation failed")
    time.sleep(5)

# 3. Add a Spanish language target
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Wait for the dub to finish generating
while True:
    language = elevenlabs.dubbing.project.language.get(
        project.project_id, language.language_id
    )
    if language.status == "completed":
        break
    if language.status == "failed":
        raise RuntimeError("Dub generation failed")
    time.sleep(5)

# 5. Download the dubbed audio (signed URL, valid ~1 hour — re-fetch the language for a fresh one)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

クイックスタート（JavaScript）

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { writeFile } from "fs/promises";

const elevenlabs = new ElevenLabsClient();

// 1. Create a project (sourceUrl shown; file upload is also supported)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Q3 marketing video",
});

// 2. Wait for the source media to be transcribed
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("Project preparation failed");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Add a Spanish language target
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Wait for the dub to finish generating
while (true) {
  language = await elevenlabs.dubbing.project.language.get(project.projectId, language.languageId);
  if (language.status === "completed") break;
  if (language.status === "failed") throw new Error("Dub generation failed");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Download the dubbed audio from the signed URL
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

クイックスタート（CLI）

elevenlabs CLI は、環境変数から ELEVENLABS_API_KEY を自動的に読み取ります。

# 1. Create a project (use --source-url "https://..." instead of --file to dub from a URL)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Poll until status is "ready"
elevenlabs dubbing project get --project-id proj_...

# 3. Add a target language
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. Poll the language until "completed", then download outputs.lossless_audio
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

作成オプション

elevenlabs dubbing project create（REST：POST /v1/dubbing/project、multipart/form-data）では、file または source_url のどちらか一方を指定します（両方は指定できません）。

フィールド	必須	備考
file	file/source_url のいずれか	吹き替え元のメディア（音声または動画）。最大 3 GiB
source_url	file/source_url のいずれか	吹き替え元メディアを取得する公開 URL
source_language	いいえ	ISO 639 コード（例：en）。省略すると自動検出され、検出された言語はソース文字起こしの language フィールドに報告されます
reference	いいえ	プロジェクトを識別するための任意のラベル（最大 500 文字）
model_id	いいえ	dubbing_v2（デフォルト）
target_language	いいえ	作成時に最初の言語ターゲットをキューに追加できます。さらに追加するには language.create を使用します
keyterms	いいえ	文字起こし／翻訳で優先する用語（製品名／ブランド名）。最大 1000 個、各用語は最大 50 文字かつ 5 語まで。<>{}[]\ は使用できません。multipart では用語ごとにフィールドを繰り返します

ソース文字起こしの編集

プロジェクトが ready になったら、言語を追加する前に文字起こしを読み取り、修正します。編集するたびにプロジェクトの revision が更新されます。各セグメントには、編集または削除に使用する固定の id があります。（Enterprise ワークスペースのみ。）

# Read the source transcript
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# Correct a segment's text — send only the fields to change (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="Welcome to our latest product demo.",
)

# Add a segment (reuse an existing speaker_id so it's dubbed with that speaker's voice)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="Thanks for watching.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

# Delete a segment
elevenlabs.dubbing.project.transcript.delete_segment(project_id, segment_id=added.segment.id)

CLI では、elevenlabs dubbing project transcript get --project-id proj_... を実行し、変更したフィールドのみ（--text、--speaker-id、--start-s、--end-s）を指定してセグメントを更新します。

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "Welcome to our latest product demo."

翻訳の調整と再生成

言語の文字起こしでは、各ソースセグメントとその translation（null は未翻訳を示します）が対応付けられています（セグメント ID はソースと一致します）。1 つの翻訳を編集してから、再生成します。（Enterprise ワークスペースのみ。）

# Read the language's translations
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# Refine a single translation (pass translation=None to clear it and mark for re-translation)
elevenlabs.dubbing.project.language.transcript.update_segment(
    project_id,
    language_id,
    segment_id=target.segments[0].id,
    translation="Bienvenido a nuestra última demostración de producto.",
)

# Regenerate the dub from the current transcript (charged like a generation)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

CLI では、elevenlabs dubbing project language transcript update_segment --project-id proj_... --language-id lang_... --segment-id seg_... --translation "..." を実行し、続いて elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... を実行します（202 Accepted が返されます）。

翻訳の編集は、その言語にのみ影響します。編集後、completed の言語は stale になり、再生成されるまでは以前の出力を提供し続けます。completed になるまでポーリングしてください。その後、output_revision は revision と等しくなり、outputs.lossless_audio には現在の文字起こしが反映されます。

複数言語への吹き替え

言語ごとに言語ターゲットを 1 つ追加します。各ターゲットは個別に生成されます。1 つずつポーリングする代わりに、language.list を使ってすべての状態を確認します。

for lang in ["es", "fr", "de", "ja"]:
    elevenlabs.dubbing.project.language.create(project_id, target_language=lang)

while True:
    result = elevenlabs.dubbing.project.language.list(project_id)
    if not any(l.status in ("queued", "processing") for l in result.languages):
        break
    time.sleep(5)

状態

プロジェクト：

ステータス	意味
queued	作成済み。ソースの取得と準備がキューに追加されています
preparing	準備（文字起こし）を実行中です
ready	ソース文字起こしを利用できます。言語の追加／生成が可能です。プロジェクトは ready のままです。言語ごとの進行状況は各言語側で管理されます
failed	準備に失敗しました（例：ソースを取得またはデコードできなかった場合）

言語：

ステータス	意味
queued	プロジェクトが ready になるのを待機中、または生成ワーカーを待機中です
processing	吹き替えを生成中です
completed	完了しました。outputs に署名付きダウンロード URL が設定されます（有効期限は約 1 時間です。新しい URL を取得するには再取得してください）
stale	以前は完了していましたが、文字起こしが変更されました。再生成されるまでは最後の出力を保持します
failed	生成に失敗しました

プロジェクトが ready になる前に言語を追加できます。その場合、言語は queued のままになり、プロジェクトが ready になると自動的に開始されます。言語の追加時には、オプションで model_id（デフォルトはプロジェクトの値）と voice_settings（例：{"cloning_strength": 7}。範囲は 0～10、デフォルトは 7。吹き替え音声の話者がソースの声をどの程度強くクローンするかを制御します）を指定できます。

エラー処理

• 401：API キーが無効です
• 再生成時の 409 Conflict：プロジェクトが ready ではないか、言語が確定していません（例：すでに生成中）。しばらく待ってから再試行してください
• ダウンロード URL の有効期限切れ：outputs.lossless_audio は署名付きで、有効期間は約 1 時間です。新しい URL を取得するには、言語を再取得してください
• トランスクリプトの編集／再生成が利用できない場合：これらのエンドポイントはエンタープライズプラン専用です。他のプランでは、確定済みのソースを使用してプロジェクトを作成し、言語を直接追加してください

参考資料

• インストールガイド
• API リファレンス — すべてのエンドポイントの完全なリクエスト／レスポンススキーマと SDK メソッド名