> 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.

# 使用自己的转录文本

> **Note**
>
> **操作指南** · 假设你已熟悉如何创建配音项目，如
> [配音快速入门](/docs/zh/eleven-api/guides/cookbooks/dubbing)所示。

> **Warning**
>
> 仅企业版工作区可提供自己的转录文本和翻译。请联系
> [销售团队](https://elevenlabs.io/contact-sales)获取访问权限。

默认情况下，配音 API 会转录源媒体，并将转录文本机器翻译为每种目标语言。如果你已有准确的转录文本（字幕、脚本或专业翻译文本），也可以直接提供。本指南介绍转录文件格式、如何从转录文本创建项目，以及添加语言时如何提供自己的翻译。

## 转录文件格式

转录文本是一个 JSON 文件，顶层仅包含一个 `segments` 数组。每个片段对应一句话：包括所说文本、开始和结束时间，以及可选的说话人信息。

**`transcript.json`**

```json title="transcript.json"
{
  "segments": [
    {
      "external_id": "line_0",
      "speaker_id": "speaker_0",
      "start_s": 0.0,
      "end_s": 14.5,
      "text": "With my soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditation guides, or adding an intimate feel to your narrative projects."
    }
  ]
}
```

| 字段            | 必填 | 说明                                                                |
| ------------- | -- | ----------------------------------------------------------------- |
| `text`        | 是  | 该片段中说出的文本。                                                        |
| `start_s`     | 是  | 片段开始时间，以秒为单位。                                                     |
| `end_s`       | 是  | 片段结束时间，以秒为单位。                                                     |
| `speaker_id`  | 否  | 用于将同一说话人的片段分组的标识符，确保每位说话人使用一致的配音音色。省略该字段的片段将共用一个默认说话人。            |
| `external_id` | 否  | 片段的自定义标识符，最多 128 个字符，且在转录文本中必须唯一。用于关联翻译，并会在每次读取转录文本时原样返回。         |
| `translation` | 否  | 片段的翻译文本，用于初始化通过 `target_language` 创建的语言目标。如果任一片段包含该字段，则所有片段都必须包含。 |

### 片段规则

创建项目时会验证转录文本：

* 片段必须按 `start_s` 排序。
* 片段时长必须介于 0.1 到 25 秒之间，且 `end_s` 必须大于 `start_s`。
* 相同 `speaker_id` 的片段不得重叠，但可以在端点相接。不同说话人的片段可重叠，以表示同时说话。
* 转录文本最多可包含 20,000 个片段，文件最大为 4 MiB。

应优先使用较短片段而非较长片段：在停顿达到 1 秒或更长时拆分句子。片段边界决定配音音频与源媒体的时间对齐方式，因此具有准确、自然停顿的转录文本可生成同步效果更好的配音。

## 根据转录文本创建项目

创建项目时传入转录文件。提供转录文本时必须指定 `source_language`，因为不会自动转录源媒体。语言使用 BCP-47 标签指定，例如 `es` 或 `fr-CA`。有关所有可接受值，请参阅[支持的语言和方言](/docs/zh/overview/capabilities/dubbing#supported-languages)。

```python
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

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

with open("transcript.json", "rb") as transcript:
    project = elevenlabs.dubbing.project.create(
        source_url="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
        source_language="en",
        transcript=transcript,
    )

print(project.project_id)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import { createReadStream } from "fs";

const elevenlabs = new ElevenLabsClient();

const project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
  sourceLanguage: "en",
  transcript: createReadStream("transcript.json"),
});

console.log(project.projectId);
```

项目在配音前仍需导入源媒体，因此请按照[快速入门](/docs/zh/eleven-api/guides/cookbooks/dubbing)所示轮询，直到状态变为 `ready`。系统会按原样使用你的片段，不会执行自动转录。

## 提供自己的翻译

添加语言目标时，传入 `translations` 映射即可使用自己的翻译，而非机器翻译。映射的键为每个源片段的 `external_id`；如果未提供该字段，则使用其内部片段 `id`。映射必须恰好覆盖每个源片段一次。

```python
project_id = "proj_1601kwkyxp0hfzvtmyxwqxx6mcy3"

language = elevenlabs.dubbing.project.language.create(
    project_id,
    target_language="fr",
    translations={
        "line_0": "Avec mon accent américain doux et murmuré, je suis le choix idéal pour créer du contenu ASMR, des guides de méditation, ou pour apporter une touche d'intimité à vos projets narratifs.",
    },
)
```

```typescript
const projectId = "proj_1601kwkyxp0hfzvtmyxwqxx6mcy3";

const language = await elevenlabs.dubbing.project.language.create(projectId, {
  targetLanguage: "fr",
  translations: {
    line_0:
      "Avec mon accent américain doux et murmuré, je suis le choix idéal pour créer du contenu ASMR, des guides de méditation, ou pour apporter une touche d'intimité à vos projets narratifs.",
  },
});
```

每个语言目标需要一次创建调用，因此请为每种要配音的语言重复此请求。`translations` 映射最多可包含 20,000 个条目，文本总量最多为 4 MiB。

如果片段没有 `external_id`，请读取源转录文本以获取每个片段的内部 `id`，并改用这些值作为键：

```python
transcript = elevenlabs.dubbing.project.transcript.get(project_id)
for segment in transcript.segments:
    print(segment.id, segment.text)
```

```typescript
const transcript = await elevenlabs.dubbing.project.transcript.get(projectId);
for (const segment of transcript.segments) {
  console.log(segment.id, segment.text);
}
```

### 创建项目时初始化翻译

对于单一目标语言，可以省去单独的 `translations` 映射：只需在转录文件的每个片段中包含 `translation`，并在创建项目时传入 `target_language`。系统会创建包含你的翻译、状态为排队中的语言目标，并在项目就绪后开始生成。

**`transcript.json`**

```json title="transcript.json"
{
  "segments": [
    {
      "external_id": "line_0",
      "speaker_id": "speaker_0",
      "start_s": 0.0,
      "end_s": 14.5,
      "text": "With my soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditation guides, or adding an intimate feel to your narrative projects.",
      "translation": "Avec mon accent américain doux et murmuré, je suis le choix idéal pour créer du contenu ASMR, des guides de méditation, ou pour apporter une touche d'intimité à vos projets narratifs."
    }
  ]
}
```

## 质量注意事项

配音质量取决于其使用的转录文本和翻译。片段时间和文本会直接用于控制配音的时长与发声，因此不准确的时间或文本会降低输出质量。翻译会被处理为适配相应片段的时长：与原文相比过长或过短的翻译会影响配音语速，因此应尽量使翻译的口语长度与原文相近。

## 后续步骤

#### [优化并重新生成配音](/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 参数和响应格式