转录编辑

概述

转录编辑可让你在转录请求中附加一条自然语言指令。音频转录完成后，系统会将指令应用于转录文本，并同时返回编辑后的文本和原始文本。

这可替代你在工作流中单独进行的后处理步骤。常见用途包括统一日期、时间或单位的写法，展开缩写，移除不需要的内容，应用不同的风格或语气，以及重新格式化转录文本。

例如，转录一段语音留言时使用指令 将所有日期写为 ISO 8601 格式（YYYY-MM-DD），会返回两个版本的文本：

{
  "language_code": "eng",
  "language_probability": 0.9912,
  "text": "Hi, this is Jill. Your appointment is confirmed for the twelfth of July twenty twenty-six, and the follow-up is on the third of August.",
  "words": [
    { "text": "Hi,", "start": 0.12, "end": 0.38, "type": "word", "logprob": 0.0 },
    { "text": " ", "start": 0.38, "end": 0.41, "type": "spacing", "logprob": 0.0 },
    { "text": "this", "start": 0.41, "end": 0.55, "type": "word", "logprob": 0.0 },
    ...
  ],
  "transcription_id": "Y2ZX8AxHUzTPCIualYiE",
  "edited_transcript": {
    "kind": "transcript",
    "text": "Hi, this is Jill. Your appointment is confirmed for 2026-07-12, and the follow-up is on 2026-08-03."
  }
}

text 和 words 字段始终描述原始转录文本。编辑后的版本会单独在 edited_transcript 中返回。

集成转录编辑

转录编辑通过向 convert 方法传入 transcript_edit 参数集成到语音转文本 API 中。指令最长可包含 2000 个字符。

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("voicemail.mp3", "rb") as audio_file:
    transcription = elevenlabs.speech_to_text.convert(
        file=audio_file,
        model_id="scribe_v2",
        # Natural-language instruction applied to the finished transcript.
        transcript_edit="Write all dates in ISO 8601 format (YYYY-MM-DD)",
    )
print("Original:", transcription.text)
print("Edited:", transcription.edited_transcript)

转录编辑同时支持同步请求和 webhook 请求。对于 webhook 请求，edited_transcript 会包含在 webhook 负载的 transcription 对象中。

Scribe v2 Realtime 支持对每条已确认的转录文本应用相同指令。请参阅 实时转录编辑指南。

编写指令

指令会应用于整段转录文本中所有相关位置，所有匹配项都会被编辑，而不只是第一个。指令可以修改特定词语或短语，同时保留其余内容不变；也可以重写或标注完整文本。一条指令可以组合多项编辑。

以下示例说明了支持指令的范围：

编写指令时请注意以下几点：

• 明确说明所需输出。将所有日期写为 ISO 8601 格式（YYYY-MM-DD） 比 修正日期 更可靠。
• 指令可使用任何语言编写，但英文指令效果最佳。编辑后的转录文本会保留原始语言。
• 系统只会执行指令。音频中说出的内容会被视为数据，无法改变指令的应用方式。
• 如果转录文本中没有任何内容受指令影响，编辑后的转录文本将与原始文本完全相同。

响应格式

设置 transcript_edit 后，响应会包含一个 edited_transcript 对象。其 kind 字段表示编辑是否成功：

未请求 transcript_edit 时，该字段不会出现。

{
  "text": "Hi, this is Jill. Your appointment is confirmed for ...",
  "edited_transcript": {
    "kind": "error",
    "error_type": "edit_failed",
    "message": "The transcript could not be edited. Please try again."
  }
}

请注意以下行为：

• 编辑后的转录文本为纯文本。词级时间戳、说话人标签和 additional_formats 仍描述原始转录文本。
• 编辑会在转录完成后执行，因此会增加延迟，且延迟会随转录文本长度增长。
• 附加费用按请求的音频时长计算，每次请求至少按 10 秒计费。

后续步骤