转录编辑 | ElevenLabs Documentation

操作指南 · 假设你已完成客户端或服务端流式传输指南。

概览

转录编辑是一项实验性功能，会在基础转录费用上增加 30% 的附加费，且每条已提交的转录文本至少按 10 秒音频计费。详细价格信息请参阅 API 定价页面。

实时转录可对每条已提交的转录文本应用自然语言编辑指令，例如将口述日期写为固定格式，或展开缩写和首字母缩略词。连接建立时传入一次指令，每条已提交的转录文本之后都会有单独的 edited_transcript 事件，其中包含编辑后的文本。

部分转录文本绝不会被编辑。committed_transcript 事件也不会改变，因此启用此功能后，现有集成仍可正常运行。

转录编辑不能与 entity_detection 结合使用。两者同时设置的连接会因 invalid_request 错误而被拒绝。

启用转录编辑

连接时通过 transcriptEdit 选项传递指令（WebSocket API 中的 transcript_edit 查询参数）。指令最长可为 2000 个字符。有关如何编写指令，请参阅批处理转录编辑指南。

在所有 SDK 中，编辑后的转录文本都会通过 RealtimeEvents.EDITED_TRANSCRIPT 事件传入。

客户端

按照客户端流式传输指南所述，在浏览器中使用 @elevenlabs/client 和由服务器签发的一次性令牌。

import { Scribe, RealtimeEvents } from "@elevenlabs/client";
// Fetch a single-use token from your server first
const response = await fetch("/scribe-token", yourAuthHeaders);
const { token } = await response.json();
const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  transcriptEdit: "Write all dates in ISO 8601 format (YYYY-MM-DD)",
  microphone: {
    echoCancellation: true,
    noiseSuppression: true,
  },
});
connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
  console.log("Committed:", data.text);
});
connection.on(RealtimeEvents.EDITED_TRANSCRIPT, (data) => {
  console.log("Edited:", data.edited_text);
});

服务端

按照服务端流式传输指南所述，在服务器上使用官方 SDK。与该指南相比，只有选项和事件处理程序不同；发送音频和关闭连接的方式相同。

import asyncio
import os
from dotenv import load_dotenv
from elevenlabs import AudioFormat, ElevenLabs, RealtimeAudioOptions, RealtimeEvents
load_dotenv()
async def main():
    elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
    connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeAudioOptions(
        model_id="scribe_v2_realtime",
        audio_format=AudioFormat.PCM_16000,
        sample_rate=16000,
        transcript_edit="Write all dates in ISO 8601 format (YYYY-MM-DD)",
    ))
    def on_committed_transcript(data):
        print(f"Committed: {data.get('text', '')}")
    def on_edited_transcript(data):
        print(f"Edited: {data.get('edited_text', '')}")
    connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, on_committed_transcript)
    connection.on(RealtimeEvents.EDITED_TRANSCRIPT, on_edited_transcript)
    # Send audio chunks as shown in the server-side streaming guide, then close.
    await connection.close()
if __name__ == "__main__":
    asyncio.run(main())

接收编辑后的转录文本

启用后，每条已提交的转录文本后都会跟随一个 edited_transcript 事件，其中包含已提交文本及其编辑版本：

{
  "message_type": "edited_transcript",
  "text": "our next meeting is on the twelfth of July twenty twenty-six",
  "edited_text": "our next meeting is on 2026-07-12"
}

需注意以下行为：

编辑会按已提交片段分别应用。由于编辑是异步进行的，edited_transcript 事件会在对应的 committed_transcript 事件后不久触发。它可能在下一条部分转录文本之后才到达，连续片段的编辑也可能乱序到达。请使用 text 字段将编辑内容与其已提交的转录文本匹配。
如果某个片段未做任何编辑，edited_text 与 text 完全相同。
如果无法为某个片段生成编辑结果，则不会为其发送 edited_transcript 事件。committed_transcript 事件不受影响。
committed_transcript_with_timestamps 中的词级时间戳描述的是原始已提交文本，而非编辑后的文本。

后续步骤

批处理转录编辑

指令编写指南和批处理响应格式。

事件参考文档

实时 STT API 的完整事件和错误类型列表。