推理 API

语音

---

POST /v1/stt

将音频文件转录为文本。

请求体

• file (字符串) — 要转录的音频文件。最大大小：500 MB。支持的容器格式（自动检测）：wav、mp3、ogg、opus、flac、aac、mp4、m4a、mkv（仅限 MP3/AAC/FLAC 编解码器）。支持的原始格式（需要 audio_format 和 sample_rate）：pcm、mulaw、alaw。必须是多部分表单中的最后一个字段。

• url (字符串) — 要下载和转录的音频文件 URL（服务器端）。必须提供 file 或 url 中的一个。

• audio_format ("pcm" | "mulaw" | "alaw" | "wav" | "mp3" | "ogg" | "opus" | "flac" | "aac" | "mp4" | "m4a" | "mkv") — 音频格式提示。仅对原始/无头格式必需（pcm、mulaw、alaw）。对于容器格式（MP3、WAV、OGG 等），服务器会从文件头自动检测格式 — 请勿设置此字段。

• sample_rate ("8000" | "16000" | "22050" | "24000" | "44100" | "48000") — 音频采样率，单位为 Hz。当 audio_format 为原始格式时必需（pcm、mulaw、alaw）。对于容器格式将被忽略。可以使用 sample_rate 或 sample_rate_hertz。

• language (字符串) — 音频的语言代码（例如 en、fr、de、ja）。当与 format=true 一起设置时，启用反向文本规范化 — 将口语形式的数字、货币和单位转换为书面形式。

• format ("true" | "false") — 当为 true 时，启用文本格式化。需要设置 language。

• multichannel ("true" | "false") — 当为 true 时，启用每通道转录。每个音频通道独立转录，结果返回在 channels 数组中。

• channels (整数) — 音频通道数。多通道原始音频必需（最小 2，最大 8）。对于容器格式，通道数从文件头自动检测。

• diarize ("true" | "false") — 当为 true 时，启用说话人分离。响应中的每个单词都包含一个 speaker 字段（整数），用于标识检测到的说话人。

• keyterm (数组<字符串>) — 用于引导转录的关键词（例如产品名称、专有名词）。对每个术语重复该字段（例如 keyterm=Understand+The+Universe）。最多 100 个术语，每个最多 50 个字符。

• filler_words ("true" | "false") — 当为 true 时，填充词（例如 "uh"、"um"、"er"）包含在转录文本中。当为 false（默认）时，填充词会自动从转录文本和 words 数组中移除。

• vad_threshold (数字) — 语音活动检测的语音概率阈值（0.0–1.0）。低于阈值的音频段被视为非语音并被跳过不转录。较低的值可以转录较安静或较嘈杂的语音（例如窄带电话），但可能会为背景噪音产生虚假文本；0 完全禁用此门控。默认值：0.5。

响应体

• text (字符串，必需) — 完整的转录文本。对于多通道请求，这是所有通道的合并转录（按时间戳交错单词）。

• language (字符串，必需) — 检测到的语言代码（ISO 639-1，例如 en）。当前为空 — 语言检测尚未启用。

• duration (数字，必需) — 音频持续时间，单位为秒（四舍五入到 2 位小数）。

• words (数组<对象>) — 带时间戳的词级分段。为空时省略。

  • text (字符串，必需) — 单词文本。

  • start (数字，必需) — 单词开始时间，单位为秒（2 位小数）。

  • end (数字，必需) — 单词结束时间，单位为秒（2 位小数）。

  • confidence (数字) — 置信度分数（0.0–1.0，基于熵）。为 0 时省略。

  • speaker (整数) — 说话人索引（从 0 开始）。仅在 diarize=true 时存在。

• channels (数组<对象>) — 每通道转录。仅在 multichannel=true 时存在。单通道音频时省略。

  • index (整数，必需) — 源音频中从 0 开始的通道索引。

  • language (字符串) — 此通道检测到的语言代码。当前为空。

  • text (字符串，必需) — 此通道的完整转录文本。

  • words (数组<对象>) — 此通道的带时间戳的词级分段。

    • text (字符串，必需) — 单词文本。

    • start (数字，必需) — 单词开始时间，单位为秒（2 位小数）。

    • end (数字，必需) — 单词结束时间，单位为秒（2 位小数）。

    • confidence (数字) — 置信度分数（0.0–1.0，基于熵）。为 0 时省略。

    • speaker (整数) — 说话人索引（从 0 开始）。仅在 diarize=true 时存在。

响应示例：

{
  "text": "The balance is $167,983.15. That is $23.4 kilograms.",
  "language": "",
  "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
    }
  ]
}

---

语音转文本 - 流式处理

WebSocket 端点：wss://api.x.ai/v1/stt

通过 WebSocket 进行实时流式语音转文本。将原始音频作为二进制帧流式传输，并在音频处理过程中接收 JSON 转录事件。配置通过连接时的查询参数完成。

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

查询参数

• sample_rate (整数，可选，默认值：16000) — 音频采样率，单位为 Hz。支持的值：8000、16000、22050、24000、44100、48000。

• encoding (字符串，可选，默认值：pcm) — 音频编码格式。pcm — 有符号 16 位小端序（2 字节/采样）。mulaw — G.711 µ-law 编码（1 字节/采样）。alaw — G.711 A-law 编码（1 字节/采样）。

• interim_results (布尔值，可选，默认值：false) — 当为 true 时，服务器在处理音频时大约每 500 毫秒发出部分转录事件（is_final=false）。当为 false（默认）时，只发送最终结果。

• endpointing (整数，可选，默认值：10) — 服务器触发 speech_final=true 事件之前的静音持续时间（毫秒），表示说话人已停止说话。范围：0–5000。设置为 0 表示无延迟（在任何 VAD 静音边界触发）。默认值：10ms。

• language (字符串，可选，默认值：) — 语言代码（例如 en、fr、de、ja）。设置后，启用反向文本规范化 — 将口语形式的数字、货币和单位转换为书面形式。

• multichannel (布尔值，可选，默认值：false) — 当为 true 时，为交错的多通道音频启用每通道转录。需要将 channels 设置为 ≥ 2。

• channels (整数，可选，默认值：1) — 交错音频通道的数量。当 multichannel=true 时必需。最小值：2，最大值：8。

• diarize (布尔值，可选，默认值：false) — 当为 true 时，启用说话人分离。transcript.partial 和 transcript.done 事件中的单词包含一个 speaker 字段（整数），用于标识检测到的说话人。

• keyterm (字符串（可重复），可选) — 用于引导转录的关键词（例如产品名称、专有名词）。对每个术语重复该参数（例如 keyterm=Understand+The+Universe）。最多 100 个术语，每个最多 50 个字符。

• filler_words (布尔值，可选，默认值：false) — 当为 true 时，填充词（例如 uh、um、er）包含在转录文本中。当为 false（默认）时，填充词会自动从转录文本和 words 数组中移除。

• smart_turn (数字，可选) — 启用智能轮次结束检测。设置为 0.0 到 1.0 之间的置信度阈值。当模型的轮次结束概率在 VAD 静音边界超过此阈值时，立即触发 speech_final。当置信度低于阈值时，speech_final 被抑制，事件被降级为 chunk_final。当启用智能轮次时，每个 transcript.partial 事件都包含一个 end_of_turn_confidence 字段（0.0–1.0）。示例：smart_turn=0.7。

• smart_turn_timeout (整数，可选) — 强制触发 speech_final 的最大静音持续时间（毫秒），即使智能轮次模型预测说话人尚未结束。作为安全网，防止在长时间静音期间会话挂起。仅适用于 smart_turn 启用时。范围：1–5000。示例：smart_turn_timeout=3000。

• vad_threshold (数字，可选，默认值：0.08) — 语音活动检测的语音概率阈值（0.0–1.0）。低于阈值的音频块被视为非语音并被跳过不转录。较低的值可以转录较安静或较嘈杂的语音（例如窄带电话），但可能会为背景噪音产生虚假文本；0 完全禁用此门控。不影响端点检测或 speech_final 计时。默认值：0.08。

客户端消息

• 二进制帧（音频） — 将原始音频作为二进制 WebSocket 帧发送，编码方式由 encoding 查询参数指定。音频应实时分块流式传输（例如一次 100 毫秒）。不要使用 base64 编码 — 直接发送原始字节。

• finalize — 强制当前话语立即作为 speech_final 结束，无需等待 VAD 端点检测或智能轮次。会话保持打开状态，您可以继续流式传输音频。接受 finalize 或 Finalize 作为类型值。当 multichannel=true 时，可选的 channel（从 0 开始）将结束限制在该通道；省略 channel 以结束所有通道。

• audio.done — 表示所有音频已发送。服务器刷新任何剩余的缓冲音频，发出最终转录事件，并发送 transcript.done 事件。transcript.done 后连接关闭。

服务器消息

• transcript.created — WebSocket 连接建立后立即发送，表示服务器已准备好接收音频。在发送音频前等待此事件 — 服务器需要初始化其后端 ASR。

• transcript.partial — 音频流的部分转录结果。两个布尔字段传达状态：临时结果（is_final=false）表示文本可能仍会变化，块结束（is_final=true、speech_final=false）表示该块已锁定，话语结束（is_final=true、speech_final=true）表示说话人已停止说话。

• transcript.done — audio.done 后的最终转录。duration 始终存在。当 multichannel=true 时每个通道一个。此事件后连接关闭。

• error — 会话期间发生错误。大多数错误（管道故障、流超时）会关闭连接。只有客户端消息解析错误保持连接打开。

示例消息流

1. transcript.created（服务器）

2. 二进制帧（音频）（客户端）

3. 二进制帧（音频）（客户端）

4. transcript.partial（服务器）

5. 二进制帧（音频）（客户端）

6. transcript.partial（服务器）

7. 二进制帧（音频）（客户端）

8. transcript.partial（服务器）

9. audio.done（客户端）

10. transcript.done（服务器）