SuperAPI AI 工具集

add-dictation

编程与开发

查看项目

更新于 11-19 03:05

技能介绍

用途 add-dictation 用于在现有应用中接入 Grok 语音转文字(Speech to Text)。典型形态包括:在编辑器的 composer 输入区域旁加一个麦克风按钮,点击后口述、再点击结束,文本插入光标处;也可以显示实时字幕,或对已录制的音频文件、音频 URL 生成转写文本。该技能通过 /add-dictation 指令、输入 Dictate,或明确的“转写”意图触发。资料特别说明:Cursor 本身没有麦克风,需要接入的是被开发的应用,而不是 IDE。

主要能力 支持两种调用路径。批处理路径(默认)向 https://api.x.ai/v1/stt 发一次 POST 请求,适合“点按说话、再点按出文字”、上传文件、传入 URL 的场景;一次请求即可完成,无需建立套接字,密钥不会离开服务端。流式路径通过 wss://api.x.ai/v1/stt 并由后端中继,适合需要边说边显示文字的字幕、长口述、按住说话等需要中间结果的交互。流式方可返回 interim 文本、最终文本与结束事件,并支持 finalize、audio.done 等控制消息。

可配置项包括:模型选择(需以官方 model-selection 文档最新列出的为准,资料快照中为 grok-voice-transcribe-2.0,省略时为 grok-voice-transcribe-1.0)、语言、format(把口语数字/金额转成书面形式,需配合 language)、keyterm(重复传入以支持产品名和专业术语,最多 100 个、每个 50 字符)、smart_turn 与 smart_turn_timeout、endpointing(默认 400ms)、diarize(区分说话人,输出 words[].speaker)、multichannel(仅 PCM)、filler_words(保留“呃”等填充词)、encoding=opus(低带宽或移动端,每帧一个原始 Opus 包)、audio_format=pcm、vad_threshold(安静或电话音频场景)。批处理接口支持 WAV、MP3、OGG、Opus、FLAC、AAC、MP4、M4A、MKV、WebM 等容器格式,file 或 url 任选,最大 500 MB。

使用方式 鉴权使用服务端保存的 Bearer XAI_API_KEY,不放在客户端打包产物中,也不在聊天中粘贴密钥。资料指出官方 STT 文档没有临时令牌流程,浏览器无法为 WebSocket 设置请求头,因此浏览器端流式必须经过自建后端中继。

批处理实现:客户端用 MediaRecorder 录音得到 Blob,POST 到自建路由;服务端以 multipart/form-data 转发,选项字段在前、file 最后(file 之后的字段可能被忽略),把 model 设为文档最新模型,再按需附加 format、language、keyterm 等,最后返回 text、language、duration,以及可选的 words、channels。错误码含义:400 输入有误、413 超过 500 MB、429 需退避重试、502 URL 抓取失败、503 可重试。

流式实现:后端中继持有密钥,在服务端构造查询字符串(model、sample_rate、encoding、interim_results、language 等),向上游建立带 Authorization 头的 WebSocket,转发浏览器二进制音频帧和客户端控制消息,下行转发 transcript.* 与 error 事件。浏览器端采集 PCM16 小端、单声道、16 kHz、每 100ms 一帧(3,200 字节)的原始二进制,不用 base64;需等到 transcript.created 后再开始发送。MediaRecorder 输出的是容器而非原始帧,不能直接用于流式。收到 transcript.partial 时按 speech_final、is_final、interim 分别拼接已确定文本与临时文本;停止时发送 audio.done,按住说话松开时发送 Finalize 并继续流。

如果服务端使用 Python,资料给出用 requests 发批处理、用 websockets 发流式的等价写法。资料还提供冒烟测试方法:批处理用 curl 提交短音频应返回 200 与 text,format=true 但缺少 language 应返回 400;流式朗读两句并在中间停顿,检查边界处是否重复或丢词;还需在客户端打包产物中搜索 XAI_API_KEY 确认其不存在。可用 /debug-voice 从日志排查,把钩子点换成 transcript.* 事件。

适用场景 适合需要给应用加入语音输入按钮、语音字幕、录音转写、会议区分说话人、双声道区分的开发者。若与 /add-voice 同时安装,/add-voice 的波形主按钮保持不变,麦克风作为旁边次要的 ghost 按钮;/add-voice 已有的 PCM 采集可复用给流式 STT,并将其采样率作为 sample_rate 传入(16 kHz 为原生,8000、22050、24000、44100、48000 由服务端重采样)。

限制 不在范围内:让语音回话(/add-voice)、朗读文本(/add-read-aloud)。不得自行发明 STT 令牌流程、端点、模型 id 或文档中没有的事件名。模型 id 与价格须以官方文档为准,本资料未提供价格信息。