实时语音转文字

实时 ASR 已通过 Open API 开放，适用于实时字幕、语音输入和会议转写。

WebSocket：wss://realtime.kittaai.com/v2/stt/live
子协议：realtime.stt.msgpack.v1
模型：kitta-asr-realtime-v1
音频：单声道 PCM16，16 kHz；建议每 100 ms 发送 3,200 字节
单次会话最长 600 秒
每个开始计费的分钟消耗 200 credits

可先请求 GET https://realtime.kittaai.com/v2/stt/capabilities 获取当前能力；完整 Open API 目录仍可通过 GET /api/openapi.json 获取。

服务端接入

服务端可以在 WebSocket 握手中发送 API Key：

Authorization: Bearer KITTA_API_KEY

import { readFile } from 'node:fs/promises';
import WebSocket from 'ws';

const ws = new WebSocket('wss://realtime.kittaai.com/v2/stt/live', 'realtime.stt.msgpack.v1', {
  headers: { Authorization: `Bearer ${process.env.KITTA_API_KEY}` },
});
const pcm = await readFile('speech-16khz-mono.pcm');

ws.on('open', () =>
  ws.send(
    JSON.stringify({
      event: 'start',
      request: {
        model: 'kitta-asr-realtime-v1',
        format: 'pcm',
        sample_rate: 16000,
        language_hints: ['zh', 'en'],
      },
    }),
  ),
);

ws.on('message', (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.event === 'ready') {
    for (let offset = 0; offset < pcm.length; offset += 3200)
      ws.send(pcm.subarray(offset, offset + 3200));
    ws.send(JSON.stringify({ event: 'stop' }));
  }
  if (event.event === 'transcript_partial') console.log('临时：', event.text);
  if (event.event === 'transcript_final') console.log('最终：', event.text);
  if (event.event === 'usage') console.log('消耗：', event.credits_used);
  if (event.event === 'error') throw new Error(`${event.code}: ${event.message}`);
});

也可以不在握手中发送认证头，而把 API Key 作为连接后的第一条 JSON 消息：

{ "event": "auth", "token": "KITTA_API_KEY" }

不要把长期 API Key 放进浏览器代码。由你的后端使用 API Key 调用 POST https://realtime.kittaai.com/v2/stt/browser-tickets，并发送当前页面的 Origin 请求头。接口返回一次性、短时有效的 ticket、websocket_url 和 subprotocol。浏览器连接后将 ticket 作为第一条 auth 消息发送，然后按上面的顺序发送 start、二进制 PCM 音频和 stop。

事件与结算

服务端依次发送 authenticated、ready、transcript_partial、 transcript_final、usage 和 finish。只持久化 transcript_final 或 finish.transcript。

网关在开始会话前预留第一个计费分钟，在音频跨入下一分钟前继续预留。正常停止或网络断开时，网关都按实际收到的 PCM 字节计算时长、完成服务端结算并保存转写历史；提供商启动失败时会退回预留额度。余额不足返回 quota_exceeded。

如果不需要流式结果，请使用 HTTP 语音转文字接口。

实时语音转文字