メインコンテンツまでスキップ

Realtime ASR（音声認識）— WebSocket

このページでは、Kotoba の Realtime ASR（speech-to-text） API（WebSocket）について説明します。

エンドポイント​

wss://api.kotobatech.ai/v1/realtime

認証​

サーバーサイド（推奨）​

APIキーを Bearer トークンとして利用します。

  • Authorization: Bearer <KOTOBA_API_KEY>

ブラウザ / クライアントサイド（APIキーを埋め込まないでください）​

ブラウザなどのクライアントサイド環境から接続したい場合は、まずサーバー側で有効期限付きの client secret を発行します。

POST https://api.kotobatech.ai/v1/realtime/transcription_sessions

その後、ブラウザから WebSocket のサブプロトコルを使って接続します（ブラウザは WebSocket に任意ヘッダーを付与できないため）。

  • sec-websocket-protocol: realtime, kotoba-insecure-api-key.<CLIENT_SECRET_VALUE>

Errors / error codes​

Realtime のエラーは JSON イベントとして配信され、以下を含みます。

  • type: "error"
  • error.code: KotobaErrorCode のいずれか（サイドバーの Errors schema を参照）

Realtime ASR でよく見る code:

  • invalid_api_key（HTTP 401 / error event）: APIキーが不正 / 未指定
  • rate_limit_exceeded / too_many_concurrent_requests（HTTP 429 / error event）: レート / 同時接続の制限
  • quota_exceeded: クレジット不足
  • invalid_parameters: session 設定 / event payload が不正
  • invalid_event: client event の type が不正
  • invalid_json: JSON が不正
  • payload_too_large: 音声 chunk が大きすぎる（小さく分割してください）

全体の流れ（概要）​

  1. WebSocket に接続します。
  2. サーバーイベント transcription_session.created を待ちます。
  3. 1回だけ transcription_session.update を送って session を設定します（音声形式、言語など）。
  4. input_audio_buffer.append で音声 chunk をストリーミングします。
  5. conversation.item.input_audio_transcription.delta（必要に応じて .completed）で書き起こし結果を受け取ります。
  6. 終了時に input_audio_buffer.commit を送ってから接続を閉じます。

Client → Server events​

transcription_session.update（必須）​

{
  "type": "transcription_session.update",
  "session": {
    "input_audio_format": "pcm16",
    "input_audio_sample_rate": 24000,
    "input_audio_number_of_channels": 1,
    "input_audio_transcription": {
      "language": "ja",
      "target_language": "ja"
    }
  }
}

input_audio_buffer.append​

base64 化した音声バイト列を送信します。

{
  "event_id": "optional_any_id_1",
  "type": "input_audio_buffer.append",
  "audio": "Base64EncodedAudioData"
}

input_audio_buffer.commit​

{
  "type": "input_audio_buffer.commit"
}

Server → Client events（代表例）​

  • transcription_session.created
  • transcription_session.updated
  • conversation.item.created
  • conversation.item.input_audio_transcription.delta
  • conversation.item.input_audio_transcription.completed
  • input_audio_buffer.committed
  • error

例: Node.js（サーバーサイドで Authorization ヘッダー）​

import WebSocket from "ws";

const ws = new WebSocket("wss://api.kotobatech.ai/v1/realtime", {
  headers: { Authorization: `Bearer ${process.env.KOTOBA_API_KEY}` },
});

ws.on("open", () => {
  // 本番では、session.created を受け取った後に transcription_session.update を送ってください。
  // 簡単なデモ用途であれば、ここで即送信しても動作します。
  ws.send(JSON.stringify({
    type: "transcription_session.update",
    session: {
      input_audio_format: "pcm16",
      input_audio_sample_rate: 24000,
      input_audio_number_of_channels: 1,
      input_audio_transcription: { language: "en", target_language: "en" }
    }
  }));
});

ws.on("message", (msg) => {
  console.log(JSON.parse(msg.toString()));
});

例: ブラウザ（client secret をサブプロトコルで利用）​

// CLIENT_SECRET_VALUE はサーバーサイドで発行してください:
// POST https://api.kotobatech.ai/v1/realtime/transcription_sessions
const ws = new WebSocket(
  "wss://api.kotobatech.ai/v1/realtime",
  ["realtime", "kotoba-insecure-api-key." + CLIENT_SECRET_VALUE]
);

ws.onmessage = (m) => console.log(JSON.parse(m.data));