转录编辑 | 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 的完整事件和错误类型列表。