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

Alibaba Cloud Model Studio:Paraformer 非リアルタイム音声認識 Java SDK

最終更新日:Oct 11, 2026

このトピックでは、Paraformer 非リアルタイム音声認識 Java SDK のパラメーターとインターフェイスの詳細について説明します。

重要Alibaba Cloud Model Studio は、中国 (北京) リージョン向けにワークスペース専用のドメインをリリースしました。この新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。 dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com への移行を推奨します。

{WorkspaceId} を実際の ワークスペース ID に置き換えてください。既存のドメインも引き続き完全に機能します。

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

ユーザーガイド:非リアルタイム音声認識

前提条件

サービスを有効化し、API キーを取得していること。コードの漏洩によるセキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、API キーを環境変数として設定してください。

注記サードパーティのアプリケーションやユーザーに一時的なアクセス権を付与する必要がある場合や、機密データへのアクセスや削除などの高リスク操作を厳密に制御したい場合は、一時的な認証トークンの使用を推奨します。

長期的な API キーと比較して、一時的な認証トークンは有効期間が短く (60 秒)、セキュリティが高いため、一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減します。

使用方法:コード内で、認証に元々使用していた API キーを取得した一時的な認証トークンに置き換えます。

クイックスタート

コアクラス (Transcription) は、タスクを非同期に送信し、タスクの完了を同期的に待機し、タスク結果を非同期にクエリするためのインターフェイスを提供します。非リアルタイム音声認識には、次の 2 つの呼び出し方法を使用できます。

  • 非同期送信 + 同期待機:タスクを送信した後、タスクが終了して認識結果が取得されるまで現在のスレッドをブロックします。
  • 非同期送信 + 非同期クエリ:タスクを送信した後、クエリインターフェイスを呼び出すことでいつでもタスク結果を照会できます。

非同期送信 + 同期待機

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

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

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

    注記

    • ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。
    • 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
  4. コアクラス (Transcription) の wait メソッドを呼び出して、タスクが終了するのを同期的に待機します。

    タスクステータスには PENDING、RUNNING、SUCCEEDED、FAILED があります。タスクが PENDING または RUNNING 状態の場合、wait インターフェイスはブロックされます。タスクが 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) {
        // 以下の設定は中国 (北京) リージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // 文字起こしリクエストパラメーターを作成
        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(
                                        "{YOUR_AUDIO_URL}"))
                        .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);
    }
}

非同期送信 + 非同期クエリ

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

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

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

    注記

    • ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。
    • 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
  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) {
        // 以下の設定は中国 (北京) リージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // 文字起こしリクエストパラメーターを作成
        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(
                                        "{YOUR_AUDIO_URL}"))
                        .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(
                  "{YOUR_AUDIO_URL}"))
  .build();
パラメーター型デフォルト必須説明

model

String

はい

音声/動画ファイルの文字起こしに使用する Paraformer モデル名を指定します。詳細については、「サポートされているモデル」をご参照ください。

fileUrls

List<String>

はい

文字起こし対象の音声/動画ファイルの URL リスト。HTTP/HTTPS プロトコルをサポートします。リクエストごとに 1 つの URL のみがサポートされます。

音声ファイルが Alibaba Cloud OSS に保存されている場合、SDK は oss:// プレフィックスを持つ一時的な URL をサポートしません。

vocabularyId

String

いいえ

最新のホットワード ID。言語設定を持つ最新の v2 シリーズモデルをサポートします。この ID に関連付けられたホットワードが、この音声認識で有効になります。デフォルトでは無効です。使用方法については、「カスタムホットワード」をご参照ください。

channelId

List<Integer>

[0]

いいえ

マルチトラック音声ファイルで認識するオーディオトラックのインデックスを指定します。インデックスは 0 から始まります。例えば、[0] は最初のトラックを認識することを意味し、[0, 1] は最初のトラックと 2 番目のトラックの両方を同時に認識することを意味します。このパラメーターを省略した場合、デフォルトで最初のトラックのみが処理されます。

重要指定された各トラックは独立して課金されます。例えば、1 つのファイルに対して [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

    • 型:Object。

    • 必須:いいえ。

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

    • 例:上記の JSON を使用すると、「Help me test this code」の音声認識結果は「Help me **** this code」になります。

    • 内部フィールド:

      • word_list:置き換える禁止用語をリストする文字列の配列。
  • filter_with_empty

    • 型:Object。

    • 必須:いいえ。

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

    • 例:上記の JSON を使用すると、「The game is about to start, right?」の音声認識結果は「The game is about to, right?」になります。

    • 内部フィールド:

      • word_list:完全に削除 (フィルター) する禁止用語をリストする文字列の配列。
  • system_reserved_filter

    • 型:Boolean。
    • 必須:いいえ。
    • デフォルト:true。
    • 説明:システムの組み込み禁止用語ルールを有効にするかどうか。true に設定すると、システムの組み込み禁止用語フィルタリングロジックも有効になり、認識結果で Alibaba Cloud Model Studio 禁止用語リスト に一致する単語は、同じ長さの * に置き換えられます。

language_hints

String[]

["zh", "en"]

いいえ

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

このパラメーターは paraformer-v2 モデルにのみ適用されます。

サポートされている言語コード:

  • zh:中国語
  • en:英語
  • ja:日本語
  • yue:広東語
  • ko:韓国語
  • de:ドイツ語
  • fr:フランス語
  • ru:ロシア語

注記language_hints は、TranscriptionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります:

TranscriptionParam param = TranscriptionParam.builder()
  // "language_hints" は paraformer-v2 モデルでのみサポートされています
  .model("paraformer-v2")
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();
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 フィールドが含まれます。

注記話者分離を有効にする場合、音声の長さが 2 時間を超えないようにすることを推奨します。超えると認識が失敗したり、タイムアウトしたりする可能性があります。

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

speakerCount

Integer

いいえ

話者数の参考値。有効な値:2 から 100 までの整数 (両端を含む)。

話者分離が有効な場合 (diarizationEnabled が true に設定されている場合) に効果があります。

デフォルトでは、システムが自動的に話者数を決定します。このパラメーターを設定した場合、アルゴリズムに対して指定された話者数を出力しようとするヒントとしてのみ機能し、正確な数が保証されるわけではありません。

apiKey

String

いいえ

API キー。API キーがすでに環境変数に設定されている場合は、コードで設定する必要はありません。そうでない場合は、コードで設定する必要があります。

応答

タスク結果 (TranscriptionResult)

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

インターフェイス/メソッドパラメーター戻り値説明
public String getRequestId()

なし

requestId

requestId を取得します。

public String getTaskId()

なし

taskId

taskId を取得します。

public TaskStatus getTaskStatus()

なし

TaskStatus、タスクステータス

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

TaskStatus は列挙型クラスです。以下の 4 つのステータスにのみ注目する必要があります:PENDING、RUNNING、SUCCEEDED、FAILED。

注記タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは 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":"{YOUR_AUDIO_URL}",
            "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=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":1,
        "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": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "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 は列挙型クラスです。以下の 4 つのステータスにのみ注目する必要があります:PENDING、RUNNING、SUCCEEDED、FAILED。

public String getMessage()

なし

タスク実行中の主要な情報、空の場合もあります

タスク実行中の主要な情報を取得します。

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

認識結果の説明

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

クリックして認識結果の例を表示

{
    "file_url":"{YOUR_AUDIO_URL}",
    "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 the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "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 は、タスクの完了を待機する場合 (Transcription の wait メソッドを呼び出す) や、タスク結果をクエリする場合 (Transcription の fetch メソッドを呼び出す) に使用されます。

静的メソッド FromTranscriptionParam を通じて TranscriptionQueryParam インスタンスを作成します。

クリックして例を表示

// 文字起こしリクエストパラメーターを作成
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(
                                "{YOUR_AUDIO_URL}"))
                .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)
  • param:TranscriptionParam インスタンス
  • 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)

queryParam:TranscriptionQueryParam インスタンス

タスク結果 (TranscriptionResult)

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

public TranscriptionResult fetch(TranscriptionQueryParam queryParam)

queryParam:TranscriptionQueryParam インスタンス

タスク結果 (TranscriptionResult)

現在のタスク結果を非同期にクエリします。

エラーコード

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

問題が解決しない場合は、開発者コミュニティ に参加して問題を報告し、さらなる調査のためにリクエスト 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": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

その他の例

その他の例については、GitHub をご参照ください。

よくある質問

機能に関する質問

Q:Base64 エンコードされた音声をサポートしていますか?

いいえ。Base64 エンコードされた音声はサポートされていません。パブリックにアクセス可能な URL を介してアクセスできる音声のみがサポートされています。バイナリストリームや直接のローカルファイル認識はサポートされていません。

Q:音声ファイルをパブリックにアクセス可能な URL として提供するにはどうすればよいですか?

一般的に、以下の手順に従います (これは一般的なアプローチであり、詳細はストレージ製品によって異なります。音声を Alibaba Cloud OSS にアップロードすることを推奨します):

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

例:

  • Object Storage Service (推奨):

    • クラウドプロバイダーのオブジェクトストレージサービス (例:Alibaba Cloud 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 を使用する場合、音声ファイルが Alibaba Cloud OSS に保存されている場合、oss:// プレフィックスを持つ一時的な URL はサポートされません。

RESTful API を使用する場合、音声ファイルが Alibaba Cloud OSS に保存されている場合、oss:// プレフィックスを持つ一時的な URL はサポートされます:

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

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

送信後、タスクはキューイング中 (PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。しばらくお待ちください。長い音声ファイルはより多くの処理時間を必要とします。

トラブルシューティング

コードエラーが発生した場合は、「エラーコード」の情報に基づいてトラブルシューティングを行ってください。

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

リクエストパラメーター の timestampAlignmentEnabled を true に設定してタイムスタンプアライメント機能を有効にすると、認識結果が音声再生と同期します。

Q:継続的なポーリング後も結果を取得できませんか?

これはレート制限が原因である可能性があります。しばらくお待ちください。容量拡張が必要な場合は、開発者コミュニティ に参加して申請してください。

Q:なぜ認識結果がないのですか (音声を認識できない)?

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

その他の質問

GitHub の QA をご参照ください。