音声認識(ASR)API
音声ファイルを入力として、音声認識(Automatic Speech Recognition)によるテキスト変換を行うAPIです。文字起こし、議事録作成、音声入力の後段処理などに利用できます。
API キーによる認証方法、エラーレスポンスの仕様は はじめに、レート制限の詳細は レート制限 をあわせてご確認ください。
エンドポイント
POST https://api.sarashina.ai/v1/audio/transcriptionsリクエストボディは multipart/form-data 形式で指定してください。cURL の -F オプションを使用すると、Content-Type は自動で設定されます。
サポートモデル
注意
本APIはストリーム形式のレスポンスには非対応です。
入力音声の仕様
file パラメーターには、以下の仕様を満たすWAVファイルを指定してください。
- 形式: RIFF/WAVE(WAV)
- エンコード: リニアPCM・16bit
- 対応言語: 日本語
- チャンネル: モノラル(1ch)
- サンプリングレート: 16,000 Hz
- 長さ: 0.1秒以上60秒以下
- リクエストサイズ: リクエスト全体で2MiB(2,097,152バイト)以下
仕様を満たさない音声ファイルを指定した場合、APIは 400 Bad Request を返却します。wavファイルとヘッダーなどを合わせたリクエスト全体のサイズが2MiBを超過した場合には 413 Payload Too Large を返却します。(参考: 60秒のモノラル・16kHz・16bit PCMのWAVファイルのサイズは約1.83MiBです。)
リクエストパラメータ
以下に定義されていないパラメータは無視されます。範囲外、サポート外の値を指定した場合、APIは 400 Bad Request を返却します。
| パラメータ | 型 | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
file | file | – | ✅ | 音声認識対象のWAVファイル。入力仕様は 入力音声の仕様 を参照してください。音声ファイルは1つのみ扱います。複数指定した場合は400 file field must contain only one file を返却します |
model | string | – | ✅ | 使用するモデル名(sarashina3.2-asr)を指定します。 |
response_format | string | json | – | レスポンス形式。json、text、verbose_json のいずれかを指定します。 |
keywords | string | – | – | 認識結果に含めやすくするキーワード。JSON文字列配列、または改行・カンマ区切りの文字列で指定します。最大200語、各語1〜64文字(Unicodeコードポイント単位)です。 |
biasing_threshold | number | 0.5 | – | キーワードを認識結果に反映する際の信頼度の閾値。keywords 指定時に有効で、値を低くするとキーワードを反映しやすくなります。0より大きく1以下の値を指定します。 |
keywords の指定形式
JSON文字列配列の場合は["Sarashina", "音声認識"]のように指定します。JSONとして解釈できない場合は、改行またはカンマ区切りの文字列として扱います。nullや123、[1,2]など、JSONとしては正しいものの文字列の配列ではない値を指定した場合は 400 Bad Request を返却します。空文字のキーワードは指定できません。
biasing_threshold の指定値
キーワードを認識結果に反映する際の信頼度の閾値です。省略した場合は0.5として扱われます。0以下、1より大きい値、数値として解釈できない値を指定した場合は 400 Bad Request を返却します。
利用例
リクエスト (cURL)
curl -H "Authorization: Bearer ${SARASHINA_API_KEY}" \
"https://api.sarashina.ai/v1/audio/transcriptions" \
-F "file=@audio.wav" \
-F "model=sarashina3.2-asr"レスポンス例
{
"text": "音声認識のサンプルです。"
}キーワードを指定したリクエスト例
固有名詞や専門用語をあらかじめ指定すると、それらの語句が認識結果に含まれやすくなります。
curl -H "Authorization: Bearer ${SARASHINA_API_KEY}" \
"https://api.sarashina.ai/v1/audio/transcriptions" \
-F "file=@audio.wav" \
-F "model=sarashina3.2-asr" \
-F 'keywords=["Sarashina", "音声認識"]' \
-F "biasing_threshold=0.25"レスポンス構造
音声認識(ASR)API のレスポンスには、音声認識の結果が含まれます。レスポンスには将来フィールドが追加される場合があります。未知のフィールドは無視してください。
response_format に text を指定した場合は、認識結果のテキストがそのままレスポンスボディとして返却されます。json と verbose_json の場合は、以下のJSONオブジェクトを返却します。
response_format | Content-Type |
|---|---|
json / verbose_json | application/json; charset=utf-8 |
text | text/plain; charset=utf-8 |
Transcription オブジェクト
| フィールド | 型 | 説明 | 対応する response_format |
|---|---|---|---|
text | string | 音声認識の結果テキスト。 | json / verbose_json |
language | string | 音声認識の対象となった言語。 | verbose_json |
duration | number | 入力音声の長さ(秒)。 | verbose_json |
レスポンスヘッダー
| ヘッダー | 説明 |
|---|---|
X-ASR-Model-Fingerprint | 音声認識に使用したモデルを識別する値。モデルの更新状況を判別する際の目安としてご利用ください。認識に使用したモデルの情報が取得できた場合に含まれます。 |
エラー
音声認識(ASR)API 固有の主なエラーは以下のとおりです。共通のエラーレスポンス形式については はじめに を参照してください。
| HTTP ステータスコード | 主な原因 |
|---|---|
400 Bad Request | 必須パラメータの未指定、サポート外のモデル・レスポンス形式、入力音声の仕様違反、keywords または biasing_threshold の制約違反 |
413 Payload Too Large | リクエスト全体のサイズが2MiBを超過 |