Elevenlabs Speech to Text API 文档

版本: v1.0.0 | 更新日期: 2026-07-15 | 模型: scribe_v2, scribe_v2_realtime | 状态: GA
本文档基于正式环境（https://cloud.ve2s.ai）线上实测请求/响应编写，所有字段名、类型、取值均与实际 API 返回严格一致。

1. 概述

Speech to Text API 提供基于 Scribe v2 系列模型的高精度语音识别能力，覆盖两类典型场景：

场景	模型	协议	适用于
录音文件转写	`scribe_v2`	HTTP (`multipart/form-data`)	已有完整音频文件的离线批量转写：会议录音、播客、客服质检等
实时流式转写	`scribe_v2_realtime`	WebSocket	边说边出字的低延迟场景：实时字幕、语音输入、会议纪要等

核心能力：

能力	说明
多语言识别	支持 90+ 种语言，自动检测语言并返回置信度
词级时间戳	每个词返回精确到毫秒级的 `start` / `end` 时间；实时模型额外返回字符级时间戳
说话人分离 (Diarization)	多人对话音频自动标注 `speaker_id`
置信度评分	每个词返回 `logprob`（对数概率），可用于质量过滤
实时增量输出	WebSocket 会话中持续推送 `partial_transcript`（临时结果）与 `committed_transcript`（确认结果）

2. 认证

所有请求须携带 API Key：

Authorization: Bearer YOUR_API_KEY

协议	携带方式
HTTP	请求头 `Authorization: Bearer <API_KEY>`
WebSocket	握手请求头 `Authorization: Bearer <API_KEY>`

安全提示：API Key 为敏感凭证，请勿在客户端代码、公开仓库或日志中暴露。建议通过环境变量或密钥管理服务注入。

3. 可用模型与定价

Model ID	说明	协议	计费方式	状态
`scribe_v2`	录音文件转写模型。高精度、支持说话人分离与词级时间戳。	HTTP	按音频时长	GA
`scribe_v2_realtime`	实时流式转写模型。低延迟增量输出，词级 + 字符级时间戳。	WebSocket	按音频时长	GA

两个模型均按音频时长计费（按量计费），与请求次数无关，计量规则见 7. 计费说明。具体单价以控制台模型价格页实时显示为准。

4. 录音文件转写（HTTP）

4.1 接口地址

POST https://cloud.ve2s.ai/v1/elevenlabs/speech-to-text

请求格式为 multipart/form-data。

4.2 请求参数

参数	类型	必填	说明
`model_id`	`string`	是	模型标识符，当前可用值：`scribe_v2`。缺失时返回 `400`。
`file`	`file`	二选一	音频文件（二进制上传）。与 `source_url` 至少传一个。支持 wav / mp3 / m4a / flac / ogg / webm 等常见格式。
`source_url`	`string`	二选一	音频文件的公网 URL。须为转写服务器可直接访问的公网地址（内网地址、国内部分 CDN 可能不可达），推荐优先使用 `file` 上传。
`language_code`	`string`	否	音频语言（ISO 639-1/639-3，如 `en`、`zh`）。不传则自动检测。显式指定可跳过语言检测、提高准确率（实测指定后 `language_probability` 为 `1.0`）。
`diarize`	`boolean`	否	是否开启说话人分离，默认 `false`。开启后 `words[]` 中每项携带 `speaker_id`（如 `speaker_0`、`speaker_1`）。
`num_speakers`	`integer`	否	说话人数量上限提示，配合 `diarize=true` 使用，有助于提升分离准确率。
`timestamps_granularity`	`string`	否	时间戳粒度：`word`（默认）/ `character` / `none`。
`tag_audio_events`	`boolean`	否	是否标注非语音音频事件（如笑声、掌声），默认 `true`。

其余 ElevenLabs Speech-to-Text 官方参数（如 additional_formats、file_format 等）原样透传至模型服务，行为与官方定义一致。

4.3 响应体 (Response Body)

成功时返回 HTTP 200。顶层字段：

字段	类型	说明
`language_code`	`string`	检测/指定的语言代码（ISO 639-3），如 `"eng"`。
`language_probability`	`float`	语言检测置信度，范围 0~1。显式传入 `language_code` 时为 `1.0`。
`text`	`string`	完整转写文本。
`words`	`array<object>`	逐词明细，含时间戳与置信度，见 4.4 words 数组详解。
`transcription_id`	`string`	本次转写的唯一标识符，可用于问题排查与日志追踪。
`audio_duration_secs`	`float`	音频文件的实际总时长（秒）。计费时长以转写结果最后一个词的 `end` 时间为准，见 7. 计费说明。

响应示例

以下为响应（9.06 秒英文测试音频，words 已截断）：

{
  "language_code": "eng",
  "language_probability": 0.8746970891952515,
  "text": "Hello VE2S, this is a speech-to-text API test. The quick brown fox jumps over the lazy dog",
  "words": [
    {
      "text": "Hello",
      "start": 0.219,
      "end": 0.5,
      "type": "word",
      "logprob": -0.0000160931
    },
    {
      "text": " ",
      "start": 0.5,
      "end": 0.599,
      "type": "spacing",
      "logprob": -0.0573769733
    },
    {
      "text": "VE2S,",
      "start": 0.599,
      "end": 1.179,
      "type": "word",
      "logprob": -0.2447926141
    }
  ],
  "transcription_id": "wnnnNJ3sHGJrl8gXgXyS",
  "audio_duration_secs": 9.06
}

4.4 words 数组详解

字段	类型	说明
`text`	`string`	词文本（含标点）。`type=spacing` 时为空格。
`start`	`float`	起始时间（秒）。
`end`	`float`	结束时间（秒）。
`type`	`string`	元素类型：`word`（词）/ `spacing`（词间空白）/ `audio_event`（音频事件，需 `tag_audio_events=true`）。
`logprob`	`float`	该词的对数概率（≤ 0，越接近 0 置信度越高）。
`speaker_id`	`string`	说话人标识（如 `"speaker_0"`）。仅在 `diarize=true` 时返回。

解析建议：拼接纯文本时直接使用顶层 text 字段；处理 words 时按 type 过滤，不要假设 word 与 spacing 交替出现。

5. 实时转写（WebSocket）

5.1 连接地址

wss://cloud.ve2s.ai/v1/elevenlabs/realtime

握手成功返回 101 Switching Protocols；鉴权失败在握手阶段直接返回 HTTP 401，不建立连接。

5.2 Query 参数

参数	类型	必填	说明
`model_id`	`string`	否	模型标识符，默认 `scribe_v2_realtime`（当前唯一可用值，建议显式传入）。
`audio_format`	`string`	否	音频编码格式，默认 `pcm_16000`。格式为 `pcm_<采样率>`，须与实际发送的音频一致，见 5.5 音频格式要求。
`language_code`	`string`	否	音频语言。不传则自动检测。
`commit_strategy`	`string`	否	提交策略。设为 `vad` 时由服务端语音活动检测（VAD）自动切分并提交转写段落；默认由客户端通过 `commit` 字段手动提交。
其他	—	否	其余 ElevenLabs Realtime 官方 query 参数原样透传。

注意：include_timestamps 由平台强制设为 true，以保证会话结束后能按词级时间戳精确计费。

5.3 客户端消息

连接建立后，客户端以 JSON 文本帧发送音频分片：

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "<Base64 编码的 PCM 音频数据>",
  "sample_rate": 16000,
  "commit": true
}

字段	类型	必填	说明
`message_type`	`string`	是	固定值 `"input_audio_chunk"`。
`audio_base_64`	`string`	是	Base64 编码的原始 PCM 音频数据（16-bit、单声道、小端序，无文件头）。
`sample_rate`	`integer`	否	采样率，须与 `audio_format` 一致，如 `16000`。
`commit`	`boolean`	否	设为 `true` 时触发服务端提交（commit）当前累积音频，生成确认转写结果。流式持续发送时可分片发送、最后一片置 `true`。

5.4 服务端消息

服务端按以下顺序推送 JSON 文本帧：

session_started → partial_transcript (0~N 次) → committed_transcript → committed_transcript_with_timestamps

session_started — 会话建立

{
  "message_type": "session_started",
  "session_id": "b4c1d85547624f98adecc5a4df82511a",
  "config": {
    "sample_rate": 16000,
    "audio_format": "pcm_16000",
    "language_code": null,
    "timestamps_granularity": "word",
    "vad_commit_strategy": false,
    "vad_silence_threshold_secs": 1.5,
    "vad_threshold": 0.4,
    "min_speech_duration_ms": 100,
    "min_silence_duration_ms": 100,
    "max_tokens_to_recompute": 5,
    "model_id": "scribe_v2_realtime",
    "include_timestamps": true,
    "include_language_detection": false,
    "filter_background_audio": false,
    "keyterms": [],
    "no_verbatim": false,
    "entity_detection": null
  }
}

字段	说明
`session_id`	会话唯一标识符，用于问题排查与对账。
`config`	服务端最终生效的会话配置（合并 query 参数与默认值后的结果），建议客户端校验后再发送音频。

partial_transcript — 临时转写（增量，可选）

低延迟的中间识别结果，内容可能随后续音频被修正，适合做实时字幕预览：

{ "message_type": "partial_transcript", "text": "Hello, VE2S. This is" }

committed_transcript — 确认转写

commit 触发后返回的最终确认文本（不再变更）：

{
  "message_type": "committed_transcript",
  "text": "Hello, VE2S. This is a speech-to-text API test. The quick brown fox jumps over the lazy dog."
}

committed_transcript_with_timestamps — 确认转写（含时间戳）

紧随 committed_transcript 之后，附带完整词级 + 字符级时间戳：

{
  "message_type": "committed_transcript_with_timestamps",
  "text": "Hello, VE2S. This is a speech-to-text API test. The quick brown fox jumps over the lazy dog.",
  "language_code": null,
  "words": [
    {
      "text": "Hello,",
      "start": 0.219,
      "end": 0.479,
      "type": "word",
      "speaker_id": null,
      "logprob": -0.5185597737,
      "characters": [
        { "text": "H", "start": 0.219, "end": 0.239 },
        { "text": "e", "start": 0.239, "end": 0.319 },
        { "text": "l", "start": 0.319, "end": 0.34 },
        { "text": "l", "start": 0.34, "end": 0.36 },
        { "text": "o", "start": 0.36, "end": 0.479 },
        { "text": ",", "start": 0.479, "end": 0.479 }
      ],
      "channel_index": null
    }
  ]
}

words[] 结构与 HTTP 接口一致（见 4.4），并额外包含：

字段	类型	说明
`characters`	`array<object>`	字符级时间戳，每项含 `text` / `start` / `end`。
`channel_index`	`integer \| null`	声道索引，单声道音频为 `null`。

错误事件

上游服务异常时以消息形式透传给客户端（此类会话不产生费用）：

message_type	含义
`scribeAuthError`	服务鉴权异常
`scribeQuotaExceededError`	服务额度超限
`scribeThrottledError`	服务限流
`scribeSessionTimeLimitExceededError`	会话超出最大时长限制

5.5 音频格式要求

项	要求
编码	原始 PCM（16-bit signed，little-endian），不带 WAV/RIFF 文件头
声道	单声道 (mono)
采样率	与 `audio_format` 参数一致，推荐 `pcm_16000`（16 kHz）

从 WAV 文件提取 PCM（ffmpeg）：

6. 完整示例

6.1 cURL — 录音文件转写

6.2 Python — 录音文件转写

6.3 Python — 实时转写 (WebSocket)

依赖：pip install websockets

6.4 Node.js — 实时转写 (WebSocket)

依赖：npm install ws

7. 计费说明

两个模型均按 实际音频时长 计费，与请求次数、输出文本长度无关。具体单价以控制台模型价格页为准。

计量规则：

计费时长以 转写结果覆盖的音频时长 为准，即最后一个词的 end 时间，按 秒向上取整（音频末尾的静音不计费）。

时长折算为 audio tokens 计量：每 1 分钟音频折合 1,000 audio tokens（不足按比例向上取整），在用量日志中体现为 prompt_tokens。

示例：9.06 秒音频，最后一个词 end = 8.319s → 取整 9 秒 → 9 / 60 × 1000 = 150 audio tokens。

实时会话在 连接关闭后统一结算；未产生任何确认转写的会话（如建连后立即断开）计 0 费用。

HTTP 请求参数校验失败（400）、鉴权失败（401）均不计费；WebSocket 收到上游错误事件的会话不计费。

每笔消费的 audio tokens 用量与费用明细可在控制台日志中查看。

8. 错误码

HTTP 状态码	场景	错误信息示例	处理建议
`400`	缺少 `model_id` 等必填参数	`model_id is required`	对照 4.2 请求参数补齐必填字段。
`401`	API Key 缺失、格式错误或已失效（HTTP 与 WebSocket 握手均适用）	`无效的令牌`	确认 Header 格式为 `Authorization: Bearer <key>`，检查 Key 是否有效。
`403`	当前 Key 无权访问指定模型	—	确认账户Key有相关模型权限。
`429`	请求频率超限或配额不足	—	降低请求频率，使用指数退避重试；必要时升级订阅计划。
`500`	请求无效（如 `file` 与 `source_url` 均未提供）或服务端内部错误	`either file or source_url is required`	先检查请求完整性；若为偶发服务端错误，携带错误信息中的 `request id` 联系技术支持。
`503`	服务暂时不可用或过载	—	使用指数退避重试。

所有错误响应均为统一 JSON 结构：{"error": {"code": "...", "message": "... (request id: ...)", "type": "..."}}。message 中的 request id 可用于问题排查，请在反馈问题时一并提供。

9. 最佳实践

9.1 模型选型

已有完整音频文件 → 用 scribe_v2（HTTP）：单次请求完成，精度优先。

需要边说边出字 → 用 scribe_v2_realtime（WebSocket）：先用 partial_transcript 做低延迟预览，以 committed_transcript_with_timestamps 为最终结果。

9.2 HTTP 转写

优先使用 file 二进制上传；source_url 要求转写服务器可直接访问该公网 URL，内网/受限 CDN 地址会导致拉取失败。

已知音频语言时显式传 language_code，可跳过语言检测并提高准确率。

长音频转写耗时与时长正相关，客户端超时建议按音频时长预留（≥ 300 秒起步）。

9.3 实时会话

音频务必为 不带文件头的原始 PCM（16-bit / mono），采样率与 audio_format 参数保持一致——格式不匹配会导致转写结果为空或乱码。

生产环境按 100~500ms 分片 持续发送音频，讲话段落结束时置 commit: true（或改用 commit_strategy=vad 由服务端自动切分）。

以 session_started 返回的 config 为准校验会话参数是否按预期生效。

收到 committed_transcript_with_timestamps 后再关闭连接，确保拿到完整时间戳；结算发生在连接关闭后。

记录 session_id（WebSocket）与 transcription_id（HTTP），便于问题排查与用量对账。

9.4 结果处理

拼接纯文本直接用顶层 text；处理 words 时按 type 字段区分 word / spacing / audio_event。

logprob 越接近 0 置信度越高，可对低置信度词（如 logprob < -1.0）做人工复核标记。

说话人分离场景，按 speaker_id 分组聚合 words 即可还原逐人对话。

10. 变更记录

日期	版本	变更内容
2026-07-15	v1.0.0	初始发布。支持 `scribe_v2`（HTTP 录音文件转写）与 `scribe_v2_realtime`（WebSocket 实时转写）。

本文档基于 2026-07-15 正式环境（cloud.ve2s.ai）线上实测编写。实测样本：9.06 秒 16kHz 单声道英文测试音频；HTTP 转写返回 33 个 words 元素，实时会话消息流 session_started → committed_transcript → committed_transcript_with_timestamps 全链路验证通过。

Elevenlabs Speech to Text API 文档

目录#

1. 概述#

2. 认证#

3. 可用模型与定价#

4. 录音文件转写（HTTP）#

4.1 接口地址#

4.2 请求参数#

4.3 响应体 (Response Body)#

响应示例#

4.4 words 数组详解#

5. 实时转写（WebSocket）#

5.1 连接地址#

5.2 Query 参数#

5.3 客户端消息#

5.4 服务端消息#

session_started — 会话建立#

partial_transcript — 临时转写（增量，可选）#

committed_transcript — 确认转写#

committed_transcript_with_timestamps — 确认转写（含时间戳）#

错误事件#

5.5 音频格式要求#

6. 完整示例#

6.1 cURL — 录音文件转写#

6.2 Python — 录音文件转写#

6.3 Python — 实时转写 (WebSocket)#

6.4 Node.js — 实时转写 (WebSocket)#

7. 计费说明#

8. 错误码#

9. 最佳实践#

9.1 模型选型#

9.2 HTTP 转写#

9.3 实时会话#

9.4 结果处理#

10. 变更记录#

目录