AI Skills
speech-to-text

speech-to-text

热门

使用 ElevenLabs Scribe v2 将音频转录为文本。适用于将音频/视频转换为文本、生成字幕、转录会议或处理语音内容。

384Star
50Fork
更新于 2026/7/15
获取 Skill源代码

相关 Skills

spring-boot-engineer1.1万turnstile-spin2146anysearch3729
SKILL.md
readonly只读
name
speech-to-text
description

使用 ElevenLabs Scribe v2 将音频转录为文本。适用于将音频/视频转换为文本、生成字幕、转录会议或处理语音内容。

ElevenLabs 语音转文本

使用 Scribe v2 将音频转录为文本——支持 90 多种语言、说话人分离和词级时间戳。

设置： 请参阅安装指南。对于 JavaScript，仅使用 @elevenlabs/* 包。

快速开始

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

with open("audio.mp3", "rb") as audio_file:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v2")

print(result.text)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream } from "fs";

const client = new ElevenLabsClient();
const result = await client.speechToText.convert({
  file: createReadStream("audio.mp3"),
  modelId: "scribe_v2",
});
console.log(result.text);

cURL

curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -F "file=@audio.mp3" -F "model_id=scribe_v2"

模型

模型 ID 描述 最佳用途
scribe_v2 最先进的准确度，支持 90+ 种语言 批量转录、字幕、长音频
scribe_v2_realtime 低延迟（约 150ms） 实时转录、语音代理

带时间戳的转录

词级时间戳包含类型分类和说话人识别：

result = client.speech_to_text.convert(
    file=audio_file, model_id="scribe_v2", timestamps_granularity="word"
)

for word in result.words:
    print(f"{word.text}: {word.start}s - {word.end}s (type: {word.type})")

说话人分离

识别谁说了什么——模型为每个词标记说话人 ID，适用于会议、采访或多说话人音频：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    diarize=True
)

for word in result.words:
    print(f"[{word.speaker_id}] {word.text}")

对于通话录音，批量 API 可以通过设置 detect_speaker_roles=true 和 diarize=true 将分离的说话人标记为 agent 和 customer。此选项与 use_multi_channel=true 不兼容。

如果您的工作区已注册说话人档案，请设置 use_speaker_library=true 和 diarize=true，以将检测到的说话人与说话人库匹配。

curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@call.mp3" \
  -F "model_id=scribe_v2" \
  -F "diarize=true" \
  -F "detect_speaker_roles=true" \
  -F "use_speaker_library=true"

多声道音频

当每个说话人隔离在单独的音频声道时，使用 use_multi_channel=true。默认情况下，API 在 transcripts 下返回每个声道一个转录；设置 multichannel_output_style="combined" 以接收按时间戳合并的一个转录，每个词带有 channel_index。

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    use_multi_channel=True,
    multichannel_output_style="combined",
)

关键词提示

帮助模型识别可能误听的特定词汇——产品名称、技术术语或特殊拼写（最多 100 个词）：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    keyterms=["ElevenLabs", "Scribe", "API"]
)

语言检测

自动检测，可选语言提示：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    language_code="eng"  # ISO 639-1 或 ISO 639-3 代码
)

print(f"检测到: {result.language_code} ({result.language_probability:.0%})")

支持的格式

音频： MP3, WAV, M4A, FLAC, OGG, WebM, AAC, AIFF, Opus
视频： MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP

限制： 文件大小最大 5.0GB，时长最长 10 小时

响应格式

{
  "text": "完整的转录文本",
  "language_code": "eng",
  "language_probability": 0.98,
  "words": [
    {"text": "The", "start": 0.0, "end": 0.15, "type": "word", "speaker_id": "speaker_0"},
    {"text": " ", "start": 0.15, "end": 0.16, "type": "spacing", "speaker_id": "speaker_0"}
  ]
}

词类型：

  • word - 实际说出的词
  • spacing - 词之间的空白（用于精确计时）
  • audio_event - 模型检测到的非语音声音（笑声、掌声、音乐等）

错误处理

try:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v2")
except Exception as e:
    print(f"转录失败: {e}")

常见错误：

  • 401：无效的 API 密钥
  • 422：无效参数
  • 429：超出速率限制

跟踪成本

通过 request-id 响应头监控使用情况：

response = client.speech_to_text.convert.with_raw_response(file=audio_file, model_id="scribe_v2")
result = response.parse()
print(f"请求 ID: {response.headers.get('request-id')}")

实时流式传输

对于超低延迟（约 150ms）的实时转录，请使用实时 API。实时 API 生成两种类型的转录：

  • 部分转录：在处理音频时频繁更新的中间结果——用于实时反馈（例如，在用户说话时显示文本）
  • 已提交转录：在您“提交”后的最终稳定结果——用作应用程序的真相来源

“提交”告诉模型最终确定当前片段。您可以手动提交（例如，当用户暂停时）或使用语音活动检测 (VAD) 在静音时自动提交。

Python（服务器端）

import asyncio
from elevenlabs import ElevenLabs

client = ElevenLabs()

async def transcribe_realtime():
    async with client.speech_to_text.realtime.connect(
        model_id="scribe_v2_realtime",
        include_timestamps=True,
        keyterms=["ElevenLabs", "Scribe"],
        no_verbatim=True,
    ) as connection:
        await connection.stream_url("https://example.com/audio.mp3")

        async for event in connection:
            if event.type == "partial_transcript":
                print(f"部分: {event.text}")
            elif event.type == "committed_transcript":
                print(f"最终: {event.text}")

asyncio.run(transcribe_realtime())

JavaScript（客户端，使用 React）

import { useScribe, CommitStrategy } from "@elevenlabs/react";

function TranscriptionComponent() {
  const [transcript, setTranscript] = useState("");

  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    commitStrategy: CommitStrategy.VAD, // 麦克风输入时静音自动提交
    keyterms: ["ElevenLabs", "Scribe"],
    noVerbatim: true,
    includeLanguageDetection: true,
    onPartialTranscript: (data) => console.log("部分:", data.text),
    onCommittedTranscript: (data) => setTranscript((prev) => prev + data.text),
  });

  const start = async () => {
    // 从后端获取令牌（切勿向客户端暴露 API 密钥）
    const { token } = await fetch("/scribe-token").then((r) => r.json());

    await scribe.connect({
      token,
      microphone: { echoCancellation: true, noiseSuppression: true },
    });
  };

  return <button onClick={start}>开始录音</button>;
}

提交策略

策略 描述
手动 您调用 commit() 时提交——适用于文件处理或当您控制音频片段时
VAD 语音活动检测在检测到静音时自动提交——适用于实时麦克风输入

设置 includeLanguageDetection: true 以在包含时间戳的已提交转录事件中接收检测到的语言代码。

// React：在 hook 上设置 commitStrategy（推荐用于麦克风输入）
import { useScribe, CommitStrategy } from "@elevenlabs/react";

const scribe = useScribe({
  modelId: "scribe_v2_realtime",
  commitStrategy: CommitStrategy.VAD,
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  // 可选的 VAD 调优：
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
});

// JavaScript 客户端：在连接时传递 vad 配置
const connection = await client.speechToText.realtime.connect({
  modelId: "scribe_v2_realtime",
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  vad: {
    silenceThresholdSecs: 1.5,
    threshold: 0.4,
  },
});

事件类型

事件 描述
partial_transcript 实时中间结果
committed_transcript 提交后的最终结果
committed_transcript_with_timestamps 带词时间戳的最终结果
error 发生错误

有关完整文档，请参阅实时参考。

参考