原生透传层

音生文 STT

上传一段音频或给一个音频地址，拿到转写文本和词级时间戳。请求原样转发给 Grok，Grok 专有参数在这里全部可用。

POST/xai/v1/stt

端点

POST /xai/v1/stt
WSS  /xai/v1/stt        # 流式识别，见总览

这是 原生透传路径。同一能力在 OpenAI 兼容层的写法见 音生文 STT（OpenAI 兼容）。

同字段的无前缀路径

/v1/stt 用的是完全相同的字段名（不转换），区别只是报错会被包成 OpenAI 信封 {"error":{"message":...}}。

• 想要 xAI 原文报错 → 用本页的 /xai/v1/stt
• 想要统一错误格式、又不想改字段名 → 用 /v1/stt

请求

请求格式是 multipart/form-data，不是 JSON。file 和 url 至少给一个。

curl -X POST https://api.wxiai.com/xai/v1/stt \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  -F "language=zh" \
  -F "format=true" \
  -F "diarize=true" \
  -F "file=@./meeting.mp3"

file 必须是最后一个字段

其余字段要写在 file 前面——流式上传时，排在 file 之后的字段可能被忽略。

请求参数

参数	必填	说明
file	二选一	音频文件，最大 500 MB。必须是 multipart 最后一个字段
url	二选一	音频地址，服务端下载后转写
language	否	语言码。只有配 format=true 时才起作用（用于文本格式化）
format	否	开启反向文本规范化：把口语数字/货币转成书面形式。需要同时传 language
diarize	否	说话人分离。开启后每个词会带 speaker 字段
multichannel	否	逐声道独立转写，结果放在 channels 数组里
channels	否	声道数（2–8）。仅裸音频需要，容器格式自动识别
audio_format	否	裸音频格式提示：pcm / mulaw / alaw。容器格式别传这个字段
sample_rate	否	采样率，仅裸音频需要：8000、16000、22050、24000、44100、48000
keyterm	否	Grok 专有。关键词偏置（产品名、专有名词）。重复传多个，最多 100 个、每个 ≤ 50 字符
filler_words	否	Grok 专有。为 true 时保留 "uh"、"um" 这类填充词；默认会从文本和 words 里移除
vad_threshold	否	Grok 专有。语音活动门限 0.0–1.0，默认 0.5。调低更适应轻声/噪声，但可能把背景噪声转成文字；0 表示关闭门限

keyterm 怎么传多个

同一个字段名重复传即可：

-F "keyterm=Understand The Universe" -F "keyterm=Grok"

返回

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

字段	说明
text	完整转写文本
language	识别到的语言（BCP-47，如 en、es-mx）
duration	音频时长（秒，保留 2 位小数）
words	词级时间戳。开了 diarize 时每个词多一个 speaker（整数）
channels	逐声道结果。开了 multichannel 时才有，每项含 index、text、words

支持的音频格式

容器格式（自动识别，不要传 audio_format）：.wav、.mp3、.ogg、.opus、.flac、.aac、.mp4、.m4a、.mkv

裸格式（必须同时传 audio_format 和 sample_rate）：

格式	audio_format 值	说明
PCM	pcm	有符号 16 位小端（2 字节/采样）
µ-law	mulaw	G.711 µ-law（1 字节/采样）
A-law	alaw	G.711 A-law（1 字节/采样）

上限：单文件 500 MB；单声道、立体声或最多 8 声道（需 multichannel=true）。

这一层的注意点

• 发 JSON 会失败：STT 只接受 multipart/form-data。
• file 没放最后：写在 file 后面的字段可能被丢掉——keyterm 这类要多传的字段尤其容易踩。
• audio_format 只给裸音频：给 .mp3 / .wav 传它反而可能出错。
• format=true 必须配 language：不配的话格式化不生效。

相关页

• 音频处理总览 —— 支持格式、语言表、计费方式、流式识别与 Smart Turn
• 音生文 STT（OpenAI 兼容） —— 同一能力的另一条路径（字段更少，但没有 Grok 专有参数）
• 文生音 TTS（原生透传） —— 反向能力
• 错误码