ElevenLabs 吹替え

ElevenLabs 吹替え は何をしますか？

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

重要: Dubbing Projects API — SDK では elevenlabs.dubbing.project.*、REST では /v1/dubbing/project エンドポイントを使用してください。レガシーな v1 吹替え API (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 ヘッダーに指定します。

概念

概念	意味
プロジェクト	1つのメディアソース（ファイルまたはURL）とそのソース文字起こし。一度準備（文字起こし）され、言語を追加している間は ready 状態で待機します。
ソース文字起こし	ソースから文字起こしされた編集可能なセグメント（テキスト、話者、タイミング）。すべての言語が翻訳元とする唯一の真実の情報源です。
言語（ターゲット）	1つの吹替え出力言語。それぞれに独自の文字起こし（ソースセグメント + セグメントごとの翻訳）と吹替え音声出力があります。
リビジョン	独立した単調増加カウンター。プロジェクトの revision はソース文字起こしの編集で増加し、言語の revision は翻訳編集またはそれに影響するソース編集で増加します。言語の output_revision は現在の音声が生成されたリビジョンです。revision より小さい場合、出力は最新ではありません。

推奨される操作順序: 言語を追加する前にソース文字起こしを確定させてください。翻訳はソースから生成されるため、最初にソースを修正することで、すべての言語が正しいテキストから開始されます。言語完了後にソースを編集すると、その言語は stale とマークされ、（課金される）再生成が必要になります。

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

ワークフロー

1. プロジェクトを作成（ファイルまたはURLから）→ queued
2. プロジェクトをポーリングして ready になるまで待つ
3. ソース文字起こしを確認・確定（セグメントの編集/追加/削除）
4. ターゲット言語を1つずつ追加 → queued → processing → completed
5. 各言語の outputs.lossless_audio をダウンロード（completed 状態の場合）
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. ローカルファイルからプロジェクトを作成（file の代わりに source_url=... を渡すことも可能）
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Q3 マーケティング動画",
    )

# 2. ソースメディアの文字起こしが完了するのを待つ
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("プロジェクトの準備に失敗しました")
    time.sleep(5)

# 3. スペイン語のターゲット言語を追加
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. 吹替えの生成が完了するのを待つ
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("吹替えの生成に失敗しました")
    time.sleep(5)

# 5. 吹替え音声をダウンロード（署名付きURL、有効期限は約1時間 — 新しいURLを取得するには言語を再取得）
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. プロジェクトを作成（sourceUrl を表示；ファイルアップロードもサポート）
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Q3 マーケティング動画",
});

// 2. ソースメディアの文字起こしが完了するのを待つ
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("プロジェクトの準備に失敗しました");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. スペイン語のターゲット言語を追加
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. 吹替えの生成が完了するのを待つ
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("吹替えの生成に失敗しました");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. 署名付き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. プロジェクトを作成（URLから吹替えたい場合は --source-url "https://..." を --file の代わりに使用）
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. ステータスが "ready" になるまでポーリング
elevenlabs dubbing project get --project-id proj_...

# 3. ターゲット言語を追加
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. 言語が "completed" になるまでポーリングし、その後 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 があります。（エンタープライズワークスペースのみ）

# ソース文字起こしを読む
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# セグメントのテキストを修正 — 変更するフィールドのみを送信（text, speaker_id, start_s, end_s）
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="最新の製品デモへようこそ。",
)

# セグメントを追加（既存の speaker_id を再利用して、その話者の声で吹き替える）
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="ご視聴ありがとうございました。",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

# セグメントを削除
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 "最新の製品デモへようこそ。"

翻訳の調整と再生成

言語の文字起こしは、各ソースセグメントとその translation をペアにします（null = 未翻訳、セグメント ID はソースと一致）。単一の翻訳を編集し、再生成します。（エンタープライズワークスペースのみ）

# 言語の翻訳を読む
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# 単一の翻訳を調整（translation=None を渡すとクリアされ、再翻訳対象としてマーク）
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.",
)

# 現在の文字起こしから吹替えを再生成（生成と同様に課金されます）
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メソッド名を掲載