请求正文

响应正文

textstring

（string，必需）— 完整的转写文本。对于多 channel 请求，这是合并后的所有 channel 转写（词语按 timestamp 交错）。

languagestring

（string，必需）— 检测到的语言，使用 BCP-47 代码（例如 `en`、`es-mx`）。

durationnumber

（number，必需）— 以秒为单位的音频时长（四舍五入到小数点后两位）。

wordsarray<object>

（array<object>）— 包含 timestamp 的词级片段。为空时省略。

channelsarray<object>

（array<object>）— 各 channel 的转写。仅在 `multichannel=true` 时出现。单 channel 时省略。

No parameters.

{
  "text": "The balance is $167,983.15. That is $23.4 kilograms.",
  "language": "en",
  "duration": 8.4,
  "words": [
    {
      "text": "The",
      "start": 0,
      "end": 0.24,
      "confidence": 0.33
    },
    {
      "text": "balance",
      "start": 0.24,
      "end": 0.64,
      "confidence": 0.67
    },
    {
      "text": "is",
      "start": 0.64,
      "end": 0.88,
      "confidence": 0.41
    },
    {
      "text": "$167,983.15.",
      "start": 0.88,
      "end": 4.8,
      "confidence": 0.07
    },
    {
      "text": "That",
      "start": 6.16,
      "end": 6.48,
      "confidence": 0.29
    },
    {
      "text": "is",
      "start": 6.48,
      "end": 6.64,
      "confidence": 0.4
    },
    {
      "text": "$23.4",
      "start": 6.64,
      "end": 7.52,
      "confidence": 0.07
    },
    {
      "text": "kilograms.",
      "start": 7.76,
      "end": 8.4,
      "confidence": 0.09
    }
  ]
}

语音转文本 - Streaming

WebSocket endpoint：wss://api.x.ai/v1/stt

通过 WebSocket 实时流式进行语音转文本。以二进制帧发送原始音频，在音频处理过程中接收 JSON 转写事件。连接时通过查询参数配置。可使用 grok-voice-transcribe-1.0 或 grok-voice-transcribe-2.0；默认为 grok-voice-transcribe-2.0。

完整 schema 和示例：/stt-streaming.ws.json

Query Parameters

sample_rate（integer，可选，默认：16000）— 音频采样率，单位为 Hz。支持的值：`8000`、`16000`、`22050`、`24000`、`44100`、`48000`。使用 `encoding=opus` 时忽略此项，Opus 数据包与采样率无关。
encoding（string，可选，默认：pcm）— 音频编码格式。`pcm` — 有符号 16 位小端序（2 字节/采样）。`mulaw` — G.711 µ-law（1 字节/采样）。`alaw` — G.711 A-law（1 字节/采样）。`opus` — 原始 Opus 数据包，每个二进制 WebSocket 帧包含一个数据包，仅支持单声道。
interim_results（boolean，可选，默认：false）— 为 `true` 时，server 会在处理音频期间约每 500 ms 发出 partial transcript event（`is_final=false`）。为 `false`（默认）时，仅发送最终结果。
endpointing（integer，可选，默认：400）— 服务器发出 `speech_final=true` 事件前的静音时长（毫秒），该事件表示说话者已停止说话。范围：0–5000。设置为 `0` 时无延迟（任意 VAD 静音边界都会触发）。默认值：400ms。
language（string，可选，默认：）— 语言代码（例如 `en`、`fr`、`de`、`ja`）。设置后会启用 Inverse Text Normalization，将口语形式的数字、货币和单位转换为书面形式。
model（string，可选，默认值：grok-voice-transcribe-2.0）— `grok-voice-transcribe-1.0` 或 `grok-voice-transcribe-2.0`。默认为 `grok-voice-transcribe-2.0`。
multichannel（boolean，可选，默认：false）— 为 `true` 时，为交错的多声道音频启用逐声道转写。需要将 `channels` 设置为 ≥ 2。不支持与 `encoding=opus` 同时使用。
channels（integer，可选，默认：1）— 交错 audio channel 的数量。 `multichannel=true` 时必需。最小值：2，最大值：8。
diarize（boolean，可选，默认：false）— 为 `true` 时启用 speaker diarization。 `transcript.partial` 和 `transcript.done` event 中的词会包含用于标识检测到的说话者的 `speaker` field（integer）。
keyterm（string（可重复），可选）— 用于让转写偏向特定术语的关键词（例如产品名、专有名词）。每个术语重复该 parameter（例如 `keyterm=Understand+The+Universe`）。最多 100 个术语，每个最多 50 个字符。
filler_words（boolean，可选，默认：false）— 为 `true` 时，转写中会包含填充词（例如 `uh`、`um`、`er`）。为 `false`（默认）时，填充词会自动从转写文本和 `words` array 中移除。
smart_turn（number，可选）— 启用 Smart Turn 回合结束检测。设置介于 `0.0` 和 `1.0` 之间的置信度阈值。当模型的回合结束概率在 VAD 静音边界处超过此阈值时，会立即触发 `speech_final`。置信度低于阈值时，`speech_final` 会被抑制，该 event 会降级为 `chunk_final`。启用 Smart Turn 后，每个 `transcript.partial` event 都会包含 `end_of_turn_confidence` field（0.0–1.0）。示例：`smart_turn=0.7`。
smart_turn_timeout（integer，可选）— 即使 Smart Turn model 预测说话者尚未结束，也会在此静音时长（毫秒）后强制触发 `speech_final`。它是防止会话在长时间静音时挂起的安全机制。仅在启用 `smart_turn` 时适用。范围：1–5000。示例：`smart_turn_timeout=3000`。
vad_threshold（number，可选，默认：0.08）— voice-activity gate 的语音概率阈值（0.0–1.0）。得分低于阈值的 chunk 音频会视为非语音并跳过转写。较低的值可转写音量更低或噪声更多的语音（例如窄带电话），但可能会为背景噪声生成伪文本；`0` 会完全禁用该 gate。不影响 endpointing 或 `speech_final` 时序。默认值：`0.08`。

Client Messages

Binary frame (audio) — 将原始音频作为二进制 WebSocket 帧发送，编码由 `encoding` 查询参数指定。音频应按实时节奏分块流式发送（例如每次 100 ms）。不要进行 base64 编码，直接发送原始字节。使用 `encoding=opus` 时，每个二进制帧必须恰好包含一个原始 Opus 数据包，不得拼接多个数据包，也不得将一个数据包拆分到多个帧。无法解码的帧会触发 `error` 事件并关闭会话。
finalize — 立即将当前 utterance 强制结束为 `speech_final`，无需等待 VAD endpointing 或 Smart Turn。session 会保持开启，你可以继续流式发送 audio。type value 接受 `finalize` 或 `Finalize`。当 `multichannel=true` 时，可选的 `channel`（从 0 开始）将 finalize 限制为该 channel；省略 `channel` 会结束所有 channel。
audio.done — 表示已发送所有 audio。server 会清空所有剩余的缓冲 audio，发出最终 transcript event，并发送 `transcript.done` event。 `transcript.done` 后连接关闭。

Server Messages

transcript.created — WebSocket connection 建立且 server 已准备接收 audio 后立即发送。**在发送 audio 前等待此 event** — server 需要初始化其 ASR backend。
transcript.partial — 音频流一部分的 transcript result。两个 boolean field 传达状态：interim（`is_final=false`）表示文本仍可能变化；chunk final（`is_final=true`、`speech_final=false`）表示该 chunk 已锁定；utterance final（`is_final=true`、`speech_final=true`）表示说话者已停止说话。
transcript.done — `audio.done` 后的最终 transcript。始终包含 `duration`。当 `multichannel=true` 时，每个 channel 一个。该 event 后连接关闭。
error — 会话期间发生错误。多数错误（处理管道失败、流超时、无法解码的音频帧）会关闭连接。只有客户端消息解析错误会保持连接开启。

示例消息流

transcript.created（server）
Binary frame (audio)（client）
Binary frame (audio)（client）
transcript.partial（server）
Binary frame (audio)（client）
transcript.partial（server）
Binary frame (audio)（client）
transcript.partial（server）
audio.done（client）
transcript.done（server）

推理 API

Voice

语音转文本 - REST