使用自己的转录文本

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

转录文件格式

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

{
  "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."
    }
  ]
}

片段规则

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

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

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

根据转录文本创建项目

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

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)

项目在配音前仍需导入源媒体，因此请按照快速入门所示轮询，直到状态变为 ready。系统会按原样使用你的片段，不会执行自动转录。

提供自己的翻译

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

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.",
    },
)

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

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

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

创建项目时初始化翻译

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

{
  "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."
    }
  ]
}

质量注意事项

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

后续步骤