SuperAPI AI 工具集

add-voice

编程与开发

查看项目

更新于 11-19 04:05

技能介绍

add-voice 是一个面向开发者的技能,用于把 Grok Speech to Speech 实时语音接入已有应用。触发方式包括运行 /add-voice、输入 Voice Mode,或明确要求为应用添加 Grok 实时语音。

用途与目标 技能的核心目标是在应用中建立可用的双向语音通路:用户应用侧麦克风输入、音频输出,连接 wss://api.x.ai/v1/realtime?model=grok-voice-latest,并采用安全的鉴权方式。由于 Cursor 没有原生麦克风,技能接入的是应用或示例客户端,而不是 IDE 本身。

协议优先 技能先定义与语言无关的事件循环,示例默认使用 TypeScript;只有当客户端 API 存在差异(例如 ws 与 websockets)时,才补充简短的 Python 版本。技能引用官方文档,包括语音转语音能力、临时令牌和定价页面;定价内容仅以文档为准。

第一步:梳理应用 需要确定应用的技术栈,例如无语音、OpenAI Realtime、STT→LLM→TTS 级联、仅 TTS/STT,并确定客户端类型是 Web、Node、iOS、Android 还是服务端。如果已有级联或 OpenAI Realtime,则按下方单路双向循环进行替换(涉及 URL、模型、语音、事件差异);仅当产品仍需在智能体之外进行一次性听或说时,才保留独立的 /v1/stt 或 /v1/tts。

鉴权 服务端使用 Bearer XAI_API_KEY。浏览器或移动端由后端 POST https://api.x.ai/v1/realtime/client_secrets 获取临时令牌,客户端使用该临时令牌(Bearer 或浏览器 sec-websocket-protocol: xai-client-secret.<token>)。不得将长期密钥放入客户端包,也不要在聊天中粘贴密钥。

连接与会话 连接 URL 为 wss://api.x.ai/v1/realtime?model=grok-voice-latest。连接打开后发送 session.update,设置语音(默认 eve)、instructions、turn_detection: { type: "server_vad" }(或 null 表示按键说话),采样率默认 PCM 24 kHz,除非应用已有统一标准。需设置 audio.input.transcription.model: "grok-transcribe",否则不会收到用户转写;conversation.item.input_audio_transcription.updated 是累积值而非增量。如需工具,可配置 web_search、x_search、file_search、mcp 或自定义函数。

音频输入输出(应用侧) 每个会话只创建一个 AudioContext 用于采集和播放,并在用户手势中创建以满足自动播放策略。请求 24 kHz;若浏览器给出其他采样率,发送前需重采样。麦克风经 AudioWorklet 以约 100 毫秒分块,通过 input_audio_buffer.append 发送(或二进制传输)。WebSocket 与麦克风并行启动;提前缓冲音频,连接打开后冲刷。收到 response.output_audio.delta 立即播放,安排约 150 毫秒提前量使分块衔接。收到 input_audio_buffer.speech_started 时停止所有已排队音频(打断)。转写行方面:在 input_audio_buffer.committed 时用 item_id 创建用户行,在 …transcription.updated 时填充;助手文本来自 response.output_audio_transcript.delta / .done,并在 response.done 时结束该轮。函数工具调用时,发送 function_call_output,完成播放后再 response.create。

编辑器 UI 约定 编辑器主按钮位于右侧。输入框为空时显示波形图标(描边样式,例如 Phosphor WaveformIcon weight="bold",不要用填充样式,否则 16 像素下会糊成一团),点击进入语音模式。有文本时显示经典发送箭头;语音模式下该文本进入实时会话(conversation.item.create + response.create)。文本回复流式输出时显示停止方块。语音进行中,同一按钮显示动画波形(4 根条,约 3 像素宽、2 像素间距、约 16 像素高,最小缩放 0.4 以保证 28 像素按钮内可读),点击结束会话。动画由阶段驱动:聆听慢、说话快、连接/思考更慢且略微变暗(不透明度不低于 0.75)。需尊重 prefers-reduced-motion。不要 X 按钮,不要脉冲圆环。状态显示在输入框内而非周围:占位文本为 Connecting… / Listening… / Thinking… / Speaking…,并加 sr-only role="status"。不要单独状态行。麦克风图标保留给听写(/add-dictation),绝不用于语音模式。

TypeScript 骨架(默认) const url = "wss://api.x.ai/v1/realtime?model=grok-voice-latest"; // Node:传 Authorization 头。浏览器:使用 xai-client-secret.<token> 协议。 const ws = new WebSocket(url /* , { headers: { Authorization: Bearer ${token} } } /); ws.addEventListener("open", () => { ws.send(JSON.stringify({ type: "session.update", session: { voice: "eve", instructions: "You are a helpful voice agent.", turn_detection: { type: "server_vad" } } })); }); ws.addEventListener("message", (ev) => { const event = JSON.parse(String(ev.data)); if (event.type === "response.output_audio.delta") { / 解码 base64 PCM 并播放 */ } });

Python 版本(仅当应用为 Python) import json, os, websockets url = "wss://api.x.ai/v1/realtime?model=grok-voice-latest" headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"} async with websockets.connect(url, additional_headers=headers) as ws: await ws.send(json.dumps({ "type": "session.update", "session": { "voice": "eve", "instructions": "You are a helpful voice agent.", "turn_detection": {"type": "server_vad"} } })) async for raw in ws: event = json.loads(raw) if event.get("type") == "response.output_audio.delta": pass # 解码并播放

埋点与调试 在首次人工测试前运行 /debug-voice:它会提出方案,然后用应用自身语言安装仅开发环境使用的日志汇(POST /api/voice/log → .voice-logs/<sessionId>.ndjson,加入 gitignore)、客户端日志器(音频缩减为字节数),并在 UI 中显示会话 ID。同一技能包含修复循环和症状→日志特征→修复对照表。

冒烟测试 通过 conversation.item.create + response.create 进行文本轮次,确认音频或转写事件;在构建后的客户端包中 grep 环境变量名和 client_secrets,确认无长期密钥;让用户戴耳机测试,因为扬声器下麦克风会听到回复导致模型自问自答,这是回声而非循环缺陷。之后用 /debug-voice 迭代。

范围之外 仅语音转文字(/add-dictation)、文本朗读(/add-read-aloud)、图像生成与纯文本推理、虚构端点/事件/CLI 标志均不在范围内。