すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:Java SDK

最終更新日:Mar 25, 2026

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 を指定できます。

  • 対応音声フォーマット

    aacamraviflacflvm4amkvmovmp3mp4mpegoggopuswavwebmwmawmv

    重要

    音声および動画フォーマットは多種多様であり、すべてを網羅的にテストすることは技術的に困難です。この API では、すべてのフォーマットが正しく認識されることを保証できません。ご自身のファイルでテストを行い、期待通りの音声認識結果が得られることを確認してください。

  • 音声サンプルレート: 任意

  • 音声ファイルサイズおよび再生時間

    最大ファイルサイズは 2 GB、最大再生時間は 12 時間です。これらの制限を超えるファイルの場合は、アップロード前に分割または圧縮を行ってください。ファイル前処理のベストプラクティスについては、「ファイル転写効率を向上させるための動画ファイル前処理(音声ファイル認識シナリオ向け)」をご参照ください。

  • バッチ処理対象の音声ファイル数

    1 回のリクエストで最大 100 個のファイル URL を指定できます。

  • 認識可能な言語: fun-asr は中国語および英語をサポートします。fun-asr-mtl-2025-08-25 は中国語、広東語、英語、日本語、タイ語、ベトナム語、インドネシア語をサポートします。

クイックスタート

コアクラス(Transcription)は、タスクを非同期で送信するインターフェイス、タスク完了を同期で待機するインターフェイス、およびタスク結果を非同期で照会するインターフェイスを提供します。以下の 2 つの方法で音声ファイル認識を実行できます:

  • 非同期送信+同期待機:タスクを送信し、タスクが完了するまで現在のスレッドをブロックして認識結果を取得します。

  • 非同期送信+非同期照会:タスクを送信した後、必要に応じて照会インターフェイスを呼び出してタスク結果を取得します。

非同期送信+同期待機

image
  1. リクエストパラメーターを設定します。

  2. コアクラス(Transcription)のインスタンスを作成します。

  3. コアクラス(Transcription)asyncCall メソッドを呼び出して、タスクを非同期で送信します。

    説明
    • タスクは送信後に PENDING ステータスになります。キュー待ち時間(通常数分)はキュー長およびファイル再生時間によって異なります。処理が開始されると、音声認識は大幅に高速化されます。

    • 認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限が切れます。有効期限が切れた後は、タスクを照会できなくなります。

  4. コアクラス(Transcription)wait メソッドを呼び出して、タスク完了を同期で待機します。

    タスクステータスには PENDINGRUNNINGSUCCEEDEDFAILED があります。wait インターフェイスは PENDING/RUNNING の状態でブロックし、タスクが SUCCEEDED または FAILED になった時点でブロックを解除し、タスク実行結果を返します。

    waitタスク実行結果(TranscriptionResult) を返します。

完全な例を表示するには、クリックしてください

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // 以下の URL はシンガポールリージョン用です。北京リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください。
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // 音声認識リクエストパラメーターを作成します。
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // シンガポールリージョンおよび北京リージョンの API キーは異なります。API キーの取得方法については、「https://www.alibabacloud.com/help/en/model-studio/get-api-key」をご参照ください。
                        // 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // ここでは例として fun-asr を使用しています。必要に応じてモデル名を変更できます。モデル一覧については、「https://www.alibabacloud.com/help/en/model-studio/models」をご参照ください。
                        .fileUrls(
                                Arrays.asList(
                                        "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"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // 音声認識リクエストを送信します。
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // タスク完了をブロックして待機し、結果を取得します。
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // 結果を出力します。
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

非同期送信+非同期照会

image
  1. リクエストパラメーターを設定します。

  2. コアクラス(Transcription)のインスタンスを作成します。

  3. コアクラス(Transcription)asyncCall メソッドを呼び出して、タスクを非同期で送信します。

    説明
    • タスクは送信後に PENDING ステータスになります。キュー待ち時間(通常数分)はキュー長およびファイル再生時間によって異なります。処理が開始されると、音声認識は大幅に高速化されます。

    • 認識結果およびダウンロード URL は、タスク完了後 24 時間で有効期限が切れます。有効期限が切れた後は、タスクを照会できなくなります。

  4. コアクラス(Transcription)fetch メソッドを繰り返し呼び出して、最終タスク結果を取得します。

    タスクステータスが SUCCEEDED または FAILED の場合、ポーリングを停止して結果を処理します。

    fetchタスク実行結果(TranscriptionResult) を返します。

完全な例を表示するには、クリックしてください

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // 以下の URL はシンガポールリージョン用です。北京リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください。
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // 音声認識リクエストパラメーターを作成します。
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // シンガポールリージョンおよび北京リージョンの API キーは異なります。API キーの取得方法については、「https://www.alibabacloud.com/help/en/model-studio/get-api-key」をご参照ください。
                        // 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // ここでは例として fun-asr を使用しています。必要に応じてモデル名を変更できます。モデル一覧については、「https://www.alibabacloud.com/help/en/model-studio/models」をご参照ください。
                        .fileUrls(
                                Arrays.asList(
                                        "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"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // 音声認識リクエストを送信します。
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // タスク実行結果を取得するまでポーリングします。
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }
            // 結果を出力します。
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

リクエストパラメーター

TranscriptionParam のチェーンメソッドを使用してリクエストパラメーターを設定します。

例を表示するには、クリックしてください

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .fileUrls(
          Arrays.asList(
                  "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"))
  .build();

パラメーター

デフォルト値

必須

説明

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 文字列である必要があります:

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

JSON フィールドの説明:

  • filter_with_signed

    • 型:オブジェクト

    • 必須:いいえ

    • 説明:アスタリスク(*)で置き換えられる禁止用語のリストを設定します。認識結果で一致した単語は、同じ長さのアスタリスク(*)に置き換えられます。

    • 例:上記の JSON 例に基づき、「Help me test this piece of code」という音声認識結果は、「Help me **** this piece of code」となります。

    • 内部フィールド:

      • word_list:置き換え対象の禁止用語を列挙した文字列配列

  • filter_with_empty

    • 型:オブジェクト

    • 必須:いいえ

    • 説明:認識結果から完全に削除(フィルター)される禁止用語のリストを設定します。認識結果で一致した単語は完全に削除されます。

    • 例:上記の JSON 例に基づき、「Is the game about to start?」という音声認識結果は、「Is the game about to?」となります。

    • 内部フィールド:

      • word_list:完全に削除(フィルター)される禁止用語を列挙した文字列配列

  • system_reserved_filter

    • 型:ブール値

    • 必須:いいえ

    • デフォルト値:true

    • 説明: システムの事前設定済み禁止用語ルールを有効にするかどうかを指定します。true に設定すると、システムの組み込み禁止用語フィルタリング処理も有効になります。認識結果でAlibaba Cloud Model Studio 禁止用語リストと一致する単語は、同じ長さのアスタリスク (*) に置き換えられます。

diarizationEnabled

Boolean

false

いいえ

自動スピーカーダイアライゼーションはデフォルトで無効です。この機能はシングルチャンネル音声にのみ適用され、マルチチャンネル音声には対応していません。

有効にした場合、認識結果にはスピーカーを識別するための speaker_id フィールドが含まれます。

speaker_id の例については、「認識結果の説明」をご参照ください。

speakerCount

Integer

-

いいえ

このパラメーターは、スピーカー数のヒント(2~100 の整数)です。diarizationEnabled が true の場合にのみ有効です。

デフォルトでは、スピーカー数は自動検出されます。このパラメーターはアルゴリズムを補助するものであり、正確なスピーカー数を保証するものではありません。

language_hints

String[]

-

いいえ

認識対象の言語コードです。自動言語検出を行う場合は、未設定のままにしてください。

システムは配列の最初の値のみを読み取り、追加の値は無視されます。

各モデルでサポートされる言語コードは以下のとおりです:

  • fun-asr、fun-asr-2025-11-07:

    • zh:中国語

    • en:英語

    • ja:日本語

  • fun-asr-2025-08-25:

    • zh:中国語

    • en:英語

  • fun-asr-mtl、fun-asr-mtl-2025-08-25:

    • zh:中国語

    • en:英語

    • ja:日本語

    • ko:韓国語

    • vi:ベトナム語

    • id:インドネシア語

    • th:タイ語

    • ms:マレー語

    • tl:フィリピン語

    • ar:アラビア語

    • hi:ヒンディー語

    • bg:ブルガリア語

    • hr:クロアチア語

    • cs:チェコ語

    • da:デンマーク語

    • nl:オランダ語

    • et:エストニア語

    • fi:フィンランド語

    • el:ギリシャ語

    • hu:ハンガリー語

    • ga:アイルランド語

    • lv:ラトビア語

    • lt:リトアニア語

    • mt:マルタ語

    • pl:ポーランド語

    • pt:ポルトガル語

    • ro:ルーマニア語

    • sk:スロバキア語

    • sl:スロベニア語

    • sv:スウェーデン語

説明

language_hints は、parameter または parameters メソッドを TranscriptionParam インスタンスに対して呼び出して設定する必要があります:

パラメーターによる設定

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .parameter("language_hints", new String[]{"zh"})
  .build();

parameters メソッドで設定

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .parameters(Collections.singletonMap("language_hints", new String[]{"zh"}))
  .build();

apiKey

文字列

-

いいえ

ご利用の API キー。API キーを環境変数として設定済みの場合、コード内で設定する必要はありません。そうでない場合は、コード内で設定する必要があります。

応答

タスク実行結果(TranscriptionResult

TranscriptionResult は、現在のタスク実行結果をカプセル化します。

インターフェイス/メソッド

パラメーター

戻り値

説明

public String getRequestId()

なし

requestId

リクエスト ID を取得します。

public String getTaskId()

なし

taskId

タスク ID を取得します。

public TaskStatus getTaskStatus()

なし

TaskStatus(タスクステータス)

タスクステータスを取得します。

TaskStatus は列挙クラスです。関心のあるステータスは PENDINGRUNNINGSUCCEEDEDFAILED のみです。

説明

タスクに複数のサブタスクが含まれる場合、少なくとも 1 つのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を確認するには、subtask_status フィールドを確認する必要があります。

public List<TranscriptionTaskResult> getResults()

なし

サブタスク実行結果(TranscriptionTaskResult)

サブタスク実行結果(TranscriptionTaskResult) を取得します。

各タスクは 1 つ以上の音声ファイルを認識します。異なる音声ファイルは異なるサブタスクで処理されます。したがって、各タスクには 1 つ以上のサブタスクが対応します。

public JsonObject getOutput()

なし

JSON 形式のタスク実行結果

タスク実行結果を取得します。

結果は JSON 形式です。getOutput インターフェイスを使用してタスク実行結果を取得する場合、受信後に JSON データを解析する必要があります。

JSON の例を表示するには、クリックしてください

正常な例

{
    "task_id":"0795ff8c-b666-4e91-bb8b-xxx",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 16:12:09.109",
    "scheduled_time":"2025-02-13 16:12:09.128",
    "end_time":"2025-02-13 16:12:10.189",
    "results":[
        {
            "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/16%3A12/34604a7b-579a-4223-8797-5116a49b07ec-1.json?Expires=1739520730&OSSAccessKeyId=yourOSSAccessKeyId&Signature=tMqyH56oB5rDW9%2FFqD8Yo%2F3WaPk%3D",
            "subtask_status":"SUCCEEDED"
        },
        {
            "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/16%3A12/3baafe5f-d09d-46c6-8b01-724927670edb-1.json?Expires=1739520730&OSSAccessKeyId=yourOSSAccessKeyId&Signature=BF7vPxlsJN9hkJlY%2BLReezxOwK8%3D",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":2,
        "FAILED":0
    }
}

異常な例

code はエラーコード、message はエラーメッセージです。これらの 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
    }
}

サブタスク実行結果(TranscriptionTaskResult

TranscriptionTaskResult は、サブタスク実行結果をカプセル化します。サブタスクとは、単一の音声ファイルの認識を指します。

インターフェイス/メソッド

パラメーター

戻り値

説明

public String getFileUrl()

なし

認識対象の音声ファイルの URL

認識対象の音声ファイルの URL を取得します。

public String getTranscriptionUrl()

なし

認識結果の URL

認識結果の URL を取得します。この URL は 24 時間有効です。有効期限が切れた後は、以前の照会から取得した URL を使用してタスクを照会したり、結果をダウンロードしたりすることはできません。

認識結果は JSON ファイルとして保存されます。このファイルは URL からダウンロードすることも、HTTP リクエストで直接その内容を読み取ることもできます。

JSON データ内の各フィールドの意味については、「認識結果の説明」をご参照ください。

public TaskStatus getSubTaskStatus()

なし

TaskStatus(サブタスクステータス)

サブタスクステータスを取得します。

TaskStatus は列挙クラスです。関心のあるステータスは PENDINGRUNNINGSUCCEEDEDFAILED のみです。

public String getMessage()

なし

タスク実行プロセスからの主要な情報。空の場合があります。

タスク実行プロセスからの主要な情報を取得します。

タスクが失敗した場合、この内容を確認して原因を分析できます。

認識結果の説明

認識結果は 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_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 を使用して作成します。

例を表示するには、クリックしてください

// 音声認識リクエストパラメーターを作成します。
TranscriptionParam param =
        TranscriptionParam.builder()
                // API キーを環境変数として設定していない場合は、apiKey をご自身の API キーに置き換えてください。
                //.apiKey("apikey")
                .model("fun-asr")
                .fileUrls(
                        Arrays.asList(
                                "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"))
                .build();
try {
    Transcription transcription = new Transcription();
    // 音声認識リクエストを送信します。
    TranscriptionResult result = transcription.asyncCall(param);
    System.out.println("RequestId: " + result.getRequestId());
    TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());
    
} catch (Exception e) {
    System.out.println("error: " + e);
}

インターフェイス/メソッド

パラメーター

戻り値

説明

public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)
  • paramTranscriptionParam インスタンス

  • taskId:タスク ID

TranscriptionQueryParam インスタンス

TranscriptionQueryParam インスタンスを作成します。

コアクラス(Transcription

Transcription は、import com.alibaba.dashscope.audio.asr.transcription.*; 文でインポートできます。このクラスの主要なインターフェイスは以下のとおりです:

インターフェイス/メソッド

パラメーター

戻り値

説明

public TranscriptionResult asyncCall(TranscriptionParam param)

param:音声認識パラメーター(TranscriptionParam インスタンス)

タスク実行結果(TranscriptionResult)

音声認識タスクを非同期で送信します。

public TranscriptionResult wait(TranscriptionQueryParam queryParam)

queryParamTranscriptionQueryParam インスタンス

タスク実行結果(TranscriptionResult)

非同期タスクが完了するまで(タスクステータスが SUCCEEDED または FAILED になるまで)現在のスレッドをブロックします。

public TranscriptionResult fetch(TranscriptionQueryParam queryParam)

queryParamTranscriptionQueryParam インスタンス

タスク実行結果(TranscriptionResult)

現在のタスクの実行結果を非同期で照会します。

エラーコード

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

タスクに複数のサブタスクが含まれる場合、少なくとも 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) にアップロードすることを推奨します。

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

例としては、以下が挙げられます。

  • Object Storage Service (推奨):

    • クラウドプロバイダーのオブジェクトストレージサービス ( OSS など) を使用します。オーディオファイルをバケットにアップロードし、そのアクセス権限を公開に設定します。

    • 利点: 高可用性、CDN アクセラレーションのサポート、容易な管理。

  • Web サーバー:

    • HTTP/HTTPS アクセスをサポートする Web サーバー (Nginx や Apache など) にオーディオファイルを配置します。

    • 利点: 小規模なプロジェクトやローカルテストに適しています。

  • コンテンツデリバリーネットワーク (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 に制限されており、スケールアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。

  • 本番環境の場合、長期的なファイルの可用性を確保し、レート制限の問題を回避するために、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