Paraformer 音声ファイル認識 Java SDK のパラメーターおよび API について説明します。
本ドキュメントは、中国 (北京) リージョンでのみ有効です。モデルを利用するには、中国 (北京) リージョンの API キー を使用する必要があります。
ユーザーガイド: モデルの概要および選択方法については、「音声ファイル認識 - Fun-ASR/Paraformer/SenseVoice」をご参照ください。
前提条件
Model Studio を有効化し、API キーを作成済みである必要があります。環境変数としてエクスポート(ハードコーディングしない)してください。これにより、セキュリティリスクを防止できます。
説明一時的なアクセスまたは高リスク操作(機密データへのアクセス/削除)を厳密に制御する必要がある場合は、一時認証トークンをご利用ください。
長期使用の API キーと比較して、一時トークンはより安全(有効期間:60 秒)であり、API キーの漏洩リスクを低減します。
一時トークンを利用する場合、コード内の認証に使用する API キーを、一時認証トークンに置き換えてください。
DashScope SDK の最新版をインストールしてください。
モデル一覧
paraformer-v2 | paraformer-8k-v2 | |
適用シナリオ | ライブ配信や会議などのマルチリンガル認識 | 電話コールセンターやボイスメールなどの中国語認識 |
サンプルレート | 任意 | 8 kHz |
対応言語 | 中国語(標準語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語 対応中国語方言:上海語、呉語、閩南語、東北官話、甘粛話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、広東語 | 中国語 |
句読点予測 | ✅ デフォルトで有効、設定不要 | ✅ デフォルトで有効、設定不要 |
逆テキスト正規化 (ITN) | ✅ デフォルトで有効、設定不要 | ✅ デフォルトで有効、設定不要 |
認識言語の指定 | ✅ | ❌ |
制限事項
本サービスは、ローカルの音声・動画ファイルの直接アップロードおよび base64 エンコードされた音声の入力に対応していません。 入力ソースは、インターネット経由でアクセス可能な HTTP または HTTPS プロトコルをサポートするファイル URL である必要があります。例: https://your-domain.com/file.mp3。
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 が正確な認識を保証することはできません(すべての可能性をテストすることが現実的ではないため)。ご利用のファイルが期待通りの音声認識結果を生成することを確認するため、事前にテストを行うことを推奨します。
音声のサンプルレート
サンプルレートはモデルによって異なります。
paraformer-v2:任意のサンプルレートをサポート
paraformer-8k-v2:8 kHz のみをサポート
音声ファイルのサイズおよび再生時間
音声ファイルのサイズは 2 GB を、再生時間は 12 時間を超えてはなりません。
これらの制限を超えるファイルを処理するには、前処理によりファイルサイズを縮小してください。「音声ファイル認識シナリオ向けの動画ファイルの前処理による文字起こし効率の向上」をご参照ください。
バッチ処理における音声ファイル数
1 回のリクエストで最大 100 個のファイル URL を指定できます。
認識可能な言語
モデルによって異なります。
paraformer-v2:
中国語(標準語および各種方言):上海語、呉語、閩南語、東北官話、甘粛話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、広東語
英語
日本語
韓国語
paraformer-8k-v2:中国語のみをサポート
クイックスタート
コアクラス(Transcription) は、非同期でタスクを送信するメソッド、同期でタスク完了を待機するメソッド、非同期でタスク実行結果を照会するメソッドを提供します。音声ファイル認識は、以下の 2 つの方法のいずれかで実行できます。
非同期タスク送信 + 同期でタスク完了を待機:タスクを送信した後、現在のスレッドはタスクが完了し、認識結果が返されるまでブロックされます。
非同期タスク送信 + 非同期でタスク実行結果を照会:タスクを送信した後、必要に応じて照会タスクインターフェイスを呼び出してタスク実行結果を照会できます。
非同期タスク送信 + 同期でタスク完了を待機
リクエストパラメーター を構成します。
コアクラス(Transcription) のインスタンスを作成します。
コアクラス(Transcription) の
asyncCallメソッドを呼び出して、タスクを非同期で送信します。説明ファイル文字起こしサービスは、API 経由で送信されたタスクをベストエフォート方式で処理します。タスクを送信すると、キューイング(
PENDING)状態に入ります。キューイング時間はキューの長さおよびファイルの再生時間に依存し、正確には特定できませんが、通常は数分以内です。タスクの処理が開始されると、音声認識プロセスはリアルタイム再生速度の数百倍の速さで実行されます。認識結果およびダウンロード URL は、タスク完了後 24 時間有効です。この期間を過ぎると、タスクの照会や結果のダウンロードができなくなります。
コアクラス(Transcription) の
waitメソッドを呼び出して、タスク完了を同期で待機します。タスクのステータスは
PENDING、RUNNING、SUCCEEDED、FAILEDのいずれかになります。wait呼び出しは、タスクステータスがPENDINGまたはRUNNINGの間はブロックされます。タスクステータスがSUCCEEDEDまたはFAILEDになると、wait呼び出しはブロック解除され、タスク実行結果を返します。waitメソッドは、タスク実行結果(TranscriptionResult) を返します。
非同期タスク送信 + 非同期でタスク実行結果を照会
リクエストパラメーター を構成します。
コアクラス(Transcription) のインスタンスを作成します。
コアクラス(Transcription) の
asyncCallメソッドを呼び出して、タスクを非同期で送信します。説明ファイル文字起こしサービスは、API 経由で送信されたタスクをベストエフォート方式で処理します。タスクを送信すると、キューイング(
PENDING)状態に入ります。キューイング時間はキューの長さおよびファイルの再生時間に依存し、正確には特定できませんが、通常は数分以内です。タスクの処理が開始されると、音声認識プロセスはリアルタイム再生速度の数百倍の速さで実行されます。認識結果およびダウンロード URL は、タスク完了後 24 時間有効です。この期間を過ぎると、タスクの照会や結果のダウンロードができなくなります。
コアクラス(Transcription) の
fetchメソッドを繰り返し呼び出して、最終的なタスク結果を取得できます。タスクステータスが
SUCCEEDEDまたはFAILEDの場合、ポーリングを停止して結果を処理します。fetchメソッドは、タスク実行結果(TranscriptionResult) を返します。
リクエストパラメーター
TranscriptionParam クラスのチェーンメソッドを使用して、リクエストパラメーターを構成できます。
パラメーター | 型 | デフォルト値 | 必須 | 説明 |
model | String | - | はい | 音声・動画ファイルの文字起こしに使用する Paraformer モデル名です。詳細については、「モデル一覧」をご参照ください。 |
fileUrls | List<String> | - | はい | 文字起こし対象の音声・動画ファイルの URL です。HTTP および HTTPS プロトコルがサポートされています。1 回のリクエストで最大 100 個の URL を指定できます。 OSS に保存された音声ファイルを使用する場合、SDK では oss:// プレフィックス付きの一時 URL はサポートされていません。 |
channelId | List<Integer> | [0] | いいえ | マルチトラック音声ファイルにおいて、認識対象とする音声トラックのインデックスを指定します。インデックスは 0 から始まります。たとえば、[0] は最初のトラックのみを認識することを意味し、[0, 1] は最初と 2 番目のトラックの両方を認識することを意味します。このパラメーターを省略した場合、デフォルトで最初のトラックが処理されます。 重要 指定された各音声トラックは個別に課金されます。たとえば、単一ファイルに対して [0, 1] を指定した場合、2 件分の課金が発生します。 |
disfluencyRemovalEnabled | Boolean | false | いいえ | フィラー語をフィルター処理します。この機能はデフォルトで無効です。 |
timestampAlignmentEnabled | Boolean | false | いいえ | タイムスタンプ配置機能を有効にするかどうかを指定します。この機能はデフォルトで無効です。 |
specialWordFilter | String | - | いいえ | 音声認識中に処理される禁止用語を指定し、異なる禁止用語に対して異なる処理方法をサポートします。 このパラメーターを渡さない場合、システムは組み込みの禁止用語フィルタリングロジックを有効にします。Alibaba Cloud Model Studio 禁止用語リスト(中国語) に一致する検出結果内の単語は、等しい数の このパラメーターを渡す場合、以下の禁止用語処理戦略を実装できます。
このパラメーターの値は、以下の構造を持つ JSON 文字列である必要があります。 JSON フィールドの説明:
|
language_hints | String[] | ["zh", "en"] | いいえ | 認識対象の音声の言語コードを指定します。 このパラメーターは paraformer-v2 モデルでのみ適用可能です。 対応言語コード:
説明
parameter メソッドを使用した設定parameters メソッドを使用した設定 |
diarizationEnabled | Boolean | false | いいえ | 自動スピーカーダイアライゼーションです。この機能はデフォルトで無効です。 この機能はモノラル音声にのみ適用可能です。マルチチャンネル音声ではスピーカーダイアライゼーションはサポートされません。 この機能を有効にすると、認識結果に
|
speakerCount | Integer | - | いいえ | スピーカー数の参照値です。値は 2 ~ 100 の整数である必要があります。 このパラメーターは、スピーカーダイアライゼーションが有効化された場合( デフォルトでは、スピーカー数は自動的に決定されます。このパラメーターを設定した場合、アルゴリズムが指定されたスピーカー数を出力するよう試みる補助となりますが、必ずしもその数が出力されることを保証するものではありません。 |
apiKey | String | - | いいえ | ご利用の API キーです。API キーを環境変数として設定済みの場合、コード内での設定は不要です。設定していない場合は、コード内で設定する必要があります。 |
応答結果
タスク実行結果(TranscriptionResult)
TranscriptionResult は、現在のタスク実行結果をカプセル化します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
| なし | requestId | リクエスト ID を返します。 |
| なし | taskId | タスク ID を返します。 |
| なし |
| タスクステータスを返します。
説明 タスクに複数のサブタスクが含まれる場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは |
| なし | サブタスク実行結果(TranscriptionTaskResult) を返します。 各タスクは 1 つ以上の音声ファイルを認識します。異なる音声ファイルは異なるサブタスクで処理されるため、各タスクには 1 つ以上のサブタスクが対応します。 | |
| なし | JSON 形式のタスク実行結果 | タスク実行結果を返します。 この結果は JSON 形式です。 |
サブタスク実行結果(TranscriptionTaskResult)
TranscriptionTaskResult は、サブタスク実行結果をカプセル化します。サブタスクは、単一の音声ファイルの認識に対応します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
| なし | 認識対象の音声ファイルへのリンク | 認識対象の音声ファイルへのリンクを返します。 |
| なし | 認識結果へのリンク | 認識結果へのリンクを返します。このリンクは 24 時間有効です。この期間を過ぎると、以前に照会した URL を使用してタスクの照会や結果のダウンロードができなくなります。 認識結果は JSON ファイルとして保存されます。上記のリンクからこのファイルをダウンロードするか、HTTP リクエストを介してファイルの内容を直接読み取ることができます。 JSON データ内の各フィールドの意味については、「認識結果の説明」をご参照ください。 |
| なし |
| サブタスクステータスを返します。
|
| なし | タスク実行中の重要な情報(空の場合あり) | タスク実行中の重要な情報を返します。 タスクが失敗した場合、この内容を確認して原因を分析できます。 |
認識結果の説明
認識結果は JSON ファイルとして保存されます。
以下の表に、主なパラメーターの説明を示します。
パラメーター | 型 | 説明 |
audio_format | string | ソースファイル内の音声フォーマットです。 |
channels | array[integer] | ソースファイル内の音声トラックのインデックス情報です。モノラル音声では [0]、ステレオ音声では [0, 1] などが返されます。 |
original_sampling_rate | integer | ソースファイル内の音声のサンプルレート(Hz)です。 |
original_duration | integer | ソースファイル内の元の音声の再生時間(ms)です。 |
channel_id | integer | 文字起こし結果の音声トラックインデックスです(0 から始まります)。 |
content_duration | integer | 音声トラック内で音声と判定されたコンテンツの再生時間(ms)です。 重要 Paraformer 音声認識モデルサービスでは、音声トラック内で音声と判定されたコンテンツの再生時間のみが文字起こしおよび課金の対象となります。非音声コンテンツは計測および課金の対象外です。通常、音声コンテンツの再生時間は元の音声の再生時間よりも短くなります。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.*; ステートメントでインポートできます。このクラスの主なメソッドを以下に示します。
インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|
| 音声認識タスクを非同期で送信します。 | |
|
| 現在のスレッドをブロックし、非同期タスクが終了するまで(タスクステータスが | |
|
| 現在のタスク実行結果を非同期で照会します。 |
エラーコード
エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者グループ に参加して問題を報告し、調査のために Request ID を提供してください。
タスクに複数のサブタスクが含まれる場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは 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
}
}その他の例
その他の例については、「GitHub」をご参照ください。
よくある質問
機能
Q:base64 エンコードされた音声はサポートされていますか?
いいえ、サポートされていません。本サービスは、インターネット経由でアクセス可能な URL からの音声認識のみをサポートしており、バイナリストリームやローカルファイルはサポートしていません。
Q:音声ファイルを公開アクセス可能な URL として提供するにはどうすればよいですか?
以下の一般的な手順に従ってください。具体的な手順は使用するストレージ製品によって異なります。当社では、OSS への音声ファイルのアップロード を推奨します。
SDK を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスが付いた一時 URL は使用できません。
RESTful API を使用して OSS に保存されたファイルにアクセスする場合、oss:// プレフィックスを含む一時的な URL を使用できます:
一時 URL の有効期間は 48 時間であり、有効期限切れ後は使用できません。本番環境では使用しないでください。
アップロード認証情報取得 API の呼び出し上限は 100 QPS であり、スケーリングはサポートされていません。本番環境、高い同時実行性を要するシナリオ、およびストレステストシナリオでは使用しないでください。
本番環境では、ファイルの長期的な可用性を確保し、レート制限の問題を回避するために、OSS などの安定したストレージサービスをご利用ください。
Q:認識結果を取得するまでの所要時間はどのくらいですか?
タスクを送信すると、PENDING 状態に入ります。キューイング時間はキューの長さおよびファイルの再生時間に依存し、正確には特定できませんが、通常は数分以内です。長い音声ファイルほど処理時間がかかります。
トラブルシューティング
コードエラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
Q:認識結果が音声の再生と同期していない場合、どうすればよいですか?
リクエストパラメーター timestampAlignmentEnabled を true に設定して、タイムスタンプ配置機能を有効化することで、認識結果を音声の再生と同期させることができます。
Q:継続的なポーリングを行っても結果が取得できないのはなぜですか?
これはレート制限による可能性があります。クォータの増加を依頼するには、開発者グループ に参加してください。
Q:音声が認識されない(認識結果がない)のはなぜですか?
音声がフォーマットおよびサンプルレートの要件を満たしているか確認してください。
paraformer-v2モデルを使用している場合、language_hintsパラメーターが正しく設定されているか確認してください。
その他の質問
詳細については、「GitHub 上の QA」をご参照ください。