ElevenLabs 配音是做什么的？

将音频或视频配音成其他语言，同时保留原始说话人的声音。从文件或 URL 创建项目，审阅和编辑源转录文本，添加一个或多个目标语言，逐段优化翻译并重新生成输出。

重要： 请使用 Dubbing Projects 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，API 密钥放在 xi-api-key 请求头中。

概念

概念	含义
项目	一个源媒体（文件或 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. 下载配音音频（签名 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 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. 从签名 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. 创建项目（使用 --source-url "https://..." 代替 --file 以从 URL 配音）
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="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` 填充了签名下载 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 是签名 URL，有效期约 1 小时；重新获取语言信息以获取新 URL
转录编辑/重新生成不可用：这些端点是企业版专有的——在其他计划中，请使用最终确定的源媒体创建项目，然后直接添加语言

参考

安装指南
API 参考 —— 每个端点的完整请求/响应模式以及 SDK 方法名称

ElevenLabs 配音