Fun-ASR 音声ファイル認識 Python SDK のパラメーターとインターフェースについて説明します。
ユーザーガイド：モデルと選択の推奨事項の詳細については、「音声ファイル認識 - Fun-ASR/Paraformer」をご参照ください。
前提条件
Model Studio をアクティブ化し、API キーを作成済みであること。セキュリティリスクを防ぐため、環境変数としてエクスポート (ハードコーディングしない) してください。
説明一時的なアクセスや高リスク操作 (機密データへのアクセス/削除) を厳密に制御する場合は、代わりに一時認証トークンを使用してください。
長期 API キーと比較して、一時トークンはより安全 (有効期間 60 秒) であり、API キーの漏洩リスクを低減します。
一時トークンを使用するには、コード内で認証に使用される API キーを一時認証トークンに置き換えます。
モデルの可用性
国際版
「国際版デプロイモード」では、エンドポイントおよびデータストレージが シンガポールリージョン に配置されます。モデル推論の計算リソースは、中国本土を除くグローバル範囲で動的にスケジュールされます。
モデル | バージョン | 単価 | 無料クォータ （注） |
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 は file_urls パラメーターを使用して指定します。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 クラスの
async_call()メソッドを、リクエストパラメーター を指定して呼び出します。説明タスクは送信後に
PENDINGステータスになります。キュー待ち時間（通常数分程度）は、キューの長さおよびファイルの持続時間に依存します。処理が開始されると、音声認識は大幅に高速化された速度で完了します。認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限切れとなります。有効期限切れ後は、タスクの照会ができなくなります。
Transcription.wait()を呼び出して、タスク完了までブロックします。タスクステータス：
PENDING、RUNNING、SUCCEEDED、FAILED。waitメソッドは、PENDING/RUNNINGステータスでブロックし、ステータスがSUCCEEDEDまたはFAILEDに遷移した時点で戻ります。TranscriptionResponse を返します。
非同期送信と非同期照会
Transcription クラスの
async_call()メソッドを、リクエストパラメーター を指定して呼び出します。説明タスクは送信後に
PENDINGステータスになります。キュー待ち時間（通常数分程度）は、キューの長さおよびファイルの持続時間に依存します。処理が開始されると、音声認識は大幅に高速化された速度で完了します。認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限切れとなります。有効期限切れ後は、タスクの照会ができなくなります。
Transcription.fetch()をポーリングして、最終結果を取得します。ステータスが
SUCCEEDEDまたはFAILEDになった時点でポーリングを停止します。TranscriptionResponse を返します。
リクエストパラメーター
Transcription.async_call() でリクエストパラメーターを設定します。
パラメーター | 型 | デフォルト | 必須 | 説明 |
model | str | - | はい | 音声/動画の文字起こしに使用するモデルです。詳細については、「モデルの可用性」をご参照ください。 |
file_urls | list[str] | - | はい | 文字起こし対象の音声/動画ファイルの URL (HTTP/HTTPS) です。リクエストごとに最大 100 個の URL を指定できます。 ご利用の音声ファイルが OSS に保存されている場合、SDK は `oss://` プレフィックスで始まる一時的な URL をサポートしていません。 |
channel_id | list[int] | [0] | いいえ | マルチトラックファイルで認識するオーディオトラックのインデックス (0 から始まるインデックス) です。例：`[0]` は最初のトラックのみ、`[0, 1]` は最初のトラックと 2 番目のトラックを意味します。デフォルト：`[0]`。 重要 各トラックは個別に課金されます。例：`[0, 1]` の場合、ファイルごとに 2 回課金されます。 |
special_word_filter | str | - | いいえ | 音声認識中に処理する禁止用語を指定し、禁止用語ごとに異なる処理メソッドをサポートします。 このパラメーターが渡されない場合、システムに組み込まれた禁止用語フィルタリングロジックが有効になります。認識結果に含まれる単語が Alibaba Cloud Model Studio の禁止用語リスト と一致する場合、その単語は同じ長さのアスタリスク ( このパラメーターが渡された場合、以下の禁止用語処理ポリシーを実装できます：
このパラメーターの値は、以下の構造を持つ JSON 文字列である必要があります： JSON フィールドの説明：
|
diarization_enabled | bool | False | いいえ | 話者ダイアライゼーションの自動化はデフォルトで無効になっています。この機能はシングルチャンネルオーディオにのみ適用され、マルチチャンネルオーディオではサポートされていません。 有効にすると、認識結果に話者を区別するための
|
speaker_count | int | - | いいえ | 参考話者数 (整数、2～100)。 デフォルト：自動検出。このパラメーターはアルゴリズムをガイドするのに役立ちますが、正確な話者数を保証するものではありません。 |
language_hints | list[str] | - | いいえ | 認識用の言語コードです。設定しない場合は、自動言語検出が使用されます。 システムは配列の最初の値のみを読み取り、それ以降の値は無視します。 各モデルでサポートされている言語コードは以下の通りです：
|
speech_noise_threshold | float | - | いいえ |
応答結果
TranscriptionResponse
TranscriptionResponse は、task_id や task_status などのタスクの基本情報をカプセル化し、実行結果を含むオブジェクトです。実行結果は output プロパティに対応します。詳細については、「TranscriptionOutput」をご参照ください。
留意すべきパラメーター：
パラメーター | 説明 |
status_code | HTTP リクエストのステータスコードです。 |
code |
|
message |
|
task_id | タスク ID です。 |
task_status | タスクのステータスです。 有効な値は タスクに複数のサブタスクが含まれる場合、1 つ以上のサブタスクが成功すれば、全体のタスクステータスは |
results | サブタスクの認識結果です。 |
subtask_status | サブタスクのステータスです。 有効な値は |
file_url | 認識対象の音声ファイルの URL です。 |
transcription_url | 音声認識結果の URL です。 認識結果は JSON ファイルとして保存されます。 |
TranscriptionOutput
TranscriptionOutput は、TranscriptionResponse の output プロパティであり、タスク実行結果を含みます。
主なパラメーター：
パラメーター | 説明 |
code | エラーコードです。エラーコード を参照し、 |
message | エラーメッセージです。 |
task_id | タスク ID です。 |
task_status | タスクのステータスです。 有効な値は タスクに複数のサブタスクが含まれる場合、1 つ以上のサブタスクが成功すれば、全体のタスクステータスは |
results | サブタスクの認識結果です。 |
subtask_status | サブタスクのステータスです。 有効な値は |
file_url | 認識対象の音声ファイルの URL です。 |
transcription_url | 音声認識結果の URL です。 認識結果は 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 から始まる）です。複数の話者を区別するために使用されます。 このフィールドは、スピーカー識別（speaker diarization）が有効な場合にのみ認識結果に表示されます。 |
punctuation | string | 予測された単語後の句読点（該当する場合）です。 |
主要インターフェイス
コアクラス (Transcription)
インポート: from dashscope.audio.asr import Transcription
メンバーメソッド | メソッドシグネチャ | 説明 |
async_call | | 音声認識タスクを非同期で送信します。 |
wait | | 非同期タスクが完了するまで（タスクステータスが このメソッドは TranscriptionResponse を返します。 |
fetch | | 現在のタスクの実行結果を非同期で照会します。 このメソッドは TranscriptionResponse を返します。 |
エラーコード
エラーが発生した場合は、「エラーメッセージ」をご参照ください。
タスクに複数のサブタスクが含まれる場合、少なくとも 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