dubbing

ElevenLabs 配音

将音频或视频配成其他语言，同时保留原说话者的声音。通过文件或 URL 创建项目，审核并编辑源转录文本，添加一种或多种目标语言，逐段润色译文，并重新生成输出。

**重要提示：**请使用配音项目 API——SDK 中的 elevenlabs.dubbing.project.*，或 /v1/dubbing/project REST 端点。不要使用旧版 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，并需要付费重新生成。

**企业版：**只有企业工作区可编辑转录文本和重新生成。所有套餐均可创建项目、添加语言和下载配音。

工作流

1. 创建项目，使用文件或 URL → queued
2. 轮询项目，直到状态变为 ready
3. 审核并完成源转录文本（编辑／添加／删除片段）
4. 每个目标添加一种语言 → 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 与源文本一致）。编辑单条翻译，然后重新生成。（仅限 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 反映当前转录文本。

配音为多种语言

每种语言添加一个语言目标——每种语言都会独立生成。使用 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（默认使用项目的 model_id）和 voice_settings（例如 {"cloning_strength": 7}，范围为 0–10，默认值为 7——用于控制配音说话者克隆源语音的程度）。

错误处理

• 401：API 密钥无效
• 再生成时发生 409 Conflict：项目尚未处于 ready 状态，或语言尚未确定（例如正在生成）——请等待后重试
• 下载 URL 已过期：outputs.lossless_audio 是签名 URL，有效期约为 1 小时；重新获取该语言即可获得新的 URL
• 无法编辑转录文本或重新生成：这些端点仅供企业版使用；其他套餐请使用已定稿的源内容创建项目，并直接添加语言

参考资料

• 安装指南
• API 参考 — 每个端点的完整请求/响应架构和 SDK 方法名称