实时语音 (WebSocket)

POST https://api.mafdet.ai/v1/realtime/sessions   ← 换一张票
wss://api.mafdet.ai/v1/realtime                   ← 用票开会话

实时会话是一条长连的 WebSocket，音频双向流动：你一边录一边推，模型不等你说完就开始 回答。它适合实时字幕、语音对话——凡是「等录完再处理就失去意义」的场景。

只是要转录一个文件？别用这个。 已经录好的音频走 /v1/chat/completions，作为音频 part 发给 gemini-3.5-transcribe。那是一次普通的 HTTPS 请求，便宜约 30%，也没有会话要管。 只有在音频还不存在的时候，实时会话的复杂度才值得。

模型

两个都是 PAID 档，都还没转正式版——发布阶段直接写在 模型页的名字里。

两步，以及为什么是两步

WebSocket 不接受你的 API Key。 你先用 Key 通过 HTTPS 换一张一次性票， 再拿票去开连接。

这是刻意的。WebSocket 的凭据走在握手 URL 和请求头里，会进代理日志、浏览器历史和 ps 输出——HTTPS 的请求体不会。票只能用一次、30 秒过期，会话一开始它就作废了。

1. 换票

你的 API Key 需要 realtime:call 这个 scope。scope 只在建 Key 时确定， 事后改不了——所以现有的 Key 升级不了，得新建一把并勾上实时语音。没有这个 scope 的 Key 会拿到 403 INSUFFICIENT_SCOPE；正因如此，一把拿去读账户的 Key 不会悄悄 具备开计费语音会话的能力。

curl https://api.mafdet.ai/v1/realtime/sessions \
  -H "Authorization: Bearer $MAFDET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.5-transcribe-live"}'

{
  "realtimeSessionId": "…",
  "ticket": "S3vQ…",
  "wsUrl": "wss://api.mafdet.ai/v1/realtime",
  "subprotocol": "mafdet-realtime.v1",
  "expiresInSeconds": 30,
  "model": "gemini-3.5-transcribe-live",
  "billing": {
    "dimensions": [{ "dimension": "AUDIO_INPUT", "sellMicroUsd": "…" }],
    "maxSessionSpendMicroUsd": "…",
    "maxSessionSeconds": 600
  }
}

billing 是这场会话自己的价目表和花费上限，在连接之前就返回——会话不会是无底洞。

2. 30 秒内连上

票放在 WebSocket 子协议头里，不放 URL：

Sec-WebSocket-Protocol: mafdet-realtime.v1, mafdet-ticket.<ticket>

要连的前一刻再去换票。 30 秒只够开一条连接，别的都不够——如果你换完票才去准备 音频、申请麦克风权限、或者等用户点一下，票就已经过期了，连接会以 4401 关闭。

收发

帧是 JSON。音频是 base64 的 PCM，16 位小端单声道，上行 16 kHz、下行 24 kHz。

{
  "realtimeInput": {
    "mediaChunks": [
      { "mimeType": "audio/pcm;rate=16000", "data": "<base64 pcm16le>" }
    ]
  }
}

服务端边生成边推回转录文本或音频，每段回答结束时给一个 turn-complete 帧。 用量是按轮返回的，不是累计快照——想要整场的数字，自己把每轮加起来。

限额

花费撞上限、或者钱包不够，会话同样会结束。每一种限额都用一个明确的关闭码和理由 关闭连接，不会静默断线。 Key 打满和组织打满都是 4429。

计费

按 token 计，分模态：文字和音频在两个方向上各自定价，贵的是音频那半边。 会话进行中滚动预留额度，结束时按真实用掉的轮数结算。

会话非正常死亡——你的进程被杀、网络断了、网关重启——会按它消耗过的持久记录结算。 凭空消失的会话不会向你收钱，也不会白送。

隐私

音频只在这一轮里流动，不录音。Mafdet 不保存你的麦克风音频，也不保存模型的音频， 两者都不写进会话历史和日志。

下一步

• 改用文件转录
• Key 的权限与 scope
• 你的套餐能用什么