ASR API リファレンス

Shisa ASR API は、単一の JSON リクエストで base64 エンコードされた音声をテキストに変換します。このページでは、エンドポイント、リクエストパラメータ、成功レスポンス、エラー処理について説明します。

エンドポイント

POST https://api.shisa.ai/asr/srt/audio_llm

完全なshsk: APIキーを含むベアラートークンで認証します:

Authorization: Bearer YOUR_API_KEY

リクエストボディは JSON で、サーバーはバイナリヘッダーから音声形式を自動検出します。

リクエストパラメータ

パラメータ	型	必須	説明
`audio`	string	必須	base64 エンコードされた音声データ（WAV、OGG、MP3、または FLAC）。
`language`	string	任意	言語コード（例: `"ja"`、`"en"`）。自動言語検出（LID）の場合は省略します。
`hotwords`	string[]	任意	ドメイン固有の用語の認識精度を高めるための単語/フレーズの配列。
`temperature`	float	任意	サンプリング温度。値を低くすると出力がより決定的になります。デフォルト: `0.0`。
`top_p`	float	任意	Nucleus サンプリングパラメータ。出力の多様性を制御します。デフォルト: `0.85`。
`frequency_penalty`	float	任意	頻出トークンにペナルティを課して繰り返しを減らします。デフォルト: `0.5`。
`repetition_penalty`	float	任意	トークンの繰り返しにペナルティを課します。`1.0` を超える値は繰り返しを抑制します。デフォルト: `1.05`。
`vad`	integer または string	任意	音声区間検出。`0`/`"off"`（デフォルト）、`1`/`"on"`、またはタイムスタンプ付きチャンクを返す`"segments"`。
`min_silence_gap`	integer	segmentsのみ	分割を作成する無音区間（ミリ秒）。デフォルト: `400`。
`segment_padding`	integer	segmentsのみ	セグメント端に追加するパディング（ミリ秒）。デフォルト: `100`、範囲: `0`〜`5000`。
`initial_segment_padding_ms`	integer	segmentsのみ	最初のセグメントの先頭プリロール（ミリ秒）。デフォルト: `1500`、範囲: `0`〜`5000`。
`speech_pad_ms`	integer	segmentsのみ	音声タイムスタンプのパディング（ミリ秒）。デフォルト: `200`。
`min_segment_duration`	float	segmentsのみ	マージ前の最小セグメント長（秒）。デフォルト: `1.5`。

注記

必須なのはaudioのみです。推奨されるトップレベルaudio形式では、言語は自動検出され、vadのデフォルトは"off"です。フィールド名はvadであり、vad_filterはサポートされません。

旧形式のリクエスト

messagesを使う旧形式では、vadのデフォルトは1です。OpenAI互換のmodelフィールドは互換性のため受け付けられますが無視され、ASRのバックエンドとモデルはデプロイ側で選択されます。

成功レスポンス

成功したリクエストは、文字起こし、検出または指定された言語、信頼度スコアを含む JSON オブジェクトを返します:

{
  "text": "こんにちは、シサAIです。",
  "language": "ja",
  "confidence": 0.98
}

フィールド	説明
`text`	音声から文字起こしされたテキスト。
`language`	検出または指定された言語コード。
`confidence`	0 から 1 までの文字起こし信頼度スコア。

セグメントレスポンス

vad: "segments"を指定すると、トップレベルのtextフィールドの代わりに、タイムスタンプ付きチャンクが返されます。

{
  "language": "ja",
  "confidence": 1.0,
  "segments": [
    {
      "start": 0.0,
      "end": 4.78,
      "text": "こんにちは、シサAIです。"
    }
  ]
}

segments[].startとsegments[].endは、パディングとマージを適用した後の出力音声チャンク境界（秒）です。

エラー処理

ルーターが生成するエラーには通常、context、数値のcode、name、文字列のerrorが含まれます。

{
  "context": ["authMiddleware"],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

エラーコード

ステータス	原因
`400`	JSON、base64/音声、言語、VAD設定、またはセッションIDが不正。ASRリクエスト本文の検証内容の多くはバックエンド依存です。
`401`	APIキーがない、または無効。
`403`	キーは有効だが、バッチASRへのアクセス権がない。
`404`	ルーティング先のASRサービス/プロバイダーが登録されていない。
`429`	APIキー全体の制限、ASR固有の制限、またはバックエンド容量に到達。バックオフして再試行してください。
`500`	ルーター内部または後処理の障害。
`502`	選択されたバックエンドにルーターが接続できない。
バックエンドのステータス	バックエンドエラーは、そのステータスとレスポンス本文のまま転送されます。

バックエンド固有の正確なフィールドやメッセージは、ルーター契約の一部ではありません。堅牢なエラー処理についてはエラーを参照してください。

次のステップ

クイックスタートで動作するリクエストを作成します。
サポートされている形式と言語選択については、音声と言語を参照してください。
利用がどのように課金されるかは料金を参照してください。

エンドポイント​

リクエストパラメータ​

成功レスポンス​

セグメントレスポンス​

エラー処理​

エラーコード​

次の​ステップ​