关键词提示 | ElevenLabs Documentation

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

概述

Scribe v3、Scribe v3 Live、Scribe v2、Scribe v2 Medical（批处理）和 Scribe v2 Realtime 支持关键词提示，但需额外付费。详细定价信息请参阅 API 定价页面。

关键词提示功能可让你突出显示词语或短语，使模型更倾向于转录它们。这适合转录音频中不常见的特定词语或句子，例如产品名称、人名或其他特定术语。与其他模型提供的偏置关键词或自定义词表相比，关键词功能更强大，因为它会根据上下文决定是否转录该术语。

	批处理（Scribe v3 / Scribe v2 / Scribe v2 Medical）	实时（Scribe v3 Live / Scribe v2 Realtime）
最大关键词数量	1000	50
每个关键词最大字符数	50	20

在批处理转录中，每个关键词最多还可包含 5 个单词。

对于更大的实时词汇表，Scribe v3 Live 还支持包含最多 10,000 个术语的关键词库。

例如，如果公司名称不是常见短语，或拼写、发音独特，你可以使用关键词来确保模型正确转录。请听以下音频：

不使用关键词提示时，模型可能会将上述内容转录为：

I work at eleven labs.

其中公司名称的样式不正确。使用关键词提示后，可确保模型以正确的拼写和样式转录上述内容：

I work at ElevenLabs.

上下文

模型可利用上下文判断是否应转录某个术语。提供关键词 “ElevenLabs” 后，上述音频会按预期转录；同时，模型仍可根据上下文正确转录以下内容：

其转录输出如下：

I've worked at many labs. In fact I've worked at eleven labs.

批处理转录

通过向 convert 方法传递 keyterms 参数，即可将关键词提示集成到批处理语音转文本 API 中。

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)
transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v3", # Model to use
    # Keyterms to prompt the model with.
    # Up to 1000 keyterms can be provided, with a maximum length of 50 characters each
    keyterms=["ElevenLabs"],
)
print(transcription)

实时流式传输

实时语音转文本 WebSocket API 也支持关键词提示。连接时传递 keyterms 参数。

connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v3_live",
    keyterms=["ElevenLabs"],
))

直接使用 WebSocket API 时，请将关键词作为查询参数传递：

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v3_live&keyterms=ElevenLabs&keyterms=AnotherTerm

关键词库

仅 Scribe v3 Live（scribe_v3_live）支持关键词库。

关键词提示最适合少数你确定会出现在音频中的术语。关键词库是面向整个领域的大型词汇库，例如医学词典、法律术语或产品目录。模型仅在听到可能匹配的内容时查询词库。

在会话的第一条 input_audio_chunk 消息中，以 keyterm_library 发送词库：

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "<base64-encoded audio>",
  "commit": false,
  "sample_rate": 16000,
  "keyterm_library": ["Acetaminophen", "Metoprolol", "Atorvastatin"]
}

关键词库有以下限制：

最多 10,000 个术语。
每个术语最多 50 个字符。
文本总大小最多 2 MB。
术语不能为空。

同一会话中可以将关键词库与 keyterms 查询参数结合使用。使用其中任一功能的会话仅收取一次关键词提示费用。

keyterm_library 仅可在会话的第一条 input_audio_chunk 中使用。在后续数据块中发送，或发送超出限制的词库，都会返回 input_error 并关闭连接。

官方 SDK 尚不支持 keyterm_library。如需使用，请直接连接 WebSocket API。

后续步骤

API 参考文档

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

实体检测

自动检测并标注转录中的人名、日期和地点等实体。