リアルタイム ASR(WebSocket)
リアルタイム ASR は、WebSocket 経由で音声をストリーミングし、発話中に文字起こしを返します。音声がまだ流れている間は暫定的な**部分(partial)結果を、発話ごとに確定的な確定(final)**結果を返します。ライブ字幕、会議の文字起こし、音声インターフェースに利用できます。
完全な音声ファイルを一度に文字起こしする場合は、代わりにバッチ ASR エンドポイントを使用してください。
エンドポイント
wss://api.shisa.ai/ws/asr/realtime
WebSocket ハンドシェイク時に、ASR 用のベアラートークンで認証します:
Authorization: Bearer YOUR_API_KEY
リアルタイム ASR は、通常どおり認可された有効な API キーに対して公開されています。キーが allowedServices 許可リストを使用している場合は shisa/asr-realtime を含めてください。deniedServices が指定されている場合はそちらが優先されます。既定の制限は API キーごとに同時 WebSocket セッション 3 です。個々のキーには別の制限が設定される場合があります。
リアルタイム ASR はバックエンドでの利用を想定しています。API キーはサーバーサイドに保管してください。ブラウザから自前のサーバーへ音声を中継し、そこから Shisa に接続します。
仕組み
Authorizationヘッダーを付けてエンドポイントに WebSocket を開きます。session.updateメッセージを 1 回送信し、音声形式と言語を設定します。session.createdを待ちます。- 生の音声を base64 の
input_audio.appendメッセージとしてストリーミングします(1 チャンクあたり 50〜250 ms が目安です)。 asr.partial_resultをライブの暫定テキストとして表示し、asr.final_resultが届いたら置き換えます。- 完了したら
session.closeを送信します。
音声の要件
生の PCM を送信してください。コンテナや圧縮は使用しません:
| プロパティ | 値 |
|---|---|
| エンコーディング | pcm_s16le(符号付き 16 ビットリトルエンディアン) |
| サンプルレート | 16000 Hz |
| チャンネル | 1(モノラル) |
| チャンク間隔 | 50〜250 ms 推奨(例では 100 ms) |
送信前にクライアント側でリサンプリングとダウンミックスを行ってください。WAV ヘッダー、Ogg、MP3、データ URL、浮動小数点 PCM、ステレオ音声は送信しないでください。
クライアントメッセージ
session.update
音声を送信する前に、session.update を必ず 1 回送信します。言語を固定するセッションが最もシンプルです:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "ja"
}
}
| フィールド | 必須 | 値 | 備考 |
|---|---|---|---|
input_audio_format | はい | pcm_s16le | 生の符号付き 16 ビットリトルエンディアン PCM。 |
sample_rate | はい | 16000 | 送信前に 16 kHz にリサンプリングします。 |
channels | はい | 1 | モノラルのみ。ステレオは先にダウンミックスします。 |
language | はい | ja、en、zh、auto | 言語が分かっている場合は固定します。自動言語識別には auto を使用します(後述)。 |
default_language | auto 時のみ | ja、en、zh | 検出が確信できない場合のフォールバック。 |
language_detection_mode | auto 時のみ | session、utterance | session は一度だけ検出、utterance はセグメントごとに検出(応用 — 後述)。 |
hotwords | いいえ | 文字列の配列 | 確定処理用のグローバル語彙。最大 50 項目(言語別の制限とは別)。 |
hotwords_by_language | いいえ | オブジェクトまたは null | 解決された言語ごとの確定処理用語彙。最大 5 キー、言語ごとに 100 項目、言語別項目の合計は 300 項目まで。 |
ホットワード
ホットワードは、製品名・専門用語・固有名詞など、独自の語彙に向けて確定処理を寄せます。設定は最初の session.update で 1 回だけ行い、その WebSocket セッション内のすべての発話に適用されます。変更する場合は、セッションを閉じて、新しい session.update で新しい WebSocket セッションを開始してください。一般的なコールセンター連携では、会話のターンごとではなく、顧客との 1 通話につき 1 つの WebSocket セッションを使用します。
固定言語のセッションが最もシンプルです:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "ja",
"hotwords": ["シーサー", "Shisa AI"]
}
}
ホットワードは asr.final_result にのみ作用します。ライブの asr.partial_result には未修正の表記が含まれる場合があります。確定結果が届いたら、表示していた部分テキストを置き換えてください。設定値がサービスイベントにエコーされることはありません。
制限
グローバルな hotwords リストと言語別リストには、それぞれ別の制限があります:
| 設定 | 制限 |
|---|---|
グローバル hotwords | 50 項目 |
| 言語キー | 5 |
| 言語ごとの項目数 | 100 |
| 言語別項目の合計 | 300 |
| 項目の長さ | 1〜100 Unicode 文字 |
各項目はそのリスト内で(大文字小文字を区別せず)一意である必要があり、1〜100 個の Unicode 文字(厳密には Unicode スカラー値)で、前後の空白や制御文字を含みません。サービスは無効な設定を切り詰め・正規化・削除・重複排除せず、拒否します。
言語別ホットワード(応用)
セッションは、単一の最初の session.update でグローバルなフォールバックホットワードと言語別リストを組み合わせることができます:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "auto",
"default_language": "en",
"language_detection_mode": "utterance",
"hotwords": ["global fallback"],
"hotwords_by_language": {
"ja": ["シーサー"],
"en": ["Shisa AI"],
"zh": ["狮萨"]
}
}
}
固定言語または LID の解決後、一致するマップ済みリストが非空であればそれが優先されます。一致するリストが存在しないか空の場合は hotwords にフォールバックします。キーは小文字 ASCII の 2 文字コードに完全一致させる必要があり、現在のデプロイでは正規の ja、en、zh を使用します。
hotwords_by_language の可用性は、選択されたデプロイによって異なる場合があります。利用できない場合、セッションは invalid_config エラーを返します。その場合は、グローバルな hotwords フィールドを使用するか、サポートにお問い合わせください。
メッセージサイズポリシー
ルーターは通常のクライアントメッセージを最大 65,536 バイトまで受け付けます。最初の session.update は、最上位の type が正確に session.update である場合に限り、最大 524,288 バイトまで許可されます。これは hotwords_by_language のような上限付きフィールドに対応するためです。上限は、組み立てられた WebSocket メッセージ全体の UTF-8 ワイヤバイト数に適用されます。
65,536 バイトを超えるその他のクライアントメッセージ、または 524,288 バイトを超えるクライアントメッセージは、1009 でクローズされ、転送されません。バックエンドからクライアントへのメッセージは引き続き 65,536 バイトに制限されます。オペレーターがより厳しい上限を設定する場合があるため、クライアントは引き続きコンパクトにシリアライズし、1009 を終端のセッションエラーとして扱ってください。
input_audio.append
音声チャンクを base64 エンコードした PCM としてストリーミングします:
{
"type": "input_audio.append",
"audio": "<base64 pcm_s16le bytes>"
}
session.close
完了したら、セッションを正常にクローズします:
{ "type": "session.close" }
言語識別(任意)
発話される言語が事前に分からない場合は、language: "auto" を設定します。2 つのモードがあります。
セッション検出は、開始直後に一度だけ言語を識別し、セッション全体でその言語を使用します:
{
"type": "session.update",
"session": {
"input_audio_format": "pcm_s16le",
"sample_rate": 16000,
"channels": 1,
"language": "auto",
"default_language": "en",
"language_detection_mode": "session"
}
}
セッションは session.language_detecting を発行し、続いて選択された language を含む session.language_detected を 1 回発行します。
発話単位の検出(language_detection_mode: "utterance")は、発話ごとに個別に言語を検出するため、複数言語が混在する音声に便利です。発話ごとに utterance.language_detected を発行します。このモードはバックエンドで有効化されている必要があり、有効でない場合、セッションは code: "invalid_config" の error を返します。その場合は、固定言語またはセッション検出にフォールバックしてください。
検出が確信を持って選択できない場合は default_language にフォールバックし、イベントには source: "default" と reason(例: no_speech、short_utterance、inconclusive、timeout、unsupported、queue_full、buffer_limit、session_close、shutdown、vad_error、lid_error)が含まれます。asr.final_result.text を常に権威ある結果として扱い、言語イベントだけを根拠に文字起こしを書き換えないでください。
ルーター管理の翻訳(任意)
ルーターは、空でない各asr.final_resultを非同期で翻訳できます。APIキーにはshisa/asr-realtimeとshisa/translateの両方へのアクセス権が必要です。翻訳はWebSocketセッションごとに明示的に有効化するまで無効です。
session.updateの後に次を送信します。
{
"type": "router.translation.update",
"id": "translate-en",
"enabled": true,
"target_langs": ["en"]
}
| フィールド | 必須 | 説明 |
|---|---|---|
enabled | 必須 | boolean。翻訳を無効にする場合はfalseを指定し、対象言語は省略します。 |
target_langs | 有効化時 | 一意かつ有効な言語コードを1〜3個指定します。 |
id | 任意 | 制御レスポンスにエコーされるクライアント相関ID。最大36文字。 |
context | 任意 | 各翻訳に渡す文脈。最大2,000 Unicodeコードポイント。 |
keywords | 任意 | 用語集の配列。最大20件、各項目100バイトまで。 |
更新が受け付けられると、次のレスポンスが返ります。
{
"type": "router.translation.updated",
"id": "translate-en",
"enabled": true,
"target_langs": ["en"]
}
設定が不正な場合はrouter.translation.errorが返ります。
{
"type": "router.translation.error",
"id": "translate-en",
"code": "too_many_target_langs",
"message": "At most 3 target languages are allowed"
}
設定エラーのコードには、invalid_json、invalid_message_type、invalid_id、id_too_long、invalid_enabled、missing_target_langs、too_many_target_langs、duplicate_target_lang、invalid_target_lang、context_too_long、too_many_keywords、keyword_too_long、translation_access_denied、translation_service_unavailableがあります。その他の予約済みrouter.*メッセージにはrouter.errorが返り、コードはunknown_router_messageまたはrouter_message_too_largeです。
ルーターは各確定結果の翻訳元言語を、(1) asr.final_result.language、(2) 最新のsession.language_detected、(3) session.update.session.languageで指定した固定言語、の優先順で解決します。単独のutterance.language_detectedイベントは翻訳元言語として直接利用しません。確定結果の到着時に有効な言語がない場合、その対象言語にはcode: "source_language_unknown"のtranslation.errorが返ります。
サービスイベント
すべてのイベントは JSON テキストメッセージです。セッション作成後、ASRバックエンドのイベントにはsession_idと単調増加するseqが含まれます。ルーターが生成するrouter.*およびtranslation.*イベントにはこれらのフィールドがないため、翻訳結果と翻訳エラーはsource_result_idでASR確定結果に関連付けてください。
session.created
セッションが受け入れられ、音声の送信を開始できます:
{
"type": "session.created",
"session_id": "asr_sess_...",
"seq": 1,
"format": { "encoding": "pcm_s16le", "sample_rate": 16000, "channels": 1 }
}
発話境界
speech_started と speech_stopped は、各発話の音声区間検出(VAD)の境界を示します:
{
"type": "speech_started",
"session_id": "asr_sess_...",
"seq": 4,
"utterance_id": "utt_0001",
"audio_start_ms": 420
}
{
"type": "speech_stopped",
"session_id": "asr_sess_...",
"seq": 9,
"utterance_id": "utt_0001",
"audio_start_ms": 420,
"audio_end_ms": 2860,
"reason": "vad_endpoint"
}
一般的な停止理由は vad_endpoint、max_buffer、session_close です。
asr.partial_result
進行中の発話の暫定テキストです。utterance_id ごとに最新の部分結果を表示し、前のものを置き換えてください。すべての部分結果を履歴に追加しないでください:
{
"type": "asr.partial_result",
"session_id": "asr_sess_...",
"seq": 7,
"utterance_id": "utt_0001",
"result_id": "utt_0001:p3",
"text": "今日の会議は3時から",
"is_final": false,
"audio_start_ms": 420,
"audio_end_ms": 2260
}
asr.final_result
発話の確定テキストです。表示していた暫定の部分結果を破棄するには replaces を使用します:
{
"type": "asr.final_result",
"session_id": "asr_sess_...",
"seq": 12,
"utterance_id": "utt_0001",
"result_id": "utt_0001:final",
"replaces": ["utt_0001:p1", "utt_0001:p2", "utt_0001:p3"],
"replaces_audio_range_ms": [420, 2860],
"text": "今日の会議は3時からです。",
"language": "ja",
"is_final": true,
"audio_start_ms": 420,
"audio_end_ms": 2860
}
確定結果は非同期であり、後続の音声イベントより遅れて届くことがあります。非常に長い発話は、continuation_of、overlap_mode、leading_context_ms、payload_audio_range_ms を持つ継続確定結果に分割される場合があります。audio_start_ms/audio_end_ms は論理的な発話範囲を示し、payload_audio_range_ms は確定 ASR に送られた重複コンテキストを含み、leading_context_ms は audio_start_ms より前のコンテキスト長です。表示は論理的な範囲のみとしてください。
translation.final_result
翻訳が有効な場合、ルーターは翻訳可能なASR確定結果ごとに、対象言語ごとの結果を1件発行します。
{
"type": "translation.final_result",
"utterance_id": "utt_0001",
"source_result_id": "utt_0001:final",
"source_text": "今日の会議は3時からです。",
"text": "Today's meeting starts at 3 o'clock.",
"source_lang": "ja",
"target_lang": "en",
"model": "shisa-v2.1-unphi4-14b"
}
source_result_idで示される正確なASR確定結果に翻訳を関連付けてください。翻訳は非同期であり、複数の対象言語の結果は任意の順序で到着します。modelはバックエンドがレスポンスで報告したモデルIDであり、翻訳リクエストに使われるデフォルトエイリアスshisa-ai/chottoと異なる場合があります。
translation.error
対象言語の翻訳に失敗した場合、ASRセッションを閉じずに対象別のエラーが発行されます。
{
"type": "translation.error",
"code": "source_language_unknown",
"message": "Cannot translate ASR final result before source language is known",
"utterance_id": "utt_0001",
"source_result_id": "utt_0001:final",
"target_lang": "en"
}
その他の一般的なコードには、same_source_target_lang、translation_access_denied、translation_service_unavailable、translation_rate_limited、translation_rate_limiter_unavailable、translation_failed、source_text_too_longがあります。空の確定テキストは翻訳されず、翻訳結果も翻訳エラーも発行されません。
session.usage
利用量は累積です。課金は最新のイベントを使用します。billable_duration は整数秒です。最上位の model は会計/デバッグに使用される、デプロイが選択した確定処理モデルです。クライアントがリアルタイムの部分結果エンジンを選択することはありません:
{
"type": "session.usage",
"session_id": "asr_sess_...",
"seq": 20,
"final": true,
"model": "shisa-ai/shisa-asr",
"usage": {
"input_duration": 18.3036875,
"billable_duration": 19,
"input_bytes": 585718,
"sample_rate": 16000,
"channels": 1,
"utterance_count": 3,
"final_result_count": 3,
"final_error_count": 0,
"final_no_speech_count": 0,
"partial_result_count": 17,
"error_count": 0,
"status": "completed",
"final": true
}
}
エラーへの対処
正常なセッションは、エラーイベントを出すことなく接続・ストリーミング・クローズを完了します。対応が必要な場合、API は明確なコードを返し、可能な限り次の行動を示します。
エラーは 2 つのタイミングで発生します。接続の確立時は error オブジェクトを含む HTTP レスポンスとして、WebSocket セッション中は type: "error" の JSON イベントとして返されます。
接続が拒否された場合
アップグレードが受け入れられない場合、WebSocket は作成されません。応答は通常の HTTP エラーです:
{
"error": {
"code": "service_access_denied",
"message": "Service access denied"
}
}
よくある原因は簡単に解決できます:
| HTTP | コード | 対処 |
|---|---|---|
401 | auth_token_required | Authorization: Bearer <key> ヘッダーを送信します。 |
401 | invalid_token_format | プレフィックスを含む完全な shsk:... キーを使用します。 |
401 | invalid_token | キーが最新かつ有効であることを確認します。認証を参照してください。 |
401 | legacy_api_key_rejected | レガシーキーを現在の API キーに置き換えます。 |
403 | service_access_denied | キーの allowedServices に shisa/asr-realtime を追加するか、deniedServices から削除します。 |
403 | ws_origin_denied | 許可されたオリジンから接続するか、サーバーサイドクライアントでは Origin ヘッダーを省略します。 |
429 | rate_limited、service_rate_limited | 速度を落とし、バックオフ付きで再試行します。レート制限を参照してください。 |
429 | ws_connection_limit_exceeded | アイドル状態のセッションを閉じるか、1 つが終了するのを待ちます。個々のキーには別の制限が設定される場合があります。エラー本文には適用される limit と現在の active 数が含まれます。 |
まれに、サービスが一時的に新しいセッションを受け付けられないことがあります(容量の変更やメンテナンス時など)。これは一時的な状態で 503 を返します。バックオフ付きで再試行してください。リクエストが原因ではありません。
一時的なサービスコード
| HTTP | コード | 意味 |
|---|---|---|
503 | auth_unavailable | API キーの検証が一時的に利用できません。 |
503 | rate_limiter_unavailable、service_rate_limiter_unavailable | レート制限の確認が一時的に利用できません。 |
503 | ws_connection_quota_unavailable | 接続クォータの追跡が一時的に利用できません。 |
503 | backends_at_capacity、backend_unavailable | 現在リアルタイム ASR の容量がありません。 |
503 | websocket_draining | サービスが計画的な再起動中で、新規セッションを受け付けていません。 |
503 | service_rate_limit_policy_invalid | キーのレート制限設定にサービス側での更新が必要です。変更なしの再試行では解決しないため、サポートにお問い合わせください。 |
セッション中
アップグレード後、バックエンドは JSON の error イベントを転送します。ほとんどは単一の発話に対するもので、セッションは継続できます。セッションが終了するのは fatal: true の場合のみです。バックエンドはコードを追加する可能性があるため、未知の code 値も防御的に処理してください:
{
"type": "error",
"code": "finalization_failed",
"message": "Finalization failed",
"fatal": false,
"session_id": "asr_sess_...",
"seq": 18,
"utterance_id": "utt_0002"
}
| コード | 対処 |
|---|---|
invalid_json、invalid_state | メッセージの順序を確認します。音声の前に session.update を正確に 1 回送信し、既知のメッセージ種別を使用します。 |
invalid_audio | 16 kHz モノラルの生 pcm_s16le を送信します。ヘッダーや圧縮音声は送信しないでください。 |
invalid_config | 選択した言語/LID モードを確認し、ホットワードがドキュメント記載の件数・長さ・一意性・文字規則を満たしているか検証します。デプロイで hotwords_by_language が利用できない場合は、グローバルな hotwords を使用するか、サポートにお問い合わせください。 |
frame_too_large | 個々のメッセージまたは音声チャンクを小さくします。 |
limit_exceeded | セッション、バッファ、認識バックログ、またはキューの上限に達しました。必要に応じて現在のセッションを停止またはクローズし、バックオフ付きで再試行します。解決しない場合はサポートにお問い合わせください。 |
finalization_timeout、finalization_cancelled、finalization_failed | その発話を再試行します。繰り返す場合はサポートにお問い合わせください。 |
service_error | 一時的なサービス側の問題です。再試行し、解決しない場合はサポートにお問い合わせください。 |
fatal: true | このイベントの後にセッションが終了します。再接続して再開してください。 |
接続クローズの動作
- 接続が拒否された場合は通常の HTTP 応答です。WebSocket は作成されません。
- 言語別ホットワードの設定が無効な場合、
invalid_configイベントに続いてクローズ1008が発生します。 - 65,536 バイトを超えるクライアントメッセージは
1009でクローズされます。最初の最上位session.updateは最大 524,288 バイトまで使用できます。 - 致命的なセッション内エラーの後にはクローズフレームが続きます。
- クローズコードと理由をログに記録し、一時的な容量・バックエンド・ネットワークの状態に対してはバックオフ付きで再接続してください。
文字起こしの取り扱い
- 暫定テキストは
utterance_idをキーとして保持します。 - より新しい
asr.partial_resultが届いたら、アクティブな部分結果を置き換えます。 asr.final_resultを受け取ったら、replacesの ID を削除し、確定テキストを確定します。- 翻訳は
source_result_idで関連付け、対象言語の結果順序を前提にしないでください。 - 空の確定テキストは表示上は無視します(診断用には保持します)。
session.usageを文字起こしテキストとして表示しないでください。
次のステップ
- 完全なファイルの文字起こしはバッチ ASR エンドポイントで行えます。
- サポートされている形式と言語は音声と言語を参照してください。
- 利用がどのように課金されるかは料金を参照してください。