Skip to main content

Fun-ASR 非リアルタイム音声認識 Python SDK

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

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

前提条件

クイックスタート

以下の例では DashScope Python SDK 2.0 を使用します。コアリソース（client.audio.asr） は、次の 2 つの方法でタスクを送信、待機、照会するためのメソッドを提供します。
  • タスクを非同期で送信し、同期的に待機する：タスクを送信した後、タスクが完了するまで現在のスレッドをブロックし、認識結果を返します。
  • タスクを非同期で送信し、非同期で結果をクエリする：タスクを送信した後、必要なときにクエリインターフェイスを呼び出して結果を取得します。
  • 非同期で送信し、同期的に待機
  • 非同期で送信し、非同期で結果をクエリ
タスクを送信して完了を待機
  1. client.audio.asr.jobs.create を呼び出し、リクエストパラメーターを指定してタスクを送信します。
    • ファイル文字起こしサービスは、API を介して送信されたタスクをベストエフォート方式で処理します。タスクを送信すると、キュー登録済み (PENDING) 状態になります。キューの待機時間はキューの長さとファイルの持続時間によって異なり、正確には言えませんが、通常は数分以内です。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。
    • 各タスクが完了した後、認識結果とダウンロード URL は 24 時間有効です。有効期限が切れると、以前のクエリで返された URL を介してタスクをクエリしたり、結果をダウンロードしたりすることはできなくなります。
  2. client.audio.asr.jobs.wait(job=job) を呼び出し、タスクの完了を同期的に待機します。 タスクが PENDING または RUNNING の間、jobs.wait は待機を続けます。成功すると Job を返します。 各メソッドは Job を返します。job.results から結果リストを取得できます。各 transcription_url は書き起こし結果のダウンロード先です。 
import json
import os

import dashscope

# {WorkspaceId} を対象リージョンの実際のワークスペース ID に置き換えます。
client = dashscope.Client(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

job = client.audio.asr.jobs.create(
    model="fun-asr",
    file_urls=["{YOUR_AUDIO_URL}"],
)

job = client.audio.asr.jobs.wait(job=job)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))

サービスエンドポイント

SDK のデフォルトは北京リージョンです。dashscope.Client の作成時に、region でリージョン、workspace でワークスペース ID を指定します。リージョン設定はその Client のみに適用されます。
  • シンガポール
  • 中国 (北京)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1{WorkspaceId} を実際の ワークスペース ID に置き換えてください。
API キーはリージョンごとに異なります。対応するリージョンの API キーを使用してください。

リクエストパラメーター

client.audio.asr.transcribe または client.audio.asr.jobs.create でリクエストパラメーターを設定します。
パラメータータイプ必須説明
modelstrはいモデル名。
file_urlslist[str]はい文字起こしする音声または動画ファイルの URL のリスト。HTTP と HTTPS がサポートされています。1 回のリクエストでサポートされる URL は 1 つだけです。サポートされている音声フォーマット、ファイルサイズの制限、持続時間の制限などの入力要件については、「音声仕様」をご参照ください。録音が Alibaba Cloud OSS に保存されている場合、RESTful API は oss:// で始まる一時的な URL をサポートしますが、SDK は oss:// で始まる一時的な URL をサポートしません。
  • 一時的な URL は 48 時間有効で、有効期限が切れると使用できなくなります。本番環境では使用しないでください。
  • アップロード認証情報インターフェイスは 100 QPS にレート制限されており、スケールアップできません。本番環境、高同時実行数、または負荷テストのシナリオでは使用しないでください。
  • 本番環境では、ファイルの長期的な可用性を確保し、レート制限を回避するために、Alibaba Cloud OSS などの安定したストレージを使用してください。
  • OSS の一時的なパブリック URL に設定された音声ファイル URL が到達不能な場合は、リクエストヘッダーで X-DashScope-OssResourceResolve を enable に設定します (非推奨)。 SDK はリクエストヘッダーの設定をサポートしていません。
parameters.vocabulary_idstrいいえプリコンパイルされたホットワードリストの ID。この ID は、ホットワードリスト作成 API を呼び出して事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。使用方法の詳細については、「プリコンパイル済みホットワード」をご参照ください。
parameters.vocabularydictいいえインスタントホットワード。キーをホットワードの文字列（string）、値を整数の重み（integer）とするキーバリューペアを渡します。事前にホットワードリストを作成する必要はありません。使用方法については、インスタントホットワードをご参照ください。例：以下の例では、クイックスタートでリージョンとワークスペースを設定した client を再利用します。
vocab = {"Zhang San": 5, "Li Si": 5}
result = client.audio.asr.jobs.create(
    model="fun-asr",
    file_urls=["{ご自身の音声ファイルの URL}"],
    parameters={"vocabulary": vocab},
)
parameters.channel_idlist[int]いいえマルチトラック音声ファイルで認識するオーディオトラックのインデックス。インデックスは 0 から始まります。たとえば、[0] は最初のトラックを認識し、[0, 1] は最初のトラックと 2 番目のトラックを同時に認識します。このパラメーターを省略すると、最初のトラックのみが処理されます。
指定された各トラックは個別に課金されます。たとえば、1 つのファイルに対して [0, 1] をリクエストすると、2 回分の料金が発生します。
デフォルト値：[0]。
parameters.special_word_filterstrいいえ音声認識中に処理する禁止用語。禁止用語ごとに異なる処理方法を設定できます。詳細については、「禁止用語フィルター」をご参照ください。
parameters.diarization_enabledboolいいえ話者分離を有効にするかどうか。デフォルトでは無効です。モノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。有効にすると、認識結果に異なる話者を区別する speaker_id フィールドが含まれます。
話者分離を有効にする場合、音声の持続時間を 2 時間以内にしてください。そうしないと、認識が失敗したり、タイムアウトしたりする可能性があります。
デフォルト値：False。speaker_id の例については、「認識結果の説明」をご参照ください。
parameters.speaker_countintいいえ
話者分離が有効な場合 (diarization_enabled が True に設定されている場合) にのみ有効です。
話者数の参照値。有効な範囲は 2 から 100 (両端を含む) の整数です。デフォルトでは、話者数は自動的に検出されます。この値を設定した場合、アルゴリズムが可能な場合に指定された数を出力するように誘導するだけであり、正確な数が保証されるわけではありません。デフォルト値なし。
parameters.language_hintslist[str]いいえ認識する言語コード。事前に言語を特定できない場合は、設定せずにモデルが自動的に言語を検出するようにします。最大 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: スロバキア語

応答

Job

Job にはタスク情報、生の出力、使用量が含まれます。 
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "status": "PENDING",
    "submitted_at": "2026-10-29 10:00:00.000",
    "scheduled_at": null,
    "finished_at": null,
    "output": {
        "task_id": "00000000-0000-0000-0000-000000000001",
        "task_status": "PENDING",
        "submit_time": "2026-10-29 10:00:00.000"
    },
    "usage": null
}
フィールド説明
task_idタスク ID。
statusタスクの状態：PENDING、RUNNING、SUCCEEDED、FAILED。
submitted_at送信時刻。job.output["submit_time"] に対応します。
scheduled_at処理開始時刻。job.output["scheduled_time"] に対応します。
finished_at終了時刻。job.output["end_time"] に対応します。
output生のタスク出力の辞書。
resultsサブタスクの結果リスト。job.results で取得できます。transcription_url の JSON ファイルをダウンロードして認識テキストを取得します。
usageタスクの使用量。

Job.output

job.output はサービスが返す生のタスク出力の辞書です。
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED (raise_on_error=False)
{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "PENDING",
    "submit_time": "2026-10-29 10:00:00.000"
}
パラメーター説明
codeエラーコード。message フィールドと組み合わせて、「エラーコード」を参照して問題をトラブルシューティングしてください。
messageエラーメッセージ。code フィールドと組み合わせて、「エラーコード」を参照して問題をトラブルシューティングしてください。
task_idタスク ID。
task_statusタスクステータス。PENDING、RUNNING、SUCCEEDED、FAILED の 4 つの状態のいずれかです。タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を判断するには、subtask_status フィールドを確認してください。
resultsサブタスクの認識結果。
subtask_statusサブタスクのステータス。PENDING、RUNNING、SUCCEEDED、FAILED の 4 つの状態のいずれかです。
file_url認識された音声の URL。
transcription_url音声認識結果の URL。認識結果は JSON ファイルとして保存されます。transcription_url に関連付けられたリンクからファイルをダウンロードするか、HTTP リクエストを介して直接その内容を読み取ることができます。JSON ファイルの内容については、「認識結果の説明」をご参照ください。

認識結果の説明

認識結果は 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":"こんにちは世界、こちらはアリババスピーチラボです。",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"こんにちは世界、こちらはアリババスピーチラボです。",
                    "sentence_id":1,
                    "speaker_id":0, //このフィールドは自動話者分離が有効な場合にのみ表示されます
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"こんにちは ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"世界",
                            "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単語の後に予測された句読点 (もしあれば)。

主要なインターフェイス

コアリソース（client.audio.asr）

dashscope.Client でクライアントを作成し、client.audio.asr リソースを使用します。以下のメソッドはいずれも Job を返します。
メソッドメソッドシグネチャ説明
transcribe
def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
タスクを送信し、完了を同期的に待機します。デフォルトモデルは qwen-audio-3.1-asr-flash-filetrans です。他のモデルを呼び出す場合は model を明示的に指定します。
jobs.create
def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
タスクを送信し、認識の完了を待たずに task_id と status を含む Job を返します。
jobs.wait
def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
Job またはタスク ID を渡して完了を同期的に待機します。poll_interval と max_interval で初期および最大ポーリング間隔、timeout で合計待機時間を設定します。単位はいずれも秒です。
jobs.fetch
def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job
タスク ID を指定して状態と結果を 1 回照会します。完了までは待機しません。

エラーコード

デフォルトでは、タスクが失敗すると DashScopeError が発生します。失敗した Job を取得するには、Client の作成時に raise_on_error=False を設定し、job.status を確認します。 エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングしてください。 タスクに複数のサブタスクが含まれている場合、少なくとも 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": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "音声ファイルをダウンロードできません。",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

よくある質問

機能

Q：Base64 エンコードされた音声はサポートされていますか？

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

Q：音声ファイルをパブリックにアクセス可能な URL で利用できるようにするにはどうすればよいですか？

一般的な手順は以下の通りです。これは 1 つのアプローチであり、正確なプロセスはストレージ製品によって異なります。音声を Alibaba Cloud OSS にアップロードすることを推奨します。
例：
  • オブジェクトストレージサービス (推奨)：
    • クラウドプロバイダーのオブジェクトストレージサービス (例：Alibaba Cloud OSS) を使用して、音声ファイルをバケットにアップロードし、パブリックアクセスに設定します。
    • 利点：高可用性、CDN アクセラレーションのサポート、簡単な管理。
  • Web サーバー：
    • HTTP/HTTPS アクセスをサポートする Web サーバー (Nginx や Apache など) に音声ファイルを配置します。
    • 利点：小規模なプロジェクトやローカルテストに適しています。
  • コンテンツ配信ネットワーク (CDN)：
    • CDN に音声ファイルをホストし、CDN が提供する URL を介してアクセスします。
    • 利点：ファイル配信を高速化し、高同時実行数シナリオに適しています。
選択したストレージまたはホスティング方法に従って音声をアップロードします。例：
  • オブジェクトストレージサービス：
    • クラウドプロバイダーのコンソールにログインし、バケットを作成します。
    • 音声ファイルをアップロードし、その権限をパブリック読み取りに設定するか、一時的なアクセスリンクを生成します。
  • Web サーバー：
    • サーバー上の指定されたディレクトリ (例：/var/www/html/audio/) に音声ファイルを配置します。
    • ファイルが HTTP/HTTPS 経由でアクセス可能であることを確認します。
例：
  • オブジェクトストレージサービス：
    • ファイルがアップロードされると、システムは自動的にパブリックアクセス 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)。
生成された 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：ポーリングしても結果が返されないのはなぜですか？

これはスロットリングが原因である可能性があります。しばらく待ってから再試行してください。

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