Paraformer Python SDK を使用して、DashScope API で音声ファイルと動画ファイルの文字起こしを行います。
前提条件
クイックスタート
コアクラス (Transcription) は、2つの文字起こしアプローチをサポートしています。
- 非同期送信 + 同期待機:タスクを送信し、完了して結果が返るまでブロックします。
- 非同期送信 + 非同期ポーリング:タスクを送信し、いつでも結果をポーリングします。
非同期送信 + 同期待機
-
コアクラス (Transcription) の
async_callメソッドを呼び出し、リクエストパラメーターを設定します。- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。 - 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
-
コアクラス (Transcription) の
waitメソッドを呼び出し、タスクが完了するまで同期的に待機します。 タスクステータスには、PENDING、RUNNING、SUCCEEDED、FAILEDがあります。waitメソッドを呼び出すと、タスクがPENDINGまたはRUNNINGの間はブロックされます。タスクがSUCCEEDEDまたはFAILEDになると、waitは結果を返します。waitメソッドは TranscriptionResponse を返します。
クリックして完全な例を表示
クリックして完全な例を表示
非同期送信 + 非同期ポーリング
-
コアクラス (Transcription) の
async_callメソッドを呼び出し、リクエストパラメーターを設定します。- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。 - 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
-
タスクが完了するまで、コアクラス (Transcription) の
fetchメソッドをポーリングします。 ステータスがSUCCEEDEDまたはFAILEDになったらポーリングを停止し、結果を処理します。fetchメソッドは TranscriptionResponse を返します。
クリックして完全な例を表示
クリックして完全な例を表示
リクエストパラメーター
コアクラス (Transcription) の async_call メソッドにこれらのパラメーターを渡します。
| パラメーター | タイプ | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
| model | 文字列 | 必須 | Paraformer による音声ファイルおよび動画ファイルの文字起こしに使用するモデル名です。サポートされているモデルについては、リンク先をご参照ください。 | |
| file_urls | list[str] | 必須 | 音声ファイルと動画ファイルの文字起こし用 URL のリストです。HTTP および HTTPS プロトコルに対応しています。1 回のリクエストで指定できる URL は 1 つのみです。音声ファイルが Alibaba Cloud OSS に保存されている場合、SDK は oss:// プレフィックスを持つ一時的な URL をサポートしません。 | |
| vocabulary_id | 文字列 | 任意 | カスタム語彙の ID です。v2 シリーズのモデルに対応しており、言語設定が必要です。デフォルトでは無効になっています。詳細については、「カスタム語彙」をご参照ください。 | |
| channel_id | list[int] | [0] | 任意 | マルチトラック音声ファイルで認識するオーディオトラックのインデックスを指定します。インデックスは 0 から始まります。例えば、[0] は最初のトラックを認識することを意味し、[0, 1] は最初のトラックと 2 番目のトラックの両方を同時に認識することを意味します。このパラメーターを省略した場合、デフォルトで最初のトラックのみが処理されます。 |
| disfluency_removal_enabled | ブール値 | False | 任意 | フィラーワードをフィルターします。デフォルトでは無効になっています。 |
| timestamp_alignment_enabled | ブール値 | False | 任意 | タイムスタンプアライメントを有効にします。デフォルトでは無効になっています。 |
| special_word_filter | 文字列 | 任意 | 音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法を設定できます。このパラメーターが提供されない場合、システムは組み込みの禁止用語フィルタリングロジックを使用し、認識結果で Alibaba Cloud Model Studio 禁止用語リスト に一致する単語は、同じ長さの * に置き換えられます。このパラメーターが提供される場合、以下の禁止用語処理戦略を実装できます:
| |
| language_hints | list[str] | ["zh", "en"] | 任意 | 認識する音声の言語コードを指定します。このパラメーターは paraformer-v2 モデルにのみ適用されます。サポートされている言語コード:
|
| diarization_enabled | ブール値 | False | 任意 | 自動話者分離。デフォルトでは無効です。モノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。この機能が有効な場合、認識結果には異なる話者を区別するための speaker_id フィールドが含まれます。話者分離を有効にする場合、音声の長さが 2 時間を超えないようにすることを推奨します。超えると認識が失敗したり、タイムアウトしたりする可能性があります。 speaker_id の例については、「認識結果の説明」をご参照ください。 |
| speaker_count | 整数 | 任意 | 参考話者数です。値の範囲は 2~100 の整数です。diarization_enabled が true の場合にのみ有効です。デフォルトでは自動的に決定されます。このパラメーターはアルゴリズムのヒントとして使用されますが、正確な数を保証するものではありません。 |
応答
TranscriptionResponse
TranscriptionResponse には、task_id、task_status、および output プロパティに実行結果が含まれます。TranscriptionOutput をご参照ください。
クリックして TranscriptionResponse の構造例を表示
クリックして TranscriptionResponse の構造例を表示
async_call が返す TranscriptionResponse には、submit_time や scheduled_time は含まれません。submit_time と scheduled_time を取得するには、async_call() の戻り値を直接使用するのではなく、wait() または fetch() メソッドを使用してください。wait() または fetch() が返す TranscriptionResponse:パラメーター | 説明 |
|---|---|
status_code | HTTP リクエストのステータスコード。 |
code |
|
message |
|
task_id | タスク ID。 |
task_status | タスクステータス。 ステータスには タスクに複数のサブタスクが含まれる場合、いずれかのサブタスクが成功すると、タスク全体のステータスは |
results | サブタスクの音声認識結果。 |
subtask_status | サブタスクのステータス。 ステータスには |
file_url | 認識する音声ファイルの URL。 |
transcription_url | 音声認識結果に対応する URL。 音声認識結果は JSON ファイルとして保存されます。 |
TranscriptionOutput
TranscriptionOutput オブジェクトは、タスクの実行結果を含む、TranscriptionResponse オブジェクトの output プロパティです。
クリックして TranscriptionOutput の構造例を表示
クリックして TranscriptionOutput の構造例を表示
- PENDING ステータス
- RUNNING ステータス
- SUCCEEDED ステータス
- FAILED ステータス
パラメーター | 説明 |
|---|---|
code | エラーコード。 |
message | エラーメッセージ。 |
task_id | タスク ID。 |
task_status | タスクステータス。 ステータスには タスクに複数のサブタスクが含まれる場合、いずれかのサブタスクが成功すると、タスク全体のステータスは |
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 | 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 | 単語の後に予測される句読点 (もしあれば)。 |
API リファレンス
コアクラス (Transcription)
Transcription クラスをインポートします: from dashscope.audio.asr import Transcription。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
| async_call | 音声認識タスクを非同期で送信します。このメソッドは TranscriptionResponse を返します。 | |
| wait | 非同期タスクが完了するまで (ステータスが SUCCEEDED または FAILED になるまで)、現在のスレッドをブロックします。このメソッドは TranscriptionResponse を返します。 | |
| fetch | 非同期タスクの実行結果を照会します。このメソッドは TranscriptionResponse を返します。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加して問題を報告し、さらなる調査のためにリクエスト ID を提供してください。
タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を判断するには、subtask_status フィールドを確認する必要があります。
エラー応答の例:
その他の例
GitHub でその他の例をご覧ください。
よくある質問
機能
Q:Base64 エンコードされた音声をサポートしていますか?
いいえ。Base64 エンコードされた音声はサポートされていません。パブリックにアクセス可能な URL を介してアクセスできる音声のみがサポートされています。バイナリストリームや直接のローカルファイル認識はサポートされていません。
Q:音声ファイルをパブリックにアクセス可能な URL として提供するにはどうすればよいですか?
一般的に、以下の手順に従います (これは一般的なアプローチであり、詳細はストレージ製品によって異なります。音声を Alibaba Cloud OSS にアップロードすることを推奨します):
1. ストレージとホスティング方法を選択する
1. ストレージとホスティング方法を選択する
-
Object Storage Service (推奨):
- クラウドプロバイダーのオブジェクトストレージサービス (例:Alibaba Cloud OSS) を使用して音声ファイルをバケットにアップロードし、パブリックアクセスに設定します。
- 利点:高可用性、CDN アクセラレーションのサポート、簡単な管理。
-
Web サーバー:
- HTTP/HTTPS アクセスをサポートする Web サーバー (Nginx や Apache など) に音声ファイルを配置します。
- 利点:小規模プロジェクトやローカルテストに適しています。
-
コンテンツデリバリーネットワーク (CDN):
- CDN に音声ファイルをホストし、CDN が提供する URL を介してアクセスします。
- 利点:ファイル配信の高速化、高同時実行シナリオに適しています。
2. 音声ファイルをアップロードする
2. 音声ファイルをアップロードする
-
Object Storage Service:
- クラウドプロバイダーのコンソールにログインし、バケットを作成します。
- 音声ファイルをアップロードし、ファイルの権限を「パブリック読み取り」に設定するか、一時的なアクセスリンクを生成します。
-
Web サーバー:
- サーバーの指定されたディレクトリ (例:
/var/www/html/audio/) に音声ファイルを配置します。 - ファイルが HTTP/HTTPS を介してアクセス可能であることを確認します。
- サーバーの指定されたディレクトリ (例:
3. パブリックにアクセス可能な URL を生成する
3. パブリックにアクセス可能な URL を生成する
-
Object Storage Service:
- アップロード後、システムは自動的にパブリックアクセス URL を生成します (通常は
https://<bucket-name>.<region>.aliyuncs.com/<file-name>の形式)。 - よりユーザーフレンドリなドメインが必要な場合は、カスタムドメインをバインドして HTTPS を有効にすることができます。
- アップロード後、システムは自動的にパブリックアクセス URL を生成します (通常は
-
Web サーバー:
- ファイルアクセス URL は通常、サーバーアドレスとファイルパスを組み合わせたものです (例:
https://your-domain.com/audio/file.mp3)。
- ファイルアクセス URL は通常、サーバーアドレスとファイルパスを組み合わせたものです (例:
-
CDN:
- CDN アクセラレーションを設定した後、CDN が提供する URL を使用します (例:
https://cdn.your-domain.com/audio/file.mp3)。
- CDN アクセラレーションを設定した後、CDN が提供する URL を使用します (例:
4. URL のアクセシビリティを確認する
4. URL のアクセシビリティを確認する
- ブラウザで URL を開き、音声ファイルが再生できるか確認します。
- ツール (
curlや Postman など) を使用して、URL が正しい HTTP 応答 (状態コード 200) を返すか確認します。
oss:// プレフィックスを持つ一時的な URL はサポートされません。
RESTful API を使用する場合、音声ファイルが Alibaba Cloud OSS に保存されている場合、oss:// プレフィックスを持つ一時的な URL はサポートされます:
- 一時的な URL は 48 時間有効で、有効期限が切れると使用できません。本番環境では使用しないでください。
- アップロード認証情報を取得するための API は 100 QPS に制限されており、スケーリングアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。
- 本番環境では、OSS などの安定したストレージサービスを使用して、長期的なファイルの可用性を確保し、レート制限の問題を回避してください。
Q:認識結果を取得するのにどれくらい時間がかかりますか?
送信後、タスクはキューイング中 (PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。しばらくお待ちください。長い音声ファイルはより多くの処理時間を必要とします。
トラブルシューティング
エラーについては、「エラーコード」をご参照ください。
Q:認識結果が音声の再生と同期しない場合はどうすればよいですか?
リクエストパラメーターの timestamp_alignment_enabled を true に設定してタイムスタンプキャリブレーションを有効にします。これにより、認識結果が音声の再生と同期します。
Q:タスクで InvalidFile.DownloadFailed エラーが返される場合はどうすればよいですか?
ファイル URL にスペースや中国語などの非 ASCII 文字が含まれていないか確認してください。ファイル名にスペースが含まれる場合 (例:my audio recording.mp4)、各スペースを %20 に置き換え、ファイル名を URL エンコードしてから file_urls パラメーターに渡してください。
Q:継続的なポーリング後も結果を取得できませんか?
これはレート制限が原因である可能性があります。しばらくお待ちください。容量拡張が必要な場合は、開発者コミュニティ に参加して申請してください。Q:なぜ認識結果がないのですか (音声を認識できない)?
- 音声が要件 (フォーマット、サンプリングレート) を満たしているか確認してください。
paraformer-v2モデルを使用している場合は、language_hintsの設定が正しいか確認してください。- 上記のいずれでも問題が解決しない場合は、カスタムホットワードを使用して特定の単語の認識を向上させることができます。