转录文本编辑 | ElevenLabs Documentation

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

概述

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

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

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

转录文本编辑不能与 entity_detection 或 entity_redaction 结合使用。同时设置两者的连接会因 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_v3_live",
  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_v3_live",
        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 的完整事件和错误类型列表。