Qwen-Audio-ASR-Filetrans 非リアルタイム音声認識用 HTTP API - Alibaba Cloud Model Studio

このトピックでは、Qwen-Audio-ASR-Filetrans を使用した非リアルタイム音声認識のための HTTP API のパラメーターとインターフェイスの詳細について説明します。

サポートされている音声フォーマット、ファイルサイズの制限、および持続時間の制限などの入力要件については、「音声仕様」をご参照ください。

仕組み

結果を単一のリクエストですぐに返す同期的な DashScope 呼び出しとは異なり、非同期呼び出しは長い音声ファイルや時間のかかるタスク向けに設計されています。このモードでは、送信・ポーリングの 2 段階のフローを使用することで、長時間の待機によるリクエストのタイムアウトを回避します。

ステップ 1：タスクの送信
- クライアントが非同期処理リクエストを送信します。
- リクエストを検証した後、サーバーはタスクをすぐには実行しません。代わりに、タスクが正常に作成されたことを示す一意の task_id を返します。
ステップ 2：結果の取得
- クライアントは、返された task_id を使用してクエリインターフェイスを繰り返しポーリングします。
- タスクが完了すると、クエリインターフェイスは最終的な認識結果を返します。

サービスエンドポイント

シンガポール

タスク送信インターフェイス： POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

タスククエリインターフェイス： GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

{WorkspaceId} を実際のワークスペース ID に置き換えてください。

中国 (北京)

タスク送信インターフェイス： POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

タスククエリインターフェイス： GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

{WorkspaceId} を実際のワークスペース ID に置き換えてください。

重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールリージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します：

中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
シンガポール： dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ

リクエストヘッダー

パラメーター	タイプ	必須	説明
`Authorization`	`string`	はい	フォーマット `Bearer <your_api_key>` の認証トークン。「`<your_api_key>`」を実際の API キーに置き換えてください。タスク送信インターフェイスとタスククエリインターフェイスの両方で必須です。
`Content-Type`	`string`	はい	リクエストボディのメディアタイプ。タスク送信インターフェイスでのみ必須です。固定値： `application/json`。
`X-DashScope-Async`	`string`	はい	非同期タスクフラグ。タスク送信インターフェイスでのみ必須です。固定値： `enable`。省略するとタスクを送信できません。

タスク送信インターフェイス

音声認識タスクを送信します。このインターフェイスは非同期で応答するため、タスククエリインターフェイスでタスクのステータスをポーリングしてください。

リクエストボディ

modelstring(必須)

モデル名。

inputobject(必須)

入力パラメーターオブジェクト。

プロパティ

file_urls array[string](必須)

文字起こしする音声または動画ファイルの URL のリスト。HTTP と HTTPS がサポートされています。1 回のリクエストでサポートされる URL は 1 つだけです。サポートされている音声フォーマット、ファイルサイズの制限、および持続時間の制限などの入力要件については、「音声仕様」をご参照ください。

録音が Alibaba Cloud Object Storage Service (OSS) に保存されている場合、RESTful API は oss:// で始まる一時的な URL をサポートしますが、SDK は oss:// で始まる一時的な URL をサポートしません。

重要

一時的な URL は 48 時間有効で、有効期限が切れると使用できなくなります。本番環境では使用しないでください。
アップロード認証情報インターフェイスは 100 QPS にレート制限されており、スケールアップできません。本番環境、高い同時実行数、または負荷テストのシナリオでは使用しないでください。
本番環境では、ファイルの長期的な可用性を確保し、レート制限を回避するために、Alibaba Cloud OSS などの安定したストレージを使用してください。
OSS の一時的なパブリック URL に設定された音声ファイル URL が到達不能な場合は、リクエストヘッダーで X-DashScope-OssResourceResolve を enable に設定してください (非推奨)。

SDK はリクエストヘッダーの構成をサポートしていません。

contextarray(object)(オプション)

認識精度を向上させるために、オプションの会話のコンテキストを提供するメッセージのリスト。

重要SDK はまだこの機能をサポートしていません。

重要コンテキスト拡張は、ドメイン固有の用語の認識精度を向上させます。使用方法については、「コンテキスト拡張」をご参照ください。

制約：input_text および text タイプのコンテキストメッセージは、それぞれ 5 メッセージに制限されます。この制限を超えた場合、最新の 5 つのみが保持されます。コンテキストターンごとの合計テキスト長 (user と assistant の text フィールドの合計長) は 400 文字を超えてはなりません (文字ごとにカウントされ、各文字は 1 としてカウントされます)。超過分は末尾から切り捨てられます。

重要コンテキストを含める場合、messages 内のメッセージの順序が重要です：コンテキストメッセージは会話のターンごとに配置する必要があります。各ターン内で、user メッセージ (input_text タイプ) は、対応する assistant メッセージ (text タイプ) の前に来る必要があります。input_audio を含む user メッセージは、messages 配列の最後に配置する必要があります。

プロパティ

rolestring(必須)

メッセージのロール。有効な値：

user：以前のターンの認識結果またはドメイン固有の単語リスト。
assistant：以前のターンの大規模言語モデルの応答。

contentarray(object)(必須)

メッセージ本文アイテムのリスト。

プロパティ

typestring(必須)

コンテンツタイプ。有効な値：

input_text (オプション、コンテキスト)：以前のターンのユーザーの発話の認識結果、またはドメイン固有の単語リスト (ロールは user)。text フィールドも渡す必要があります。
text (オプション、コンテキスト)：以前のターンの大規模言語モデルの応答 (ロールは assistant)。text フィールドも渡す必要があります。

textstring(条件付き必須)

type が input_text の場合、以前のターンのユーザーの発話の認識結果またはドメイン固有の単語リストを入力します。type が text の場合、以前のターンの大規模言語モデルの応答を入力します。テキストは文字ごとにカウントされ、各文字は 1 としてカウントされます。コンテキストターン内のすべてのメッセージにわたる text フィールドの合計長は 400 文字を超えてはなりません。超過分は末尾から切り捨てられます。

parametersobject(必須)

parameters は必ず指定してください。設定するオプションがない場合は空のオブジェクト {} を渡します。このフィールドを省略すると、送信済みの書き起こしタスクが失敗します。

プロパティ

keep_dialect boolean (オプション)

qwen-audio-3.1-asr-flash-filetrans のみが対応しています。デフォルトは false で、方言を標準中国語に書き起こします。方言表現を保持するには true に設定します。

vocabulary_id string(オプション)

プリコンパイルされたホットワードリストの ID。

この ID は、ホットワードリスト作成 API を呼び出して事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。

語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。

使用方法の詳細については、「プリコンパイルされたホットワード」をご参照ください。

vocabulary object(オプション)

即時ホットワード。

キーと値のペアとして渡されます。キーはホットワードのテキスト (string)、値はホットワードの重み (integer) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定されます：[1, 5] の値は、値が大きくなるにつれてモデルがその単語を出力する可能性を高めます。値 50 はスーパーホットワードを指定し、再現率を大幅に向上させますが、スーパーホットワードの数は 50 を超えることはできません。

一時的な、会話レベルのホットワード最適化に適しています。

即時ホットワードと事前コンパイル済みホットワードを同時に設定すると、両方のリストが統合されます。統合後に 2000 個を超える場合は、2000 個がランダムに選択されます。使用方法の詳細については、「即時ホットワード」をご参照ください。

channel_id array[integer](オプション)

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

重要指定された各トラックは独立して課金されます。たとえば、1 つのファイルに対して [0, 1] をリクエストすると、2 つの別々の料金が発生します。

デフォルト値：[0]。

special_word_filter string(オプション)

音声認識中に処理する禁止用語。禁止用語ごとに異なる処理方法を設定できます。詳細については、「禁止用語フィルター」をご参照ください。

diarization_enabled boolean(オプション)

話者ダイアライゼーションを有効にするかどうか。デフォルトでは無効です。

モノラル音声にのみ適用されます。マルチチャンネル音声は話者ダイアライゼーションをサポートしていません。

有効にすると、認識結果に異なる話者を区別する speaker_id フィールドが含まれます。

注記話者ダイアライゼーションを有効にする場合、音声の持続時間を 2 時間以内にしてください。そうしないと、認識が失敗したり、タイムアウトしたりする可能性があります。

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

デフォルト値：false。

speaker_count integer(オプション)

重要話者ダイアライゼーションが有効な場合 (diarization_enabled が true に設定されている場合) にのみ有効です。

話者数の参照値。有効な範囲は 2 から 100 (両端を含む) の整数です。

デフォルトでは、話者数は自動的に検出されます。この値を設定した場合、アルゴリズムが可能な場合に指定された数を出力するように誘導するだけであり、正確な数を保証するものではありません。

デフォルト値なし。

language_hints array[string](オプション)

認識する言語コード。事前に言語を特定できない場合は、設定せずにモデルが自動的に言語を検出するようにします。

最大 4 個の値を指定できます。それ以上指定した場合は、最初の 4 個だけが有効です。

サポートされている言語コードを表示するにはクリックします

zh: 中国語
en: 英語
ja: 日本語
ko: 韓国語
vi: ベトナム語
th: タイ語
id: インドネシア語
ms: マレー語
tl: フィリピン語
hi: ヒンディー語
ar: アラビア語
fr: フランス語
de: ドイツ語
es: スペイン語
pt: ポルトガル語
ru: ロシア語
it: イタリア語
nl: オランダ語
sv: スウェーデン語
da: デンマーク語
fi: フィンランド語
no: ノルウェー語
el: ギリシャ語
pl: ポーランド語
cs: チェコ語
hu: ハンガリー語
ro: ルーマニア語
bg: ブルガリア語
hr: クロアチア語
sk: スロバキア語

基本的な呼び出し

次の例では、シンガポールリージョンを使用しています。「{WorkspaceId}」を実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。シンガポールリージョンと北京リージョンでは、異なる API キーを使用します。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

インラインホットワード

インラインホットワードは次のフォーマットで使用します：

{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

コンテキスト

コンテキストは次のフォーマットで使用します：

{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ],
        "context": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Hello there"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello, I am Qwen. How can I help you?"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

レスポンスボディ

request_idstring

この呼び出しの一意の識別子。

outputobject

タスク送信インターフェイスによって返されるデータ。

プロパティ

task_idstring

タスク ID。この ID をタスククエリインターフェイスの string として渡します。

task_statusstring

タスクステータス。正常に送信されると PENDING を返します。

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

タスククエリインターフェイス

音声認識タスクの実行ステータスと結果をクエリします。タスクが終了状態に達するまで、このインターフェイスをポーリングします。

リクエストボディ

task_idstring(必須)

重要このパラメーターは URL パスパラメーターです。リクエストボディはありません。

タスクをクエリするには、その ID を指定します。この ID は、タスク送信インターフェイスが呼び出されたときに返される task_id です。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

レスポンスボディ

request_idstring

この呼び出しの一意の識別子。

outputobject

タスククエリインターフェイスによって返されるデータ。

プロパティ

task_idstring

クエリされたタスクの ID。

task_statusstring

クエリされたタスクのステータス。

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

submit_timestring

タスクが送信された時間。

scheduled_timestring

タスクが実行されるようにスケジュールされた時間。

end_timestring

タスクが終了した時間。

resultsarray[object]

サブタスクの結果のリスト。認識する音声ファイルごとに 1 つ。

プロパティ

subtask_statusstring

サブタスクのステータス。

file_urlstring

ファイル文字起こしタスクによって処理されたファイルの URL。

transcription_urlstring

認識結果へのリンク。このリンクは 24 時間有効です。有効期限が切れると、以前のクエリで返された URL を介してタスクをクエリしたり、結果をダウンロードしたりすることはできません。

認識結果は JSON ファイルとして保存されます。上記のリンクからファイルをダウンロードするか、HTTP リクエストで直接その内容を読み取ることができます。JSON データの各フィールドの意味については、「認識結果の説明」をご参照ください。

codestring

重要サブタスクが失敗した場合にのみ返されます。

失敗したサブタスクのエラーコード。

messagestring

重要サブタスクが失敗した場合にのみ返されます。

失敗したサブタスクのエラーメッセージ。

task_metricsobject

タスクの全体的な実行統計。

プロパティ

TOTALinteger

サブタスクの総数。

SUCCEEDEDinteger

成功したサブタスクの数。

FAILEDinteger

失敗したサブタスクの数。

成功例

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

エラー例

{
    "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": "FILE_DOWNLOAD_FAILED",
            "message": "FILE_DOWNLOAD_FAILED",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

その他のインターフェイス：タスクステータスの一括クエリ / タスクのキャンセル

詳細については、「非同期タスクの管理」をご参照ください。過去 24 時間以内に送信された非リアルタイム音声認識タスクを一括クエリしたり、PENDING (キュー) 状態のタスクをキャンセルしたりできます。

認識結果の説明

認識結果は 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 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)。注記以下の課金説明は `qwen-audio-3.0-asr-flash-filetrans` に適用されます。`qwen-audio-3.1-asr-flash-filetrans` はトークン使用量に基づいて課金されます。音声認識モデルサービスは、音声として識別されたトラック内のコンテンツのみを文字起こしし、その持続時間に基づいて測定および請求します。非音声コンテンツは測定または請求されません。通常、音声コンテンツの持続時間は元の音声の持続時間よりも短くなります。音声コンテンツが存在するかどうかは AI モデルによって決定されるため、結果は実際の状況と若干異なる場合があります。
`transcript`	`string`	段落レベルの文字起こし結果。
`sentences`	`array`	文レベルの文字起こし結果。
`words`	`array`	単語レベルの文字起こし結果。
`begin_time`	`integer`	開始タイムスタンプ (ms)。
`end_time`	`integer`	終了タイムスタンプ (ms)。
`text`	`string`	文字起こし結果。
`speaker_id`	`integer`	現在の話者のインデックス。0 から始まり、異なる話者を区別するために使用されます。このフィールドは、話者ダイアライゼーションが有効な場合にのみ認識結果に表示されます。
`punctuation`	`string`	単語の後に予測される句読点 (もしあれば)。