Skip to main content

Fun-ASR 非リアルタイム音声認識用 HTTP API

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

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

仕組み

結果を単一のリクエストですぐに返す同期的な DashScope 呼び出しとは異なり、非同期呼び出しは長い音声ファイルや時間のかかるタスク向けに設計されています。このモードでは、送信・ポーリングの 2 段階のフローを使用することで、長時間の待機によるリクエストのタイムアウトを回避します。
  1. ステップ 1：タスクの送信
    • クライアントが非同期処理リクエストを送信します。
    • リクエストを検証した後、サーバーはタスクをすぐには実行しません。代わりに、タスクが正常に作成されたことを示す一意の task_id を返します。
  2. ステップ 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 に置き換えてください。
Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールリージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します：
  • 中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
  • シンガポール： dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ
新しいドメイン (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com) でタスクを送信する場合、リクエストボディに parameters オブジェクトを含める必要があります。パラメーターを設定する必要がない場合でも、空のオブジェクト {} を渡してください。そうしないと、タスクは正常に送信されますが、認識は失敗します。

リクエストヘッダー

パラメータータイプ必須説明
Authorizationstringはいフォーマット Bearer <your_api_key> の認証トークン。「<your_api_key>」を実際の API キーに置き換えてください。タスク送信インターフェイスとタスククエリインターフェイスの両方で必須です。
Content-Typestringはいリクエストボディのメディアタイプ。タスク送信インターフェイスでのみ必須です。固定値： application/json。
X-DashScope-Asyncstringはい非同期タスクフラグ。タスク送信インターフェイスでのみ必須です。固定値： 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 はリクエストヘッダーの構成をサポートしていません。
parametersobject(オプション)リクエストパラメーターオブジェクト。
新しいドメイン (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com) を使用する場合、parameters は必須です。パラメーターを設定する必要がない場合でも、空のオブジェクト {} を渡してください。このフィールドを省略すると、タスクは正常に送信されますが、タスククエリインターフェイスは認識失敗を返します。

プロパティ

vocabulary_id string(オプション)プリコンパイルされたホットワードリストの ID。この ID は、ホットワードリスト作成 API を呼び出して事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。使用方法の詳細については、「プリコンパイルされたホットワード」をご参照ください。vocabulary object(オプション)インスタントホットワード。キーをホットワードの文字列（string）、値を整数の重み（integer）とするキーバリューペアを渡します。事前にホットワードリストを作成する必要はありません。使用方法については、インスタントホットワードをご参照ください。channel_id array[integer](オプション)マルチトラック音声ファイルで認識する音声トラックのインデックス。インデックスは 0 から始まります。たとえば、[0] は最初のトラックを認識し、[0, 1] は最初のトラックと 2 番目のトラックを同時に認識します。このパラメーターを省略すると、最初のトラックのみが処理されます。
指定された各トラックは独立して課金されます。たとえば、1 つのファイルに対して [0, 1] をリクエストすると、2 つの別々の料金が発生します。
デフォルト値：[0]。special_word_filter string(オプション) 置換または削除する語句を設定します。パラメーターは次のフィールドを含む JSON 文字列です。
  • filter_with_signed.word_list：一致した語句を同じ長さの * に置き換える文字列配列。
  • filter_with_empty.word_list：結果から削除する語句の文字列配列。
  • system_reserved_filter：組み込みリストも使用するかどうかを制御するブール値。デフォルトは true。false でもカスタムルールは有効です。
省略した場合、組み込みの Model Studio 機密語リストに一致する語句を同じ長さの * に置き換えます。たとえば、PROJECT を同じ長さのアスタリスクに置き換え、REPORT を削除するには、次の値を指定します。
{
  "special_word_filter": "{\"filter_with_signed\":{\"word_list\":[\"PROJECT\"]},\"filter_with_empty\":{\"word_list\":[\"REPORT\"]},\"system_reserved_filter\":true}"
}
diarization_enabled boolean(オプション)話者ダイアライゼーションを有効にするかどうか。デフォルトでは無効です。モノラル音声にのみ適用されます。マルチチャンネル音声は話者ダイアライゼーションをサポートしていません。有効にすると、認識結果に異なる話者を区別する speaker_id フィールドが含まれます。
話者ダイアライゼーションを有効にする場合、音声の持続時間を 2 時間以内にしてください。そうしないと、認識が失敗したり、タイムアウトしたりする可能性があります。
speaker_id の例については、「認識結果の説明」をご参照ください。デフォルト値：false。speaker_count integer(オプション)
話者ダイアライゼーションが有効な場合 (diarization_enabled が true に設定されている場合) にのみ有効です。
話者数の参照値。有効な範囲は 2 から 100 (両端を含む) の整数です。デフォルトでは、話者数は自動的に検出されます。この値を設定した場合、アルゴリズムが可能な場合に指定された数を出力するように誘導するだけであり、正確な数を保証するものではありません。デフォルト値なし。language_hints array[string](オプション)認識する言語コード。事前に言語を特定できない場合は、設定せずにモデルが自動的に言語を検出するようにします。最大 1 個の値を指定できます。それ以上指定した場合は、最初の 1 個だけが有効です。
  • 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": "fun-asr",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

レスポンスボディ

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

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

詳細については、「非同期タスクの管理」をご参照ください。過去 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_formatstringソースファイルの音声フォーマット。
channelsarray[integer]ソースファイル内の音声のトラックインデックス。シングルトラック音声の場合は [0]、デュアルトラック音声の場合は [0, 1] が返されます。
original_sampling_rateintegerソースファイル内の音声のサンプリングレート (Hz)。
original_duration_in_millisecondsintegerソースファイル内の元の音声の持続時間 (ms)。
channel_idinteger文字起こし結果のトラックインデックス。0 から始まります。
content_durationinteger音声として識別されたトラック内のコンテンツの持続時間 (ms)。音声認識モデルサービスは、音声として識別されたトラック内のコンテンツのみを文字起こしし、その持続時間に基づいて測定および請求します。非音声コンテンツは測定または請求されません。通常、音声コンテンツの持続時間は元の音声の持続時間よりも短くなります。音声コンテンツが存在するかどうかは AI モデルによって決定されるため、結果は実際の状況と若干異なる場合があります。
transcriptstring段落レベルの文字起こし結果。
sentencesarray文レベルの文字起こし結果。
wordsarray単語レベルの文字起こし結果。
begin_timeinteger開始タイムスタンプ (ms)。
end_timeinteger終了タイムスタンプ (ms)。
textstring文字起こし結果。
speaker_idinteger現在の話者のインデックス。0 から始まり、異なる話者を区別するために使用されます。このフィールドは、話者ダイアライゼーションが有効な場合にのみ認識結果に表示されます。
punctuationstring単語の後に予測される句読点 (もしあれば)。