ElevenLabs 配音技術是做什麼的？

將音訊或影片配音成其他語言，同時保留原始說話者的聲音。可從檔案或 URL 建立專案，審閱和編輯原始轉錄稿，新增一個或多個目標語言，精細調整各段落的翻譯，並重新產生輸出。

重要事項： 請使用 Dubbing 專案 API — 在 SDK 中為 elevenlabs.dubbing.project.*，或 REST 端點 /v1/dubbing/project。請勿使用舊版 v1 配音介面 (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，並在 xi-api-key 標頭中傳入您的 API 金鑰。

概念

概念	意義
專案	一個來源媒體（檔案或 URL）及其來源轉錄稿。準備（轉錄）一次後，會保持在 `ready` 狀態，直到您新增語言。
來源轉錄稿	從來源轉錄的可編輯段落（文字、說話者、時間）。所有語言翻譯的單一事實來源。
語言（目標）	一個配音輸出語言。每個語言都有自己的轉錄稿（來源段落 + 每個段落的翻譯）以及自己的配音音訊輸出。
修訂版本	獨立的單調計數器。專案的 `revision` 在來源轉錄稿編輯時增加；語言的 `revision` 在其翻譯編輯或受影響的來源編輯時增加。語言的 `output_revision` 是其目前音訊產生時所使用的修訂版本 — 如果落後於 `revision`，則輸出已過時。

建議的操作順序： 在新增任何語言之前，請先完成來源轉錄稿。翻譯是根據來源產生的，因此先修正來源可確保每個語言都從正確的文字開始 — 在語言完成後編輯來源會將其標記為 stale，並需要（收費的）重新產生。

企業方案： 轉錄稿編輯和重新產生僅適用於企業工作區。建立專案、新增語言和下載配音則適用於所有方案。

工作流程

建立專案（從檔案或 URL）→ queued
輪詢專案直到 ready
審閱並完成來源轉錄稿 （編輯/新增/刪除段落）
新增每個目標語言 → queued → processing → completed
下載每個語言的 outputs.lossless_audio（當狀態為 completed 時）
精細調整 各段落的翻譯（如有需要）→ 語言進入 stale 狀態
重新產生 語言 → 再次變為 completed，並提供全新的輸出

快速開始（Python）

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

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

# 1. 從本地檔案建立專案（或使用 source_url=... 替代檔案）
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Q3 marketing video",
    )

# 2. 等待來源媒體轉錄完成
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. 新增西班牙語目標語言
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("Dub generation failed")
    time.sleep(5)

# 5. 下載配音音訊（簽署網址，有效期約 1 小時 — 重新擷取語言以取得新網址）
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 marketing video",
});

// 2. 等待來源媒體轉錄完成
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. 新增西班牙語目標語言
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("Dub generation failed");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. 從簽署網址下載配音音訊
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

快速開始（CLI）

elevenlabs CLI 會自動從環境變數讀取 ELEVENLABS_API_KEY。

# 1. 建立專案（使用 --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）	用於擷取來源媒體的公開網址
`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="Welcome to our latest product demo.",
)

# 新增段落（重複使用現有的 speaker_id，以便使用該說話者的聲音進行配音）
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,
)

# 刪除段落
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 與來源相符）。編輯單一翻譯，然後重新產生。（僅限企業工作區。）

# 讀取語言的翻譯
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 反映當前的轉錄稿。

配音成多種語言

每個語言新增一個語言目標 — 各自獨立產生。使用 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` 填入簽署的下載網址（有效期約 1 小時 — 重新擷取以取得新網址）
`stale`	先前已完成，但轉錄稿已變更；保持最後的輸出直到重新產生
`failed`	產生失敗

您可以在專案變為 ready 之前新增語言 — 它會保持在 queued 狀態，並在專案變為 ready 時自動開始。新增語言時可選擇接受 model_id（預設為專案的）和 voice_settings（例如 {"cloning_strength": 7}，範圍 0–10，預設 7 — 控制配音說話者模仿來源聲音的強度）。

錯誤處理

401：無效的 API 金鑰
409 Conflict（重新產生時）：專案未處於 ready 狀態，或語言未穩定（例如正在產生中）— 請等待並重試
下載網址過期：outputs.lossless_audio 是簽署網址，有效期約 1 小時；請重新擷取語言以取得新的網址
轉錄稿編輯 / 重新產生不可用：這些端點僅限企業方案 — 在其他方案中，請使用已完成的來源建立專案，並直接新增語言

參考資料

安裝指南
API 參考 — 每個端點，包含完整的請求/回應架構和 SDK 方法名稱

ElevenLabs 配音技術