语音转文本

快速开始

通过一次 API 调用转录音频文件：

curl -X POST https://api.x.ai/v1/stt \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F model=grok-voice-transcribe-2.0 \
  -F format=true \
  -F language=en \
  -F "keyterm=Understand The Universe" \
  -F file=@audio.mp3

import os
import requests

response = requests.post(
    "https://api.x.ai/v1/stt",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    files={"file": ("audio.mp3", open("audio.mp3", "rb"), "audio/mpeg")},
    data=[
        ("model", "grok-voice-transcribe-2.0"),
        ("format", "true"),
        ("language", "en"),
        ("keyterm", "Understand The Universe"),
    ],
)
response.raise_for_status()

result = response.json()
print(result["text"])
print(f"Duration: {result['duration']}s")
for word in result.get("words", []):
    print(f"  {word['start']:.2f}s - {word['end']:.2f}s: {word['text']}")

import fs from "fs";

const formData = new FormData();
formData.append("model", "grok-voice-transcribe-2.0");
formData.append("format", "true");
formData.append("language", "en");
formData.append("keyterm", "Understand The Universe");
formData.append("file", new Blob([fs.readFileSync("audio.mp3")]), "audio.mp3");

const response = await fetch("https://api.x.ai/v1/stt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
  },
  body: formData,
});

if (!response.ok) throw new Error(`STT error ${response.status}`);

const result = await response.json();
console.log(result.text);
console.log(`Duration: ${result.duration}s`);
for (const word of result.words ?? []) {
  console.log(`  ${word.start.toFixed(2)}s - ${word.end.toFixed(2)}s: ${word.text}`);
}

注意：file 参数必须位于 multipart form 中所有其他参数之后。

获取 API Key →

实时语音演示

模型选择

在 REST 表单中或以 WebSocket 查询参数传入 model。

支持的语言

该 language 参数可为以下语言启用格式化。无论是否设置 language 参数，模型都能转录这些语言；设置该参数会将数字、货币和单位格式化为书面形式。

请求体

请求使用 multipart/form-data。必须提供 file 或 url 其中之一。

† 必须提供 file 或 url 其中之一。

Option 字段应位于 file 之前；对于 streamable upload，在 file 之后发送的字段可能会被忽略。

文本格式化示例

curl -X POST https://api.x.ai/v1/stt \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F model=grok-voice-transcribe-2.0 \
  -F format=true \
  -F language=en \
  -F "keyterm=Understand The Universe" \
  -F file=@meeting.mp3

该 file 参数必须位于 multipart form 中所有其他参数之后。

响应

响应包含完整转录文本、音频时长和词级时间戳。

{
  "text": "The balance is $167,983.15.",
  "language": "en",
  "duration": 3.45,
  "words": [
    { "text": "The", "start": 0.24, "end": 0.48 },
    { "text": "balance", "start": 0.48, "end": 0.96 },
    { "text": "is", "start": 0.96, "end": 1.12 },
    { "text": "$167,983.15.", "start": 1.12, "end": 3.20 }
  ]
}

支持的音频格式

Container 格式（自动检测）

Raw 格式（需要 audio_format 和 sample_rate）

限制

• 最大文件大小： 500 MB

• Channels： Mono、stereo，或最多 8 个 channel（使用 multichannel=true）

• Sample rate： 8000、16000、22050、24000、44100、48000 Hz

Streaming Speech-to-Text（WebSocket）

实时 transcription 请使用位于 wss://api.x.ai/v1/stt 的 WebSocket API。Client 将 raw 音频作为 binary WebSocket frame streaming，并在处理音频时接收 JSON transcript event。

Endpoint： wss://api.x.ai/v1/stt

通过 URL query parameter 完成配置，无需 setup message。音频以 raw binary frame 发送（不使用 base64 encoding）。

Query Parameters

服务器事件

该 transcript.partial event 使用 is_final 和 speech_final 表示三种状态：

客户端消息

• 二进制帧 — 使用指定编码的原始音频（按实时节奏分块传输，例如每块 100 ms）。使用 encoding=opus 时，每个二进制帧必须且只能包含一个 Opus 数据包——请参阅 Opus 流式传输。

• {"type": "finalize"} — 强制当前 utterance 立即以 speech_final 完成，用于 PTT

• {"type": "audio.done"} — 表示音频结束，触发 transcript.done

transcript.done 告知 server 不再发送音频，flush 剩余 transcript 并关闭 WebSocket。

Push-to-talk 示例（释放按钮时 finalize，然后继续 session）：

{"type": "Finalize"}

Per-channel finalize（仅 multichannel，例如 agent 位于 channel 0）：

{"type": "Finalize", "channel": 0}

Opus 流式传输

设置 encoding=opus 可传输压缩音频而非原始 PCM，带宽约为 4 KB/s，而 24 kHz 的 PCM16 约为 48 KB/s，且无需客户端重采样。

工作原理：

• 发送时，每个二进制 WebSocket 帧必须且只能包含一个原始 Opus 数据包。Opus 数据包不标记自身边界，边界由 WebSocket 分帧确定，因此绝不能拼接多个数据包，也不能将一个数据包拆分到多个帧。

• 省略 sample_rate——Opus 数据包不携带采样率，此编码会忽略该参数。按音源产生的采样率编码即可。

• multichannel 不支持 Opus——仅支持单声道。

• 发送原始数据包，不要发送容器。如需转录 Ogg-Opus 或 WebM 文件，请改用批量处理端点，该端点会自动识别容器。

• 如果某帧无法解码，服务器会发送 error 事件并关闭会话。分帧错误的数据包常会被解码为噪声而非触发错误，因此请仔细检查编码器是否每帧输出一个完整数据包。

示例 URL：

wss://api.x.ai/v1/stt?model=grok-voice-transcribe-2.0&encoding=opus&interim_results=true

典型用例：移动设备或其他带宽受限客户端的听写和实时转录；在这些场景下，传输原始 PCM 会浪费带宽。大多数平台音频 API 和 WebRTC 栈都能原生输出 Opus 数据包。

Multichannel Streaming

设为 multichannel=true 和 channels ≥ 2 时，server 分别转录每个 audio channel。将交错的 multichannel PCM（例如 stereo 的 L,R,L,R,…）作为 binary frame 发送，server 会 de-interleave 并并行处理每个 channel。

工作原理：

• transcript.created 发送一次（session 级别，无 channel_index）。

• transcript.partial event 包含 channel_index 字段（从 0 开始），用于标识源 channel。不同 channel 的 event 会交错到达。

• transcript.done 在 每个 channel 发送一次，位于 audio.done 之后，每个都包含自己的 channel_index。

• Client Finalize 不带 channel 时会一次 finalize 所有 channel；{"type": "Finalize", "channel": N} 仅 finalize channel N（从 0 开始）。

• Chunk 大小应考虑所有 channel，例如 16 kHz stereo PCM16 中，100 ms = 6,400 bytes（每个 channel 3,200 × 2 个 channel）。

示例 URL：

wss://api.x.ai/v1/stt?model=grok-voice-transcribe-2.0&sample_rate=16000&encoding=pcm&multichannel=true&channels=2&interim_results=true

典型用例： Call center 录音，agent 位于 channel 0，客户位于 channel 1，无需 speaker diarization 即可实现 per-speaker transcription。

Smart Turn

Smart Turn 使用轻量 ML 模型，在静音停顿时预测说话者是否已完成表达，减少句中停顿（例如口述数字或在从句间思考）导致的错误 endpointing。

工作原理：

• 通过 smart_turn=<threshold> 启用后，模型会在每个 VAD 静音边界评估累计音频。

• 如果 end-of-turn confidence 超过 threshold，speech_final=true 会正常触发。

• 如果 confidence 低于 threshold，event 会降级为 chunk_final（is_final=true、speech_final=false），transcript 文本锁定，但 utterance 继续。

• 每个 transcript.partial event 都包含 end_of_turn_confidence 字段（0.0–1.0），前提是启用了 Smart Turn。

• 在用户说话期间，end_of_turn_confidence 为 0.0（模型仅在静音边界运行）。

静音 timeout（smart_turn_timeout）：

启用 Smart Turn 后，模型完全控制 speech_final 的触发时机。为防止 session 在长时间静音时挂起（例如用户离开），请设置 smart_turn_timeout 为最长静音时长（毫秒，1–5000）。如果模型持续预测 "not done" 超过该时长，speech_final 仍会触发，作为安全保障。

wss://api.x.ai/v1/stt?model=grok-voice-transcribe-2.0&sample_rate=16000&encoding=pcm&interim_results=true&smart_turn=0.7&smart_turn_timeout=3000

不设置 smart_turn_timeout 时，模型拥有无限控制权，speech_final 仅在 confidence 超过 threshold 时触发。

启用 Smart Turn 的 event 示例：

{
  "type": "transcript.partial",
  "text": "I will buy two of those, please.",
  "words": [...],
  "is_final": true,
  "speech_final": true,
  "start": 0.0,
  "duration": 2.4,
  "end_of_turn_confidence": 0.983
}

典型用例： 适用于希望避免在用户句中打断的 Voice assistant 和 conversational AI。没有 Smart Turn 时，口述电话号码或在从句间思考的短暂停顿会触发 speech_final。启用 Smart Turn 后，模型会等待检测到自然轮次结束（confidence 0.95+），并在句中停顿期间正确抑制触发（confidence ~0.005）。

完整示例

import asyncio
import json
import os

import websockets

API_KEY = os.environ["XAI_API_KEY"]
WS_URL = "wss://api.x.ai/v1/stt?model=grok-voice-transcribe-2.0&sample_rate=16000&encoding=pcm&interim_results=true&language=en&keyterm=Understand+The+Universe"

async def transcribe_stream(audio_file: str):
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with websockets.connect(WS_URL, additional_headers=headers) as ws:
        # Wait for server ready signal
        msg = json.loads(await ws.recv())
        assert msg["type"] == "transcript.created"
        print("Server ready")

        # Read raw PCM from a WAV file (skip 44-byte header)
        with open(audio_file, "rb") as f:
            f.read(44)  # Skip WAV header
            chunk_size = 16000 * 2 // 10  # 100ms of PCM16 at 16kHz

            while chunk := f.read(chunk_size):
                await ws.send(chunk)  # Send raw binary — no base64
                await asyncio.sleep(0.1)

        # Signal end of audio
        await ws.send(json.dumps({"type": "audio.done"}))

        # Collect events until transcript.done
        async for message in ws:
            event = json.loads(message)
            if event["type"] == "transcript.partial":
                prefix = "FINAL" if event["is_final"] else "partial"
                print(f"[{prefix}] {event['text']}")
            elif event["type"] == "transcript.done":
                print(f"\nFull transcript: {event['text']}")
                print(f"Duration: {event['duration']}s")
                break

asyncio.run(transcribe_stream("audio.wav"))

import fs from "fs";
import WebSocket from "ws";

const apiKey = process.env.XAI_API_KEY;
const url = "wss://api.x.ai/v1/stt?model=grok-voice-transcribe-2.0&sample_rate=16000&encoding=pcm&interim_results=true&language=en&keyterm=Understand+The+Universe";

const ws = new WebSocket(url, { headers: { Authorization: `Bearer ${apiKey}` } });

ws.on("open", () => console.log("Connected"));

ws.on("message", (data) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case "transcript.created":
      console.log("Server ready — streaming audio...");
      // Read WAV file, skip 44-byte header, send 100ms chunks
      const audio = fs.readFileSync("audio.wav").slice(44);
      const chunkSize = 3200; // 100ms at 16kHz, 16-bit
      let offset = 0;
      const interval = setInterval(() => {
        if (offset >= audio.length) {
          clearInterval(interval);
          ws.send(JSON.stringify({ type: "audio.done" }));
          return;
        }
        ws.send(audio.slice(offset, offset + chunkSize));
        offset += chunkSize;
      }, 100);
      break;
    case "transcript.partial":
      const prefix = event.is_final ? "FINAL" : "partial";
      console.log(`[${prefix}] ${event.text}`);
      break;
    case "transcript.done":
      console.log(`\nFull transcript: ${event.text}`);
      console.log(`Duration: ${event.duration}s`);
      ws.close();
      break;
  }
});

用例

• 实时字幕 — 为视频通话、会议和直播提供实时字幕

• Voice assistant — 转录用户语音，供自然语言理解 pipeline 使用

• Call center — 通过 multichannel per-speaker transcription 提供实时 agent 辅助

• 无障碍 — 为听障用户提供实时 transcription

• Voice command — 为免手持界面提供低延迟 speech-to-action

Streaming STT 提示

• 使用 16 kHz sample rate 和 PCM encoding（sample_rate=16000&encoding=pcm），这是模型的原生 rate，可避免在 server 上 resampling

• 启用 interim_results以获得响应迅速的 UX，在用户说话时显示 transcription

• 使用 language=en启用文本格式化，数字和货币会以标准形式书写

• 发送 100 ms audio chunk（16 kHz PCM16 时为 3,200 bytes），在延迟和效率之间取得良好平衡

• 使用 encoding=opus（适用于带宽受限的客户端）——约 4 KB/s，而 24 kHz 原始 PCM 约为 48 KB/s。请参阅 Opus 流式传输

• 等待 transcript.created 后再发送音频，server 需要初始化 ASR backend

错误处理

相关内容

• Voice 概览 — 所有 xAI voice 能力概览

• Text to Speech — 将文本转换为语音

• API 参考 — Speech to text — 完整的 REST endpoint 规范

• API 参考 — Streaming — WebSocket streaming 规范