转录文本编辑 | ElevenLabs Documentation

操作指南 · 假设你已完成文本转语音快速入门。

概述

转录文本编辑是一项实验性功能，除基础转录费用外，还会额外收取 30% 的费用。每次请求至少按 10 秒音频计费。详细定价信息请参阅 API 定价页面。

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

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

例如，转录语音邮件时使用指令 Write all dates in ISO 8601 format (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_v3",
        # 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 v3 Live 和 Scribe v2 Realtime 支持在每个已提交的转录文本上使用相同指令。请参阅实时转录文本编辑指南。

编写指令

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

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

指令	效果
`Write all dates in ISO 8601 format (YYYY-MM-DD)`	`the twelfth of July twenty twenty-six` 变为 `2026-07-12`
`Write times in 24-hour format`	`half past two in the afternoon` 变为 `14:30`
`Expand abbreviations such as "ETA" and "ASAP" on first use`	`ETA` 变为 `estimated time of arrival (ETA)`
`Add the sentiment of every sentence in brackets at the end. Choose from [positive, negative, neutral]`	`Thanks, that was really helpful.` 变为 `Thanks, that was really helpful. [positive]`
`Redact every curse word with its first letter followed by stars, e.g. s***`	`That was a damn good call.` 变为 `That was a d*** good call.`
`Format the transcript as a bulleted list, one sentence per bullet`	重新格式化整个转录文本

有些调整提供了专用参数，比编辑指令更便宜且更可预测。使用关键术语提示让识别更倾向于特定名称和术语，使用 no_verbatim 删除填充词和不流畅表达，并使用 numbers_format （Scribe v3）在数字和文字之间选择。仅将转录文本编辑用于这些选项无法覆盖的更改。

编写指令时请注意：

明确说明所需输出。Write all dates in ISO 8601 format (YYYY-MM-DD) 比 fix the dates 更可靠。
指令可以用任何语言编写，但英文指令效果最佳。编辑后的转录文本会保留原始语言。
系统只会执行指令。音频中说出的内容会被视为数据，不能改变指令的应用方式。
如果指令未影响转录文本中的任何内容，编辑后的转录文本将与原文完全相同。

响应格式

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

`kind`	字段	说明
`transcript`	`text`	编辑后的转录文本。未进行编辑时，与原始 `text` 相同。
`error`	`error_type`（`edit_failed`）、`message`	无法生成编辑结果。转录本身仍然成功，且仍会返回原始 `text`。

未请求 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 秒计费。

转录文本编辑无法与 entity_detection、entity_redaction 或 use_multi_channel 组合使用。组合使用这些参数的请求会因参数无效而被拒绝。

后续步骤

API 参考文档

完整的文本转语音 API 参考文档和参数说明。

Webhooks

通过 webhook 异步接收转录文本，包括编辑后的转录文本。