> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 配音快速入门

本指南介绍如何使用配音 API 将媒体文件配音为另一种语言。本示例将从英语音频文件创建配音项目，并生成西班牙语配音。

配音项目包含两部分：一个**项目**，其中包含一份源媒体及其转录文本；以及一个或多个**语言目标**，每个目标生成单一语言的配音输出。先创建项目，等待其源媒体完成转录，再添加语言，最后下载完成的配音。

> **Note**
>
> 创建项目时会预先收取一种语言的费用，这是配音项目的最低收费。
> 这会预付第一个语言目标：添加的第一个语言将使用这项额度，之后每增加一种
> 语言都会单独收费。详情请参阅[配音费用是多少？](/docs/zh/help-center/product/dubbing/how-much-does-dubbing-cost)。

语言使用 BCP-47 标签指定，例如 `es` 或 `fr-CA`。有关所有可接受值，请参阅[支持的语言和方言](/docs/zh/overview/capabilities/dubbing#supported-languages)。

## 使用配音 API

#### 创建 API 密钥

[在控制台中创建 API 密钥](https://elevenlabs.io/app/api/api-keys)，用于安全地[访问 API](/docs/zh/api-reference/authentication)。

将密钥作为受管理的机密信息存储，并根据偏好，通过 `.env` 文件将其作为环境变量传递给 SDK，或直接写入应用配置。

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### 安装 SDK

#### SDK

我们还会使用 `dotenv` 库从环境变量加载 API 密钥。

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

安装 ElevenLabs CLI。推荐使用 Homebrew（macOS）和 Scoop（Windows）。

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

然后进行身份验证——这会打开浏览器以授权 CLI：

```bash
elevenlabs auth login
```

> **Note**
>
> Python 示例使用 `requests` 库下载配音音频。请使用 `pip install requests`
> 安装。

#### 发起 API 请求

#### SDK

根据所选语言创建名为 `example.py` 或 `example.mts` 的新文件，并添加以下代码：

```python maxLines=0
# example.py
import os
import time
import requests
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

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

# 1. Create a project from a source URL
project = elevenlabs.dubbing.project.create(
    source_url="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
    source_language="en",
    reference="Quickstart dub",
)

# 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")
    print("Preparing project...")
    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")
    print("Generating dub...")
    time.sleep(5)

# 5. Download the dubbed audio from the signed URL
audio = requests.get(language.outputs.lossless_audio)
with open("dubbed.wav", "wb") as f:
    f.write(audio.content)

print("Saved dubbed audio to dubbed.wav")
```

```typescript maxLines=0
// example.mts
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { writeFile } from "fs/promises";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

// 1. Create a project from a source URL
let project = await elevenlabs.dubbing.project.create({
  sourceUrl:
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
  sourceLanguage: "en",
  reference: "Quickstart dub",
});

// 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");
  console.log("Preparing project...");
  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");
  console.log("Generating dub...");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

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

console.log("Saved dubbed audio to dubbed.wav");
```

> **Note**
>
> `outputs.lossless_audio` 中的下载 URL 已签名，会在签发约 1 小时后
> 过期。如已过期，请再次获取该语言以取得新的 URL。

然后运行：

```python
python example.py
```

```typescript
npx tsx example.mts
```

配音音频将保存到工作目录中的 `dubbed.wav`。

#### CLI

CLI 的流程相同。每个步骤都会输出 JSON——请将响应中的 `project_id` 和
`language_id` 复制到下一条命令中，并轮询 `get` 命令，
直到状态稳定。

```bash
# 1. Create a project from a source URL (note the returned project_id)
elevenlabs dubbing project create \
  --source-url https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 \
  --source-language en \
  --reference "Quickstart dub"

# 2. Poll until the project status is "ready"
elevenlabs dubbing project get --project-id <project_id> --query status

# 3. Add a Spanish language target (note the returned language_id)
elevenlabs dubbing project language create --project-id <project_id> --target-language es

# 4. Poll until the language status is "completed"
elevenlabs dubbing project language get \
  --project-id <project_id> --language-id <language_id> --query status

# 5. Get the signed download URL, then save the dubbed audio
elevenlabs dubbing project language get \
  --project-id <project_id> --language-id <language_id> --query outputs.lossless_audio

curl -o dubbed.wav "<lossless_audio_url>"
```

配音音频将保存到工作目录中的 `dubbed.wav`。

## 处理失败情况

如果添加语言失败，请将相同语言再次添加到现有项目，而不是创建新项目。项目及其已转录的源媒体可重复使用，因此重试语言会更快，也能避免再次支付[单语言最低费用](/docs/zh/help-center/product/dubbing/how-much-does-dubbing-cost)。

仅当项目本身在准备过程中变为 `failed` 时才创建新项目，这表示其源媒体无法完成转录。请检查源文件或 URL，然后创建新项目。

> **Tip**
>
> 企业版工作区可在添加语言前审核和修正源转录文本，从而生成更准确的翻译。请参阅[优化并重新生成 配音](/docs/zh/eleven-api/guides/how-to/dubbing/refine-and-regenerate)。

## 后续步骤

#### [使用自己的转录文本](/docs/zh/eleven-api/guides/how-to/dubbing/bring-your-own-transcript)

根据现有转录文本创建项目，并提供自己的翻译

#### [优化并重新生成配音](/docs/zh/eleven-api/guides/how-to/dubbing/refine-and-regenerate)

编辑源转录文本和翻译，然后重新生成配音

#### [配音为多种语言](/docs/zh/eleven-api/guides/how-to/dubbing/multiple-languages)

为单个项目添加多种目标语言

#### [API 参考文档](/docs/zh/api-reference/dubbing/create-project)

查看所有配音 API 参数和响应格式