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

Alibaba Cloud Model Studio:Java SDK

最終更新日:Mar 25, 2026

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)

✅ デフォルトで有効、設定不要

✅ デフォルトで有効、設定不要

認識言語の指定

language_hints パラメーターで指定可能

制限事項

本サービスは、ローカルの音声・動画ファイルの直接アップロードおよび 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 を指定できます。

  • 音声フォーマット

    aacamraviflacflvm4amkvmovmp3mp4mpegoggopuswavwebmwmawmv

    重要

    すべての音声・動画フォーマットおよびそのバリエーションについて、API が正確な認識を保証することはできません(すべての可能性をテストすることが現実的ではないため)。ご利用のファイルが期待通りの音声認識結果を生成することを確認するため、事前にテストを行うことを推奨します。

  • 音声のサンプルレート

    サンプルレートはモデルによって異なります。

    • paraformer-v2:任意のサンプルレートをサポート

    • paraformer-8k-v2:8 kHz のみをサポート

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

    音声ファイルのサイズは 2 GB を、再生時間は 12 時間を超えてはなりません。

    これらの制限を超えるファイルを処理するには、前処理によりファイルサイズを縮小してください。「音声ファイル認識シナリオ向けの動画ファイルの前処理による文字起こし効率の向上」をご参照ください。

  • バッチ処理における音声ファイル数

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

  • 認識可能な言語

    モデルによって異なります。

    • paraformer-v2:

      • 中国語(標準語および各種方言):上海語、呉語、閩南語、東北官話、甘粛話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、広東語

      • 英語

      • 日本語

      • 韓国語

    • paraformer-8k-v2:中国語のみをサポート

クイックスタート

コアクラス(Transcription) は、非同期でタスクを送信するメソッド、同期でタスク完了を待機するメソッド、非同期でタスク実行結果を照会するメソッドを提供します。音声ファイル認識は、以下の 2 つの方法のいずれかで実行できます。

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

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

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

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

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

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

    説明
    • ファイル文字起こしサービスは、API 経由で送信されたタスクをベストエフォート方式で処理します。タスクを送信すると、キューイング(PENDING)状態に入ります。キューイング時間はキューの長さおよびファイルの再生時間に依存し、正確には特定できませんが、通常は数分以内です。タスクの処理が開始されると、音声認識プロセスはリアルタイム再生速度の数百倍の速さで実行されます。

    • 認識結果およびダウンロード URL は、タスク完了後 24 時間有効です。この期間を過ぎると、タスクの照会や結果のダウンロードができなくなります。

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

    タスクのステータスは PENDINGRUNNINGSUCCEEDEDFAILED のいずれかになります。wait 呼び出しは、タスクステータスが PENDING または RUNNING の間はブロックされます。タスクステータスが SUCCEEDED または FAILED になると、wait 呼び出しはブロック解除され、タスク実行結果を返します。

    wait メソッドは、タスク実行結果(TranscriptionResult) を返します。

完全な例を表示

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

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // 文字起こしリクエストパラメーターを作成します。
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // API キーを環境変数として設定していない場合は、「apikey」を実際の API キーに置き換えてください。
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .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(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

非同期タスク送信 + 非同期でタスク実行結果を照会

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

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

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

    説明
    • ファイル文字起こしサービスは、API 経由で送信されたタスクをベストエフォート方式で処理します。タスクを送信すると、キューイング(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.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // 文字起こしリクエストパラメーターを作成します。
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // API キーを環境変数として設定していない場合は、「apikey」を実際の API キーに置き換えてください。
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .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(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

リクエストパラメーター

TranscriptionParam クラスのチェーンメソッドを使用して、リクエストパラメーターを構成できます。

例を表示

TranscriptionParam param = TranscriptionParam.builder()
  .model("paraformer-v2")
  // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
  .parameter("language_hints", new String[]{"zh", "en"})
  .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

-

はい

音声・動画ファイルの文字起こしに使用する 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 文字列である必要があります。

{
  "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 code」という音声認識結果は「Help me ** this code」となります。

    • 内部フィールド:

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

  • filter_with_empty

    • 型:オブジェクト

    • 必須:いいえ

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

    • 例:前述の 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

String[]

["zh", "en"]

いいえ

認識対象の音声の言語コードを指定します。

このパラメーターは paraformer-v2 モデルでのみ適用可能です。

対応言語コード:

  • zh:中国語

  • en:英語

  • ja:日本語

  • yue:広東語

  • ko:韓国語

  • de:ドイツ語

  • fr:フランス語

  • ru:ロシア語

説明

language_hints パラメーターは、parameter メソッドまたは parameters メソッドを使用して TranscriptionParam インスタンスで設定する必要があります。

parameter メソッドを使用した設定

TranscriptionParam param = TranscriptionParam.builder()
  // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
  .model("paraformer-v2")
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();

parameters メソッドを使用した設定

TranscriptionParam param = TranscriptionParam.builder()
  // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
  .model("paraformer-v2")
  .parameters(Collections.singletonMap("language_hints", new String[]{"zh", "en"}))
  .build();

diarizationEnabled

Boolean

false

いいえ

自動スピーカーダイアライゼーションです。この機能はデフォルトで無効です。

この機能はモノラル音声にのみ適用可能です。マルチチャンネル音声ではスピーカーダイアライゼーションはサポートされません。

この機能を有効にすると、認識結果に speaker_id フィールドが表示され、異なるスピーカーを区別できます。

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

speakerCount

Integer

-

いいえ

スピーカー数の参照値です。値は 2 ~ 100 の整数である必要があります。

このパラメーターは、スピーカーダイアライゼーションが有効化された場合(diarizationEnabled を true に設定)にのみ有効です。

デフォルトでは、スピーカー数は自動的に決定されます。このパラメーターを設定した場合、アルゴリズムが指定されたスピーカー数を出力するよう試みる補助となりますが、必ずしもその数が出力されることを保証するものではありません。

apiKey

String

-

いいえ

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

応答結果

タスク実行結果(TranscriptionResult

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

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

パラメーター

戻り値

説明

public String getRequestId()

なし

requestId

リクエスト ID を返します。

public String getTaskId()

なし

taskId

タスク ID を返します。

public TaskStatus getTaskStatus()

なし

TaskStatus(タスクステータス)

タスクステータスを返します。

TaskStatus は列挙クラスです。以下の 4 つのステータスに注意してください:PENDINGRUNNINGSUCCEEDEDFAILED

説明

タスクに複数のサブタスクが含まれる場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を確認するには、subtask_status フィールドを確認してください。

public List<TranscriptionTaskResult> getResults()

なし

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

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

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

public JsonObject getOutput()

なし

JSON 形式のタスク実行結果

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

この結果は JSON 形式です。getOutput インターフェイスを介してタスク実行結果を取得する場合、結果を取得した後に自分で解析する必要があります。

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()

なし

認識対象の音声ファイルへのリンク

認識対象の音声ファイルへのリンクを返します。

public String getTranscriptionUrl()

なし

認識結果へのリンク

認識結果へのリンクを返します。このリンクは 24 時間有効です。この期間を過ぎると、以前に照会した URL を使用してタスクの照会や結果のダウンロードができなくなります。

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

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

public TaskStatus getSubTaskStatus()

なし

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

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

TaskStatus は列挙クラスです。以下の 4 つのステータスに注意してください: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

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 静的メソッドを使用して作成できます。

例を表示

// 文字起こしリクエストパラメーターを作成します。
TranscriptionParam param =
        TranscriptionParam.builder()
                // API キーを環境変数として設定していない場合は、「apikey」を実際の API キーに置き換えてください。
                //.apiKey("apikey")
                .model("paraformer-v2")
                // 「language_hints」パラメーターは paraformer-v2 モデルでのみサポートされています。
                .parameter("language_hints", new String[]{"zh", "en"})
                .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)

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

エラーコード

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

問題が解決しない場合は、開発者グループ に参加して問題を報告し、調査のために 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 への音声ファイルのアップロード を推奨します。

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

以下の方法をご利用いただけます。

  • Object Storage Service(OSS)(推奨):

    • Object Storage Service(例: Alibaba Cloud OSS)を使用し、オーディオファイルをバケットにアップロードして、パブリックアクセスを設定します。

    • メリット:高い可用性、コンテンツ配信ネットワーク(CDN)による高速化、管理が容易

  • Web サーバー:

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

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

  • コンテンツ配信ネットワーク(CDN):

    • CDN に音声ファイルをホストし、CDN が提供する URL を介してアクセスします。

    • メリット:ファイル転送の高速化、高い同時実行性を要するシナリオに適しています。

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

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

  • Object Storage Service:

    • クラウド サービス プロバイダーのコンソールにログインし、バケットを作成します。

    • 音声ファイルをアップロードし、ファイル権限を「公開読み取り(public-read)」に設定するか、一時アクセスリンクを生成します。

  • 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:認識結果が音声の再生と同期していない場合、どうすればよいですか?

リクエストパラメーター timestampAlignmentEnabledtrue に設定して、タイムスタンプ配置機能を有効化することで、認識結果を音声の再生と同期させることができます。

Q:継続的なポーリングを行っても結果が取得できないのはなぜですか?

これはレート制限による可能性があります。クォータの増加を依頼するには、開発者グループ に参加してください。

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

  • 音声がフォーマットおよびサンプルレートの要件を満たしているか確認してください。

  • paraformer-v2 モデルを使用している場合、language_hints パラメーターが正しく設定されているか確認してください。

その他の質問

詳細については、「GitHub 上の QA」をご参照ください。