本ガイドでは、Fun-ASR リアルタイム音声認識の Python ソフトウェア開発キット(SDK)のパラメーターおよびインターフェイスについて説明します。
ユーザーガイド:モデルの概要および選択に関するガイダンスについては、「リアルタイム音声認識 — Fun-ASR/Gummy/Paraformer」をご参照ください。
前提条件
サービスを有効化し、API キーを作成済みである必要があります。セキュリティリスクを防止するため、API キーはコード内にハードコーディングせず、環境変数として設定してください。
モデル一覧
国際
国際デプロイモードでは、エンドポイントおよびデータストレージが シンガポールリージョンに配置されます。モデル推論の計算リソースは、中国本土を除くグローバルに動的にスケジュールされます。
モデル | バージョン | 単価 | 無料クォータ (注) |
fun-asr-realtime 現在:fun-asr-realtime-2025-11-07 | Stable | $0.00009/秒 | 36,000 秒(10 時間) 有効期限:90 日間 |
fun-asr-realtime-2025-11-07 | Snapshot |
対応言語:標準語、広東語、呉語、閩南語、客家語、贛語、湘語、晋語。また、中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、香港・台湾地域の標準語アクセント(河南省、陝西省、湖北省、四川省、重慶市、雲南省、貴州省、広東省、広西チワン族自治区、河北省、天津市、山東省、安徽省、南京市、江蘇省、杭州市、甘粛省、寧夏回族自治区を含む)にも対応。さらに英語および日本語も対応。
対応サンプルレート:16 kHz
対応音声フォーマット:pcm、wav、mp3、opus、speex、aac、amr
中国本土
中国本土デプロイモードでは、エンドポイントおよびデータストレージが 中国 (北京) リージョンに配置されます。モデル推論の計算リソースは中国本土に限定されます。
モデル | バージョン | 単価 | 無料クォータ (注) |
fun-asr-realtime 現在:fun-asr-realtime-2025-11-07 | Stable | $0.000047/秒 | 無料クォータなし |
fun-asr-realtime-2026-02-28 | Snapshot | ||
fun-asr-realtime-2025-11-07 | Snapshot | ||
fun-asr-realtime-2025-09-15 | |||
fun-asr-flash-8k-realtime 現在:fun-asr-flash-8k-realtime-2026-01-28 | Stable | $0.000032/秒 | |
fun-asr-flash-8k-realtime-2026-01-28 | Snapshot |
対応言語:
fun-asr-realtime、fun-asr-realtime-2026-02-28、fun-asr-realtime-2025-11-07:中国語(標準語、広東語、呉語、閩南語、客家語、贛語、湘語、晋語。また、中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、香港・台湾など地域の標準語アクセント(河南省、陝西省、湖北省、四川省、重慶市、雲南省、貴州省、広東省、広西チワン族自治区、河北省、天津市、山東省、安徽省、南京市、江蘇省、杭州市、甘粛省、寧夏回族自治区を含む)にも対応)、英語、日本語。
fun-asr-realtime-2025-09-15:中国語(標準語)、英語
対応サンプルレート:16 kHz
対応サンプルレート:
fun-asr-flash-8k-realtime および fun-asr-flash-8k-realtime-2026-01-28:8 kHz
その他のすべてのモデル:16 kHz
対応音声フォーマット:pcm、wav、mp3、opus、speex、aac、amr
はじめに
Recognition クラスは、非ストリーミング呼び出しおよび双方向ストリーミング呼び出しをサポートしています。ご利用のユースケースに応じて、適切な方法を選択してください。
非ストリーミング呼び出し:ローカルファイルを認識し、完全な認識結果を一度に返します。この方法は、事前に録音された音声を処理する場合に適しています。
双方向ストリーミング呼び出し:音声ストリームを認識し、リアルタイムで結果を返します。音声ストリームは、外部デバイス(例:マイク)またはローカルファイルから取得できます。この方法は、即時フィードバックが必要なシナリオに最適です。
非ストリーミング呼び出し
この方法では、単一の音声ファイルに対してリアルタイム音声テキスト変換タスクを送信します。呼び出しは同期的であり、認識結果が返されるまで現在のスレッドをブロックします。
Recognition クラスのインスタンスを作成し、リクエストパラメーターを設定した後、call メソッドを呼び出して認識結果(RecognitionResult)を取得します。
双方向ストリーミング呼び出し
この方法では、リアルタイム音声テキスト変換タスクを送信し、コールバックを通じてストリーミング結果を返します。
ストリーミング音声認識を開始
Recognition クラスのインスタンスを作成し、リクエストパラメーターおよびコールバック(RecognitionCallback)を設定した後、
startメソッドを呼び出してストリーミング音声認識を開始します。音声データをストリーミング
Recognition クラスの
send_audio_frameメソッドを継続的に呼び出して、ローカルファイルまたはマイクなどのデバイスから読み取ったバイナリ音声ストリームのチャンクをサーバーに送信します。音声送信中に、サーバーはコールバック(RecognitionCallback)の
on_eventメソッドを通じて、リアルタイムで認識結果をクライアントに返します。推奨される音声チャンクサイズは約 100 ms(データサイズは 1 KB ~ 16 KB)です。
認識を停止
Recognition クラスの
stopメソッドを呼び出して音声認識を停止します。このメソッドは、RecognitionCallback の
on_completeまたはon_errorメソッドがトリガーされるまで、現在のスレッドをブロックします。
リクエストパラメーター
Recognition クラス のコンストラクター(__init__)でリクエストパラメーターを設定します。
パラメーター | 型 | デフォルト値 | 必須 | 説明 |
model | str | - | はい | リアルタイム音声認識に使用するモデルです。 |
sample_rate | int | - | はい | 音声のサンプルレート(Hz 単位)です。
|
format | str | - | はい | 音声フォーマットです。 対応フォーマット:pcm、wav、mp3、opus、speex、aac、amr。 重要 opus/speex:Ogg カプセル化が必要です。 wav:PCM エンコーディングが必要です。 amr:AMR-NB タイプのみサポートされます。 |
semantic_punctuation_enabled | bool | False | いいえ | 意味的句読点機能を有効または無効にします。デフォルトは
意味的句読点は精度が高く、会議の文字起こしなどのユースケースに適しています。VAD による分割はレイテンシーが低く、インタラクティブなシナリオに最適です。 異なるシナリオに応じて、 |
max_sentence_silence | int | 1300 | いいえ | VAD を使用した文分割における、文の終了を判定するサイレンス持続時間のしきい値(ミリ秒単位)です。 音声セグメント後のサイレンスがこのしきい値を超えると、システムは文の終了と判断します。 有効範囲:200 ~ 6000。デフォルト値:1300。 このパラメーターは、 |
multi_threshold_mode_enabled | bool | False | いいえ |
このパラメーターは、 |
punctuation_prediction_enabled | bool | True | いいえ | 認識結果への自動句読点挿入を有効にします。
|
heartbeat | bool | False | いいえ | サーバーとの持続的接続を維持するかどうかを制御します。
SDK バージョン 1.23.1 以降が必要です。 |
language_hints | list[str] | - | いいえ | 認識対象の言語コードを指定します。言語が不明な場合は、このパラメーターを省略すると、モデルが自動的に言語を判別します。 リスト内の最初の値のみが読み込まれ、それ以降の値は無視されます。 各モデルでサポートされる言語コードは以下のとおりです。
|
speech_noise_threshold | float | - | いいえ | VAD の感度しきい値を設定し、音声とノイズを区別します。 有効範囲:-1.0 ~ 1.0。 値の設定に関するガイドライン:
重要 これは高度な設定パラメーターです。調整によって認識結果に大きな影響を与える可能性があるため、以下の点に注意してください。
|
callback | RecognitionCallback | - | いいえ |
主要インターフェイス
Recognition クラス
Recognition クラスは、from dashscope.audio.asr import * を使用してインポートします。
メンバーメソッド | メソッドシグネチャー | 説明 |
call | | ローカルファイルに対する非ストリーミング認識を実行します。このメソッドは、音声ファイル全体の処理が完了するまで現在のスレッドをブロックします。ファイルには読み取り権限が必要です。 このメソッドは |
start | | コールバックを使用したリアルタイムストリーミング認識タスクを開始します。 このメソッドは非ブロッキングであり、 |
send_audio_frame | | 音声フレームを送信します。最適なパフォーマンスを得るには、各音声フレームの長さを約 100 ms、サイズを 1 KB ~ 16 KB にすることを推奨します。 RecognitionCallback インターフェイス の |
stop | | 音声認識タスクを停止します。このメソッドは、受信したすべての音声の処理が完了するまで現在のスレッドをブロックします。 |
get_last_request_id | | リクエスト ID を返します。このメソッドは、 |
get_first_package_delay | | 初回パケット遅延(first-packet latency)を返します。これは、最初の音声フレームを送信してから最初の認識結果を受信するまでの時間を示します。このメソッドはタスク完了後に利用可能です。 |
get_last_package_delay | | 最終パケット遅延(last-packet latency)とは、 |
get_response | | サーバーから最後に受信したメッセージを返します。 |
コールバックインターフェイス(RecognitionCallback)
双方向ストリーミング呼び出しでは、サーバーがコールバックを使用して、重要な処理情報およびデータをクライアントに返します。サーバーからの応答を処理するには、コールバックメソッドを実装する必要があります。
メソッド | パラメーター | 戻り値 | 説明 |
| なし | なし | サーバーへの接続が確立されたときに呼び出されます。 |
|
| なし | サービスが認識結果を返したときに呼び出されます。 |
| なし | なし | すべての認識結果が返された後に呼び出されます。 |
|
| なし | エラーが発生したときに呼び出されます。 |
| なし | なし | サーバーへの接続が閉じられたときに呼び出されます。 |
応答
認識結果(RecognitionResult)
RecognitionResult は、双方向ストリーミング呼び出しまたは非ストリーミング呼び出しの認識結果を表します。
メンバーメソッド | メソッドシグネチャー | 説明 |
get_sentence | | 現在認識中の文およびそのタイムスタンプ情報を返します。コールバックでは、単一の文に対して 詳細については、「文情報(Sentence)」をご参照ください。 |
get_request_id | | リクエスト ID を返します。 |
is_sentence_end | | 指定された文が終了しているかどうかを確認します。 |
文(Sentence)
Sentence クラスには、以下のメンバーが含まれます。
パラメーター | 型 | 説明 |
begin_time | int | 文の開始時刻(ミリ秒単位)です。 |
end_time | int | 文の終了時刻(ミリ秒単位)です。 |
text | str | 認識されたテキストです。 |
words | Word タイムスタンプ情報(Word) オブジェクトのリストです。 | 文内の各単語のタイムスタンプ情報です。 |
単語タイムスタンプ(Word)
Word クラスには、以下のメンバーが含まれます。
パラメーター | 型 | 説明 |
begin_time | int | 単語の開始時刻(ミリ秒単位)です。 |
end_time | int | 単語の終了時刻(ミリ秒単位)です。 |
text | str | 単語です。 |
punctuation | str | 句読点です。 |
エラーコード
エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、「開発者グループ」に参加し、調査のためにリクエスト ID を提供してください。
よくある質問
機能
Q:サイレンス時に持続的接続を維持するにはどうすればよいですか?
heartbeat リクエストパラメーターを true に設定し、サーバーに継続的にサイレンス音声を送信してください。
サイレンス音声とは、音声が含まれない音声データです。Audacity や Adobe Audition などの音声編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して生成できます。
Q:音声を対応フォーマットに変換するにはどうすればよいですか?
FFmpeg ツール を使用できます。詳細については、FFmpeg 公式サイトをご参照ください。
# 基本的な変換コマンド(汎用テンプレート)
# -i:入力ファイルパスを指定します。例:audio.wav
# -c:a:オーディオエンコーダーを指定します。例:aac、libmp3lame、pcm_s16le
# -b:a:ビットレートを指定します(音質を制御)。例:192k、320k
# -ar:サンプルレートを指定します。例:44100(CD)、48000、16000
# -ac:チャンネル数を指定します。例:1(モノラル)、2(ステレオ)
# -y:出力ファイルが既に存在する場合に上書きします(値は不要)。
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bit_rate -ar sample_rate -ac number_of_channels output.ext
# 例:WAV → MP3(オリジナル品質を維持)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# 例:MP3 → WAV(標準 16 ビット PCM 形式)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# 例:M4A → AAC(Apple 音声の抽出/変換)
ffmpeg -i input.m4a -c:a copy output.aac # 再エンコーディングなしで直接抽出
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac # 品質向上のため再エンコーディング
# 例:FLAC(ロスレス)→ Opus(高圧縮)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opusQ:ローカルファイルを認識するにはどうすればよいですか?
ローカルファイルを認識するには、以下の 2 つの方法があります。
ローカルファイルパスを直接渡す:この方法では、ファイル全体の処理が完了した後に完全な認識結果が返されるため、リアルタイムアプリケーションには不向きです。
この方法を使用するには、Recognition クラス の
callメソッドにファイルパスを渡します。詳細については、「非ストリーミング呼び出し」をご参照ください。ローカルファイルをバイナリストリームに変換する:この方法では、ファイルを処理し、認識結果をストリームとして返すため、リアルタイムアプリケーションに適しています。
詳細については、「双方向ストリーミング呼び出し」をご参照ください。Recognition クラス の
send_audio_frameメソッドを使用して、バイナリストリームをサーバーに送信し、認識を行います。
トラブルシューティング
Q:認識結果が返されないのはなぜですか?
音声フォーマット(
format)およびサンプルレート(sampleRate/sample_rate)が、実際の音声ファイルのプロパティと一致し、かつパラメーター制約を満たしているかを確認してください。一般的なエラー例:音声ファイルの拡張子が .wav ですが、実際には MP3 形式であり、
formatリクエストパラメーターが誤ってwavに設定されています。音声のサンプルレートが 3600 Hz ですが、
sampleRate/sample_rateリクエストパラメーターが誤って 48000 に設定されています。
音声コンテナ、エンコーディング、サンプルレート、チャンネル数に関する情報を取得するには、ffprobe ツールを使用します。
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx