Fun-ASR 音声ファイル認識 Java SDK のパラメーターおよびインターフェイスの詳細です。
ユーザーガイド: モデルと選択に関する推奨事項については、「音声ファイル認識 — Fun-ASR/Paraformer」をご参照ください。
前提条件
Model Studio を有効化し、API キーを作成済みである必要があります。環境変数としてエクスポートする(ハードコーディングしない)ことで、セキュリティリスクを防止してください。
説明一時的なアクセスや、機密データへのアクセス/削除など高リスク操作を厳密に制御する場合は、一時認証トークンをご利用ください。
長期使用の API キーと比較して、一時トークンはより安全(有効期間:60 秒)であり、API キーの漏洩リスクを低減します。
一時トークンを利用するには、コード内の認証に使用する API キーを、一時認証トークンに置き換えてください。
DashScope SDK の最新版をインストールしてください。
モデルの可用性
国際
国際デプロイモードでは、エンドポイントおよびデータストレージが シンガポールリージョンに配置されます。モデル推論の計算リソースは、中国本土を除く世界中で動的にスケジュールされます。
モデル | バージョン | 単価 | 無料クォータ (注) |
fun-asr 現在は fun-asr-2025-11-07 です。 | Stable | $0.000035/秒 | 36,000 秒(10 時間) 有効期間:90 日 |
fun-asr-2025-11-07 fun-asr-2025-08-25 と比較して、遠距離 VAD の精度が向上しています | Snapshot | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl 現在は fun-asr-mtl-2025-08-25 です。 | Stable | ||
fun-asr-mtl-2025-08-25 | Snapshot |
対応言語:
fun-asr および fun-asr-2025-11-07:標準中国語、広東語、呉語、閩南語、客家語、贛語、湘語、晋語。また、中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、香港・台湾地域(河南省、陝西省、湖北省、四川省、重慶市、雲南省、貴州省、広東省、広西チワン族自治区、河北省、天津市、山東省、安徽省、南京市、江蘇省、杭州市、甘粛省、寧夏回族自治区を含む)の標準中国語アクセントにも対応。さらに英語および日本語もサポートします。
fun-asr-2025-08-25:標準中国語および英語。
fun-asr-mtl および fun-asr-mtl-2025-08-25:標準中国語、広東語、英語、日本語、韓国語、ベトナム語、インドネシア語、タイ語、マレー語、フィリピン語、アラビア語、ヒンディー語、ブルガリア語、クロアチア語、チェコ語、デンマーク語、オランダ語、エストニア語、フィンランド語、ギリシャ語、ハンガリー語、アイルランド語、ラトビア語、リトアニア語、マルタ語、ポーランド語、ポルトガル語、ルーマニア語、スロバキア語、スロベニア語、スウェーデン語。
対応サンプルレート: 任意
対応音声フォーマット: aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv
中国本土
中国本土デプロイモードでは、エンドポイントおよびデータストレージが 北京リージョンに配置されます。モデル推論の計算リソースは中国本土内に限定されます。
モデル | バージョン | 単価 | 無料クォータ (注) |
fun-asr 現在は fun-asr-2025-11-07 です。 | Stable | $0.000032 / 秒 | 無料クォータはありません |
fun-asr-2025-11-07 fun-asr-2025-08-25 と比較して、遠距離 VAD の精度が向上しています | Snapshot | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl 現在は fun-asr-mtl-2025-08-25 です。 | Stable | ||
fun-asr-mtl-2025-08-25 | Snapshot |
対応言語:
fun-asr および fun-asr-2025-11-07:標準中国語、広東語、呉語、閩南語、客家語、贛語、湘語、晋語。また、中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、香港・台湾地域(河南省、陝西省、湖北省、四川省、重慶市、雲南省、貴州省、広東省、広西チワン族自治区、河北省、天津市、山東省、安徽省、南京市、江蘇省、杭州市、甘粛省、寧夏回族自治区を含む)の標準中国語アクセントにも対応。さらに英語および日本語もサポートします。
fun-asr-2025-08-25:標準中国語および英語。
fun-asr-mtl および fun-asr-mtl-2025-08-25:標準中国語、広東語、英語、日本語、韓国語、ベトナム語、インドネシア語、タイ語、マレー語、フィリピン語、アラビア語、ヒンディー語、ブルガリア語、クロアチア語、チェコ語、デンマーク語、オランダ語、エストニア語、フィンランド語、ギリシャ語、ハンガリー語、アイルランド語、ラトビア語、リトアニア語、マルタ語、ポーランド語、ポルトガル語、ルーマニア語、スロバキア語、スロベニア語、スウェーデン語。
対応サンプルレート: 任意
対応音声フォーマット: aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv
制限事項
入力は、パブリックネットワークからアクセス可能なファイル URL(HTTP/HTTPS)である必要があります。例: https://your-domain.com/file.mp3。ローカルファイルおよび Base64 エンコーディングされた音声はサポートされていません。
SDKを使用してOSSに保存されているファイルにアクセスする場合、oss://プレフィックスを持つ一時URLは使用できません。
RESTful API を使用して OSS に格納されているファイルにアクセスする場合、oss:// プレフィックスが付いた一時 URL を使用できます:
一時 URL の有効期間は 48 時間であり、有効期限が切れた後は使用できません。本番環境では使用しないでください。
アップロード認証情報取得 API の呼び出し上限は 100 QPS であり、スケーリングはサポートされていません。本番環境、高同時実行数シナリオ、ストレステストシナリオでは使用しないでください。
本番環境では、ファイルの長期的な可用性を確保し、レート制限の問題を回避するために、OSS などの安定したストレージサービスをご利用ください。
URL は fileUrls パラメーターで指定します。1 回のリクエストで最大 100 個の URL を指定できます。
対応音声フォーマット
aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv重要音声および動画フォーマットは多種多様であり、すべてを網羅的にテストすることは技術的に困難です。この API では、すべてのフォーマットが正しく認識されることを保証できません。ご自身のファイルでテストを行い、期待通りの音声認識結果が得られることを確認してください。
音声サンプルレート: 任意
音声ファイルサイズおよび再生時間
最大ファイルサイズは 2 GB、最大再生時間は 12 時間です。これらの制限を超えるファイルの場合は、アップロード前に分割または圧縮を行ってください。ファイル前処理のベストプラクティスについては、「ファイル転写効率を向上させるための動画ファイル前処理(音声ファイル認識シナリオ向け)」をご参照ください。
バッチ処理対象の音声ファイル数
1 回のリクエストで最大 100 個のファイル URL を指定できます。
認識可能な言語: fun-asr は中国語および英語をサポートします。fun-asr-mtl-2025-08-25 は中国語、広東語、英語、日本語、タイ語、ベトナム語、インドネシア語をサポートします。
クイックスタート
コアクラス(Transcription)は、タスクを非同期で送信するインターフェイス、タスク完了を同期で待機するインターフェイス、およびタスク結果を非同期で照会するインターフェイスを提供します。以下の 2 つの方法で音声ファイル認識を実行できます:
非同期送信+同期待機:タスクを送信し、タスクが完了するまで現在のスレッドをブロックして認識結果を取得します。
非同期送信+非同期照会:タスクを送信した後、必要に応じて照会インターフェイスを呼び出してタスク結果を取得します。
非同期送信+同期待機
リクエストパラメーターを設定します。
コアクラス(Transcription)のインスタンスを作成します。
コアクラス(Transcription)の
asyncCallメソッドを呼び出して、タスクを非同期で送信します。説明タスクは送信後に
PENDINGステータスになります。キュー待ち時間(通常数分)はキュー長およびファイル再生時間によって異なります。処理が開始されると、音声認識は大幅に高速化されます。認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限が切れます。有効期限が切れた後は、タスクを照会できなくなります。
コアクラス(Transcription)の
waitメソッドを呼び出して、タスク完了を同期で待機します。タスクステータスには
PENDING、RUNNING、SUCCEEDED、FAILEDがあります。waitインターフェイスはPENDING/RUNNINGの状態でブロックし、タスクがSUCCEEDEDまたはFAILEDになった時点でブロックを解除し、タスク実行結果を返します。waitは タスク実行結果(TranscriptionResult) を返します。
非同期送信+非同期照会
リクエストパラメーターを設定します。
コアクラス(Transcription)のインスタンスを作成します。
コアクラス(Transcription)の
asyncCallメソッドを呼び出して、タスクを非同期で送信します。説明タスクは送信後に
PENDINGステータスになります。キュー待ち時間(通常数分)はキュー長およびファイル再生時間によって異なります。処理が開始されると、音声認識は大幅に高速化されます。認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限が切れます。有効期限が切れた後は、タスクを照会できなくなります。
コアクラス(Transcription)の
fetchメソッドを繰り返し呼び出して、最終タスク結果を取得します。タスクステータスが
SUCCEEDEDまたはFAILEDの場合、ポーリングを停止して結果を処理します。fetchは タスク実行結果(TranscriptionResult) を返します。
リクエストパラメーター
TranscriptionParam のチェーンメソッドを使用してリクエストパラメーターを設定します。
パラメーター | 型 | デフォルト値 | 必須 | 説明 |
model | String | - | はい | 音声および動画ファイルの転写に使用するモデルの名称です。詳細については、「モデルの可用性」をご参照ください。 |
fileUrls | List<String> | - | はい | 転写対象の音声および動画ファイルの URL のリストです。HTTP および HTTPS プロトコルがサポートされます。1 回のリクエストで最大 100 個の URL を指定できます。 OSS に保存されている音声ファイルの場合、SDK では oss:// プレフィックス付きの一時 URL はサポートされていません。 |
vocabularyId | String | - | いいえ | ホットワード辞書の ID です。指定した辞書内のホットワードは、今回の音声認識タスクで有効になります。この機能はデフォルトで無効です。この機能の使用方法については、「ホットワードのカスタマイズ」をご参照ください。 |
channelId | List<Integer> | [0] | いいえ | マルチトラックファイル内で認識対象とする音声トラックのインデックス(0 開始)。例:[0] = 最初のトラックのみ、[0, 1] = 最初および 2 番目のトラック。デフォルト値:[0]。 重要 各トラックは別途課金されます。例:[0, 1] = ファイルあたり 2 回の課金。 |
specialWordFilter | String | - | いいえ | 音声認識中に処理される禁止用語を指定します。禁止用語ごとに異なる処理方法をサポートします。 このパラメーターを渡さない場合、システム組み込みの禁止用語フィルタリングロジックが有効になります。認識結果で Alibaba Cloud Model Studio 禁止用語リスト と一致する単語は、同じ長さのアスタリスク( このパラメーターを渡す場合、以下の禁止用語処理ポリシーを実装できます:
このパラメーターの値は、以下の構造を持つ JSON 文字列である必要があります: JSON フィールドの説明:
|
diarizationEnabled | Boolean | false | いいえ | 自動スピーカーダイアライゼーションはデフォルトで無効です。この機能はシングルチャンネル音声にのみ適用され、マルチチャンネル音声には対応していません。 有効にした場合、認識結果にはスピーカーを識別するための
|
speakerCount | Integer | - | いいえ | このパラメーターは、スピーカー数のヒント(2~100 の整数)です。 デフォルトでは、スピーカー数は自動検出されます。このパラメーターはアルゴリズムを補助するものであり、正確なスピーカー数を保証するものではありません。 |
language_hints | String[] | - | いいえ | 認識対象の言語コードです。自動言語検出を行う場合は、未設定のままにしてください。 システムは配列の最初の値のみを読み取り、追加の値は無視されます。 各モデルでサポートされる言語コードは以下のとおりです:
説明
パラメーターによる設定parameters メソッドで設定 |
apiKey | 文字列 | - | いいえ | ご利用の API キー。API キーを環境変数として設定済みの場合、コード内で設定する必要はありません。そうでない場合は、コード内で設定する必要があります。 |
応答
タスク実行結果(TranscriptionResult)
TranscriptionResult は、現在のタスク実行結果をカプセル化します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
| なし | requestId | リクエスト ID を取得します。 |
| なし | taskId | タスク ID を取得します。 |
| なし |
| タスクステータスを取得します。
説明 タスクに複数のサブタスクが含まれる場合、少なくとも 1 つのサブタスクが成功すれば、全体のタスクステータスは |
| なし | サブタスク実行結果(TranscriptionTaskResult) を取得します。 各タスクは 1 つ以上の音声ファイルを認識します。異なる音声ファイルは異なるサブタスクで処理されます。したがって、各タスクには 1 つ以上のサブタスクが対応します。 | |
| なし | JSON 形式のタスク実行結果 | タスク実行結果を取得します。 結果は JSON 形式です。 |
サブタスク実行結果(TranscriptionTaskResult)
TranscriptionTaskResult は、サブタスク実行結果をカプセル化します。サブタスクとは、単一の音声ファイルの認識を指します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
| なし | 認識対象の音声ファイルの URL | 認識対象の音声ファイルの URL を取得します。 |
| なし | 認識結果の URL | 認識結果の URL を取得します。この URL は 24 時間有効です。有効期限が切れた後は、以前の照会から取得した URL を使用してタスクを照会したり、結果をダウンロードしたりすることはできません。 認識結果は JSON ファイルとして保存されます。このファイルは URL からダウンロードすることも、HTTP リクエストで直接その内容を読み取ることもできます。 JSON データ内の各フィールドの意味については、「認識結果の説明」をご参照ください。 |
| なし |
| サブタスクステータスを取得します。
|
| なし | タスク実行プロセスからの主要な情報。空の場合があります。 | タスク実行プロセスからの主要な情報を取得します。 タスクが失敗した場合、この内容を確認して原因を分析できます。 |
認識結果の説明
認識結果は JSON ファイルとして保存されます。
主なパラメーターは以下のとおりです:
パラメーター | 型 | 説明 |
audio_format | string | ソースファイル内の音声のフォーマットです。 |
channels | array[integer] | ソースファイル内の音声トラックのインデックス情報です。シングルトラック音声の場合は [0]、デュアルトラック音声の場合は [0, 1] などが返されます。 |
original_sampling_rate | integer | ソースファイル内の音声のサンプルレート(Hz)です。 |
original_duration_in_milliseconds | integer | ソースファイル内の音声の元の再生時間(ms)です。 |
channel_id | integer | 認識対象の音声トラックのインデックス(0 開始)です。 |
content_duration | integer | 音声トラック内で音声として検出されたコンテンツの再生時間(ms)です。 重要 課金は音声コンテンツの再生時間のみに基づきます(非音声部分は課金対象外です)。音声の再生時間は、通常、音声ファイルの総再生時間より短くなります。AI を使用した音声検出には、わずかな誤差が生じる場合があります。 |
transcript | string | 段落レベルの音声認識結果です。 |
sentences | array | 文レベルの音声認識結果です。 |
words | array | 単語レベルの音声認識結果です。 |
begin_time | integer | 開始タイムスタンプ(ms)です。 |
end_time | integer | 終了タイムスタンプ(ms)です。 |
text | string | 音声認識結果です。 |
speaker_id | integer | 現在のスピーカーのインデックス(0 開始)です。これにより、異なるスピーカーを区別できます。 このフィールドは、スピーカーダイアライゼーションが有効な場合にのみ認識結果に表示されます。 |
punctuation | string | 予測された単語後の句読点(該当する場合)です。 |
主要なインターフェイス
タスク照会パラメータークラス(TranscriptionQueryParam)
TranscriptionQueryParam は、タスク完了を待機する場合(wait メソッドを Transcription に対して呼び出す場合)や、タスク実行結果を照会する場合(fetch メソッドを Transcription に対して呼び出す場合)に使用されます。
TranscriptionQueryParam インスタンスは、静的メソッド FromTranscriptionParam を使用して作成します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|
|
|
|
コアクラス(Transcription)
Transcription は、import com.alibaba.dashscope.audio.asr.transcription.*; 文でインポートできます。このクラスの主要なインターフェイスは以下のとおりです:
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|
| 音声認識タスクを非同期で送信します。 | |
|
| 非同期タスクが完了するまで(タスクステータスが | |
|
| 現在のタスクの実行結果を非同期で照会します。 |
エラーコード
エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。
タスクに複数のサブタスクが含まれる場合、少なくとも 1 つのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を確認するには、subtask_status フィールドを確認する必要があります。
エラー応答の例:
{
"task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2024-12-16 16:30:59.170",
"scheduled_time": "2024-12-16 16:30:59.204",
"end_time": "2024-12-16 16:31:02.375",
"results": [
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
"transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
"subtask_status": "SUCCEEDED"
},
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
"code": "InvalidFile.DownloadFailed",
"message": "音声ファイルをダウンロードできません。",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 1,
"FAILED": 1
}
}よくある質問
機能
Q: Base64 エンコーディングの音声は対応していますか?
このサービスは、公開 URL からの音声のみを認識します。Base64 エンコーディング、バイナリ ストリーム、またはローカルファイルの音声はサポートしていません。
Q: オーディオファイルを公開 URL として提供するにはどうすればよいですか?
通常、次の手順に従うことができます。これは一般的なガイドであり、特定のステップは異なるストレージプロダクトによって異なる場合があります。オーディオを Object Storage Service (OSS) にアップロードすることを推奨します。
SDK を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時 URL は使用できません。
RESTful API を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時 URL を使用できます。
一時 URL は 48 時間有効であり、有効期限が切れると使用できません。本番環境では使用しないでください。
アップロード認証情報を取得するための API は 100 QPS に制限されており、スケールアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。
本番環境の場合、長期的なファイルの可用性を確保し、レート制限の問題を回避するために、OSS などの安定したストレージサービスを使用してください。
Q:認識結果を取得するのにどのくらいの時間がかかりますか?
タスクは送信後に PENDING 状態に入ります。キュー待ち時間(通常数分)は、キューの長さとファイルの持続時間によって異なります。音声ファイルが長いほど、処理時間が長くなります。
トラブルシューティング
コードエラーが発生した場合は、「エラーコード」の情報をもとに問題を解決してください。
Q:連続ポーリング後に結果が取得できないのはなぜですか?
これは、レート制限が原因である可能性があります。
Q:音声が認識されない(認識結果がない)のはなぜですか?
音声のフォーマットとサンプルレートが正しく、パラメーターの制約を満たしているか確認してください。
音声ファイルのコンテナ、コーデック、サンプルレート、チャンネルに関する情報を取得するには、ffprobe ツールを使用できます。
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx