Paraformer Python SDK で録音済み音声の文字起こし - Alibaba Cloud Model Studio

このトピックでは、Paraformer 録音ファイル認識 Python SDK のパラメーターと API の詳細について説明します。

重要

このドキュメントは、「中国 (北京)」リージョンにのみ適用されます。モデルを使用するには、API キーを「中国 (北京)」リージョンから取得する必要があります。

ユーザーガイド：モデルの概要と選択方法については、「音声ファイル認識 - Fun-ASR/Paraformer」をご参照ください。

前提条件

Model Studio を有効化し、API キーを作成済みであること。セキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、環境変数としてエクスポートしてください。
説明
サードパーティのアプリケーションやユーザーに一時的なアクセス権限を付与する場合、または機密データへのアクセスや削除などのリスクの高い操作を厳密に制御したい場合は、一時的な認証トークンを使用することを推奨します。
長期的な API キーと比較して、一時的な認証トークンは有効期間が短い (60 秒) ため、より安全です。これらは一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。
一時的なトークンを使用するには、コード内の認証に使用される API キーを一時的な認証トークンに置き換えます。
DashScope SDK の最新バージョンをインストールする。

モデル

	paraformer-v2	paraformer-8k-v2
シナリオ	ライブストリーミングや会議などの多言語認識シナリオ	電話カスタマーサービスやボイスメールなどの中国語認識シナリオ
サンプルレート	任意	8 kHz
言語	中国語 (標準語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語サポートされている中国語の方言：上海語、呉語、閩南語、東北方言、甘粛方言、貴州方言、河南方言、湖北方言、湖南方言、江西方言、寧夏方言、山西方言、陝西方言、山東方言、四川方言、天津方言、雲南方言、広東語	中国語
句読点予測	✅ デフォルトでサポート、設定不要	✅ デフォルトでサポート、設定不要
逆テキスト正規化 (ITN)	✅ デフォルトでサポート、設定不要	✅ デフォルトでサポート、設定不要
カスタムホットワード	✅ 詳細については、「カスタムホットワード」をご参照ください	✅ 詳細については、「カスタムホットワード」をご参照ください
認識言語の指定	✅ `language_hints` パラメーターで指定	❌

制限事項

このサービスは、ローカルの音声または動画ファイルの直接アップロードをサポートしていません。また、base64 エンコードされた音声もサポートしていません。入力ソースは、HTTP または HTTPS プロトコルをサポートするインターネット経由でアクセス可能なファイル URL である必要があります。例：https://your-domain.com/file.mp3。

SDK を使用して Object Storage Service (OSS) に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時的な URL は使用できません。

RESTful API を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時的な URL を使用できます：

重要

一時的な URL は 48 時間有効で、有効期限が切れると使用できなくなります。本番環境では使用しないでください。
アップロード認証情報を取得するための API は 100 QPS に制限されており、スケールアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。
本番環境では、Alibaba Cloud OSS などの安定したストレージサービスを使用して、長期的なファイルの可用性を確保し、レート制限の問題を回避してください。

URL は file_urls パラメーターを使用して指定できます。1 回のリクエストで最大 100 個の URL をサポートします。

音声フォーマット
aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、および wmv
重要
すべての音声および動画フォーマットとそのバリアントに対して正しい認識を保証することはできません。これは、すべての可能性をテストすることが現実的でないためです。ファイルが期待される音声認識結果を生成することを確認するために、ファイルをテストすることを推奨します。
音声サンプルレート
サンプルレートはモデルによって異なります：
- paraformer-v2 は任意のサンプルレートをサポートします
- paraformer-8k-v2 は 8 kHz のサンプルレートのみをサポートします
音声ファイルのサイズと長さ
音声ファイルはサイズが 2 GB、長さが 12 時間を超えることはできません。
これらの制限を超えるファイルを処理するには、前処理を行ってサイズを小さくすることができます。前処理のベストプラクティスについては、「動画ファイルを前処理してファイル文字起こし効率を向上させる (音声ファイル認識シナリオ向け)」をご参照ください。
バッチ処理用の音声ファイル数
1 回のリクエストで最大 100 個のファイル URL をサポートします。
認識可能な言語
モデルによって異なります：
- paraformer-v2：
  - 中国語 (標準語および各種方言)：上海語、呉語、閩南語、東北方言、甘粛方言、貴州方言、河南方言、湖北方言、湖南方言、江西方言、寧夏方言、山西方言、陝西方言、山東方言、四川方言、天津方言、雲南方言、広東語
  - 英語
  - 日本語
  - 韓国語
- paraformer-8k-v2 は中国語のみをサポートします

はじめに

Transcription クラスは、タスクを非同期で送信し、タスクが完了するのを同期的に待機し、タスクの実行結果を非同期でクエリするためのメソッドを提供します。録音ファイル認識には、次の 2 つの方法を使用できます：

非同期タスクの送信 + タスク完了の同期待機：タスクを送信した後、タスクが完了して認識結果が返されるまで現在のスレッドはブロックされます。
非同期タスクの送信 + タスク実行結果の非同期クエリ：タスクを送信した後、必要なときにクエリタスクインターフェイスを呼び出すことで、タスクの実行結果を取得できます。

非同期タスクの送信 + タスク完了の同期待機

コアクラス (Transcription) の async_call メソッドを呼び出し、リクエストパラメーターを設定します。
説明
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。タスクが送信されると、キューイング (PENDING) 状態になります。キューイング時間はキューの長さとファイルの長さに依存し、正確に決定することはできませんが、通常は数分以内です。タスクの処理が開始されると、音声認識プロセスはリアルタイム再生の数百倍の速さになります。
- 認識結果とダウンロード URL は、タスク完了後 24 時間有効です。この期間を過ぎると、タスクのクエリや結果のダウンロードはできません。
コアクラス (Transcription) の wait メソッドを呼び出して、タスクが完了するのを同期的に待機します。
タスクのステータスには PENDING、RUNNING、SUCCEEDED、FAILED があります。タスクのステータスが PENDING または RUNNING の場合、wait メソッドはブロックされます。タスクのステータスが SUCCEEDED または FAILED の場合、wait メソッドはブロックされなくなり、タスクの実行結果を返します。
wait メソッドは TranscriptionResponse を返します。

クリックして完全な例を表示

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# 環境変数に API キーを設定していない場合は、次の行のコメントを解除し、apiKey をご自身の API キーに置き換える必要があります。
# import dashscope
# dashscope.api_key = "apiKey"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav',
               'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav'],
    language_hints=['zh', 'en']  # "language_hints" は paraformer-v2 モデルでのみサポートされています
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('文字起こしが完了しました！')

非同期タスクの送信 + タスク実行結果の非同期クエリ

コアクラス (Transcription) の async_call メソッドを呼び出し、リクエストパラメーターを設定します。
説明
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。タスクが送信されると、キューイング (PENDING) 状態になります。キューイング時間はキューの長さとファイルの長さに依存し、正確に決定することはできませんが、通常は数分以内です。タスクの処理が開始されると、音声認識プロセスはリアルタイム再生の数百倍の速さになります。
- 認識結果とダウンロード URL は、タスク完了後 24 時間有効です。この期間を過ぎると、タスクのクエリや結果のダウンロードはできません。
最終的なタスク結果を取得するまで、コアクラス (Transcription) の fetch メソッドをループで呼び出します。
タスクのステータスが SUCCEEDED または FAILED の場合、ポーリングを停止して結果を処理します。
fetch メソッドは TranscriptionResponse を返します。

クリックして完全な例を表示

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# 環境変数に API キーを設定していない場合は、次の行のコメントを解除し、apiKey をご自身の API キーに置き換える必要があります。
# import dashscope
# dashscope.api_key = "apiKey"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav',
               'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav'],
    language_hints=['zh', 'en']  # "language_hints" は paraformer-v2 モデルでのみサポートされています
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == 'FAILED':
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('文字起こしが完了しました！')

リクエストパラメーター

コアクラス (Transcription) の async_call メソッドを使用してリクエストパラメーターを設定できます。

パラメーター	タイプ	デフォルト値	必須	説明
model	str	-	はい	音声/動画ファイルの文字起こしに使用される Paraformer モデル名を指定します。詳細については、「モデル」をご参照ください。
file_urls	list[str]	-	はい	音声/動画ファイルの文字起こし用の URL のリスト。HTTP/HTTPS プロトコルをサポートします。1 回のリクエストで最大 100 個の URL をサポートします。音声ファイルが Alibaba Cloud OSS に保存されている場合、SDK は oss:// プレフィックスで始まる一時的な URL をサポートしません。
vocabulary_id	str	-	いいえ	最新のホットワードの ID。最新の v2 シリーズモデルはこのパラメーターと言語設定をサポートします。このホットワード ID に対応するホットワードは、現在の音声認識で有効になります。この機能はデフォルトで無効になっています。この機能の使用方法の詳細については、「カスタムホットワード」をご参照ください。
channel_id	list[int]	[0]	いいえ	マルチトラック音声ファイルで認識するオーディオトラックのインデックスを指定します。インデックスは 0 から始まります。たとえば、[0] は最初のトラックのみが認識されることを示し、[0, 1] は最初と 2 番目の両方のトラックが認識されることを示します。このパラメーターを省略すると、デフォルトで最初のトラックが処理されます。重要指定された各オーディオトラックは個別に課金されます。たとえば、1 つのファイルに対して [0, 1] をリクエストすると、2 つの個別の料金が発生します。
disfluency_removal_enabled	bool	False	いいえ	フィラーワードをフィルターします。デフォルトでは無効です。
timestamp_alignment_enabled	bool	False	いいえ	タイムスタンプアライメントを有効にします。デフォルトでは無効です。
special_word_filter	str	-	いいえ	音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法をサポートします。このパラメーターを渡さない場合、システムは組み込みの禁止用語フィルタリングロジックを有効にします。検出結果で Alibaba Cloud Model Studio 禁止用語リスト (中国語) に一致する単語は、同数の `` 文字に置き換えられます。このパラメーターが渡されると、次の禁止用語処理戦略を実装できます： `` で置換：一致した禁止用語を同数のアスタリスク (``) に置き換えます。直接フィルタリング：認識結果から一致する禁止用語を完全に削除します。このパラメーターの値は、次の構造を持つ JSON 文字列である必要があります： `{ "filter_with_signed": { "word_list": ["test"] }, "filter_with_empty": { "word_list": ["start", "happen"] }, "system_reserved_filter": true }` JSON フィールドの説明： `filter_with_signed` タイプ：object。必須：いいえ。説明：`` に置き換える禁止用語のリストを設定します。認識結果で一致した単語は、同数のアスタリスク (``) に置き換えられます。例：上記の JSON に基づくと、「Help me test this code」の音声認識結果は「Help me * this code」になります。内部フィールド： `word_list`：置き換える禁止用語をリストする文字列配列。 `filter_with_empty` タイプ：object。必須：いいえ。説明：認識結果から削除 (フィルタリング) する禁止用語のリストを設定します。認識結果で一致した単語は完全に削除されます。例：上記の JSON に基づくと、「Is the match about to start now?」の音声認識結果は「Is the match about to now?」になります。内部フィールド： `word_list`：完全に削除 (フィルタリング) する禁止用語をリストする文字列配列。 `system_reserved_filter` タイプ：ブール値。必須：いいえ。デフォルト値：true。説明：システムで事前定義された禁止用語ルールを有効にするかどうかを指定します。このパラメーターが `true` に設定されている場合、システムの組み込み禁止用語フィルタリングロジックも有効になり、検出結果で Alibaba Cloud Model Studio 禁止用語リスト (中国語) に一致する単語は、同数の `*` 文字に置き換えられます。
language_hints	list[str]	["zh", "en"]	いいえ	認識する音声の言語コードを指定します。このパラメーターは paraformer-v2 モデルにのみ適用されます。サポートされている言語コード： zh：中国語 en：英語 ja：日本語 yue：広東語 ko：韓国語 de：ドイツ語 fr：フランス語 ru：ロシア語
diarization_enabled	bool	False	いいえ	話者分離の自動化。この機能はデフォルトで無効になっています。この機能はモノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。この機能を有効にすると、認識結果に `speaker_id` フィールドが表示され、異なる話者を区別します。 `speaker_id` の例については、「認識結果の説明」をご参照ください。
speaker_count	int	-	いいえ	話者数の参照値。値は 2 から 100 までの整数 (2 と 100 を含む) である必要があります。このパラメーターは、話者分離が有効になった後 (`diarization_enabled` が true に設定されている) に有効になります。デフォルトでは、話者数は自動的に決定されます。このパラメーターを設定した場合、アルゴリズムが指定された話者数を出力しようとするのを補助するだけであり、この数が必ず出力されることを保証するものではありません。

応答結果

`TranscriptionResponse`

TranscriptionResponse は、task_id や task_status などのタスクの基本情報と実行結果をカプセル化します。実行結果は output 属性に対応します。詳細については、「TranscriptionOutput」をご参照ください。

TranscriptionResponse 構造の例を表示するにはクリック

次の例は、async_call メソッドによって返される TranscriptionResponse オブジェクトを示しています。応答には submit_time や scheduled_time などの情報は含まれません：

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING"
    },
    "usage":null
}

wait() または fetch() メソッドを呼び出して、submit_time や scheduled_time などの情報を取得します。async_call() の戻り値に直接アクセスしないでください。wait() または fetch() メソッドによって返される TranscriptionResponse オブジェクトの例を次に示します：

`PENDING`

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}

`RUNNING`

{
    "status_code":200,
    "request_id":"d9d530f1-853c-9848-a5f1-f5de59086ff7",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"RUNNING",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":null
}

`SUCCEEDED`

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "end_time":"2025-02-13 17:31:21.867",
        "results":[
            {
                "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A31/20ee4e4f-0404-4806-b617-c7d4c62eed19-1.json?Expires=1739525481&OSSAccessKeyId=yourOSSAccessKeyId&Signature=3q%2B1uQmRwltd7FPn5HQM2mBKw74%3D",
                "subtask_status":"SUCCEEDED"
            },
            {
                "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A31/be4f14c5-e46b-47ff-b03a-476ae9a45fd3-1.json?Expires=1739525481&OSSAccessKeyId=yourOSSAccessKeyId&Signature=EUX%2FRkGcn46L5d93ihQmpWUeYE4%3D",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":2,
            "FAILED":0
        }
    },
    "usage":{
        "duration":9
    }
}

`FAILED`

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code":null,
    "message":"",
    "output":{
        "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
        }
    },
    "usage":{
        "duration":9
    }
}

次の表に、主要なパラメーターを示します：

パラメーター	説明
status_code	HTTP リクエストの状態コード。
code	最も外側の `code` は無視できます。 `output.results` の下の `code` はエラーコードを表します。エラーコードと `message` フィールドを参照して問題をトラブルシューティングできます。
message	最も外側の `message` は無視できます。 `output.results` の下の `message` はエラーメッセージを表します。エラーコードと `code` フィールドを参照して問題をトラブルシューティングできます。
task_id	タスク ID。
task_status	タスクのステータス。ステータスは `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED` の 4 つです。タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すると、タスク全体のステータスは `SUCCEEDED` とマークされます。特定のサブタスクの結果を判断するには、`subtask_status` フィールドを確認する必要があります。
results	サブタスクの認識結果。
subtask_status	サブタスクのステータス。ステータスは `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED` の 4 つです。
file_url	認識された音声の URL。
transcription_url	音声認識結果に対応する URL。認識結果は JSON ファイルに保存されます。`transcription_url` に対応するリンクからファイルをダウンロードするか、HTTP リクエストを通じてファイルのコンテンツを直接読み取ることができます。JSON ファイルのコンテンツについては、「認識結果の説明」をご参照ください。

`TranscriptionOutput`

TranscriptionOutput は TranscriptionResponse の output 属性に対応し、現在のタスク実行結果を表します。

TranscriptionOutput 構造の例を表示するにはクリック

PENDING

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

RUNNING

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"RUNNING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

`SUCCEEDED`

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "end_time":"2025-02-13 17:59:28.828",
    "results":[
        {
            "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=yourOSSAccessKeyId&Signature=AtGjIKI%2BdgbzjJIu%2BHsr1R5nSAY%3D",
            "subtask_status":"SUCCEEDED"
        },
        {
            "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/ce1ebe74-be78-4ac8-b4f8-8e438a14d1c2-1.json?Expires=1739527168&OSSAccessKeyId=yourOSSAccessKeyId&Signature=z5s0ROpSU8HwiM8WHPNVpkuFG3A%3D",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":2,
        "FAILED":0
    }
}

`FAILED`

code パラメーターはエラーコード、message パラメーターはエラーメッセージです。これら 2 つのフィールドは例外的な場合にのみ表示されます。これら 2 つのフィールドを使用して問題をトラブルシューティングできます。詳細については、「エラーコード」をご参照ください。

{
    "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
    }
}

次の表に、主要なパラメーターを示します：

パラメーター	説明
code	エラーコードを表します。エラーコードと `message` フィールドを参照して問題をトラブルシューティングできます。
message	エラーメッセージを表します。エラーコードと `code` フィールドを参照して問題をトラブルシューティングできます。
task_id	タスク ID。
task_status	タスクのステータス。ステータスは `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED` の 4 つです。タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すると、タスク全体のステータスは `SUCCEEDED` とマークされます。特定のサブタスクの結果を判断するには、`subtask_status` フィールドを確認する必要があります。
results	サブタスクの認識結果。
subtask_status	サブタスクのステータス。ステータスは `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED` の 4 つです。
file_url	認識された音声の URL。
transcription_url	音声認識結果に対応する URL。認識結果は JSON ファイルに保存されます。`transcription_url` に対応するリンクからファイルをダウンロードするか、HTTP リクエストを通じてファイルのコンテンツを直接読み取ることができます。JSON ファイルのコンテンツについては、「認識結果の説明」をご参照ください。

認識結果の説明

認識結果は JSON ファイルとして保存されます。

認識結果の例を表示するにはクリック

{
    "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //このフィールドは、話者分離の自動化が有効な場合にのみ表示されます。
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // その他のコンテンツはここでは省略されています。
                    ]
                }
            ]
        }
    ]
}

次の表に、主要なパラメーターを示します：

パラメーター	タイプ	説明
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	単語の後に予測される句読点 (もしあれば)。

主要なインターフェイス

コアクラス (`Transcription`)

Transcription は from dashscope.audio.asr import Transcription を使用してインポートできます。

メンバーメソッド	メソッドシグネチャ	説明
async_call	`@classmethod def async_call(cls, model: str, file_urls: List[str], phrase_id: str = None, api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	音声認識タスクを非同期で送信します。このメソッドは TranscriptionResponse を返します。
wait	`@classmethod def wait(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	タスクが完了するまで (タスクステータスが `SUCCEEDED` または `FAILED` になるまで) 現在のスレッドをブロックします。このメソッドは TranscriptionResponse を返します。
fetch	`@classmethod def fetch(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	タスクの結果を非同期で取得します。このメソッドは TranscriptionResponse を返します。

エラーコード

エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。

問題が解決しない場合は、開発者グループに参加して問題を報告し、詳細な調査のためにリクエスト 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 にアップロードすることを推奨します。

1. ストレージとホスティング方法の選択

次のような方法を使用できます：

Object Storage Service (OSS) (推奨)：
- Alibaba Cloud OSS などの Object Storage Service を使用し、音声ファイルをバケットにアップロードしてパブリックアクセスに設定します。
- 利点：高い可用性、コンテンツ配信ネットワーク (CDN) アクセラレーションをサポート、管理が容易。
Web サーバー：
- Nginx や Apache などの HTTP/HTTPS アクセスをサポートする Web サーバーに音声ファイルを配置します。
- 利点：小規模なプロジェクトやローカルテストに適しています。
コンテンツ配信ネットワーク (CDN)：
- CDN 上で音声ファイルをホストし、CDN が提供する URL を通じてアクセスします。
- 利点：ファイル転送を高速化し、高同時実行シナリオに適しています。

2. 音声ファイルのアップロード

選択したストレージ方法に基づいて音声ファイルをアップロードします。例：

Object Storage Service：
- クラウドサービスプロバイダーのコンソールにログインし、バケットを作成します。
- 音声ファイルをアップロードし、ファイルの権限を「公開読み取り」に設定するか、一時的なアクセスリンクを生成します。
Web サーバー：
- サーバー上の指定されたディレクトリ (例：/var/www/html/audio/) に音声ファイルを配置します。
- ファイルが HTTP/HTTPS 経由でアクセスできることを確認します。

3. 公開アクセス可能な URL の生成

例：

Object Storage Service：
- ファイルのアップロード後、システムは自動的に公開アクセス URL を生成します。通常は https://<bucket-name>.<region>.aliyuncs.com/<file-name> の形式です。
- よりフレンドリなドメイン名が必要な場合は、カスタムドメイン名をバインドして HTTPS を有効にすることができます。
Web サーバー：
- ファイルアクセス URL は通常、サーバーアドレスにファイルパスを加えたものです。例：https://your-domain.com/audio/file.mp3。
CDN：
- CDN アクセラレーションを設定した後、CDN が提供する URL を使用します。例：https://cdn.your-domain.com/audio/file.mp3。

4. URL の可用性の確認

生成された URL が公開アクセス可能であることを確認します。例：

ブラウザで URL を開き、音声ファイルが再生できるか確認します。
curl や Postman などのツールを使用して、URL が正しい HTTP 応答 (状態コード 200) を返すか確認します。

SDK を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時的な URL は使用できません。

RESTful API を使用して OSS に保存されているファイルにアクセスする場合、oss:// プレフィックスを持つ一時的な URL を使用できます：

重要

一時的な URL は 48 時間有効で、有効期限が切れると使用できなくなります。本番環境では使用しないでください。
アップロード認証情報を取得するための API は 100 QPS に制限されており、スケールアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。
本番環境では、Alibaba Cloud OSS などの安定したストレージサービスを使用して、長期的なファイルの可用性を確保し、レート制限の問題を回避してください。

Q：認識結果を取得するのにどのくらい時間がかかりますか？

タスクが送信されると、PENDING 状態になります。キューイング時間はキューの長さとファイルの長さに依存し、正確に決定することはできませんが、通常は数分以内です。長い音声ファイルはより多くの処理時間を必要とします。

トラブルシューティング

エラーが発生した場合は、「エラーコード」の情報を参照してください。

Q：認識結果が音声の再生と同期しない場合はどうすればよいですか？

A：リクエストパラメーター timestamp_alignment_enabled を true に設定します。これにより、タイムスタンプアライメントが有効になり、認識結果が音声再生と同期します。

Q：継続的にポーリングしても結果を取得できないのはなぜですか？

これはレート制限が原因である可能性があります。クォータの引き上げをリクエストするには、開発者グループに参加してください。

Q：音声が認識されない (認識結果がない) のはなぜですか？

音声がフォーマットとサンプルレートの要件を満たしているか確認してください。
paraformer-v2 モデルを使用している場合は、language_hints パラメーターが正しく設定されているか確認してください。
上記を確認しても問題が解決しない場合は、カスタムホットワードを使用して特定の単語の認識を向上させることができます。

その他の質問

詳細については、GitHub のよくある質問をご参照ください。