azure-speech-to-text-rest-py

同梱されているアップストリームのサポートファイル

サポートファイルはスキルからの相対パスに含まれています。固定されたソース、ライセンス、ハッシュ、インポート時の変更については、UPSTREAM-NOTICE.md を参照してください。

Azure Speech to Text REST API（短い音声向け）

短い音声ファイル（最大 60 秒）を音声テキスト変換するためのシンプルな REST API です。SDK は不要で、HTTP リクエストだけで利用できます。

前提条件

1. Azure サブスクリプション - 無料で作成
2. Speech リソース - Azure ポータルで作成
3. 認証情報を取得 - デプロイ後、リソースの［キーとエンドポイント］に移動します

環境変数

# Required
AZURE_SPEECH_KEY=<your-speech-resource-key>
AZURE_SPEECH_REGION=<region>  # e.g., eastus, westus2, westeurope

# Alternative: Use endpoint directly
AZURE_SPEECH_ENDPOINT=https://<region>.stt.speech.microsoft.com

インストール

pip install requests

クイックスタート

import os
import requests

def transcribe_audio(audio_file_path: str, language: str = "en-US") -> dict:
    """Transcribe short audio file (max 60 seconds) using REST API."""
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Accept": "application/json"
    }
    
    params = {
        "language": language,
        "format": "detailed"  # or "simple"
    }
    
    with open(audio_file_path, "rb") as audio_file:
        response = requests.post(url, headers=headers, params=params, data=audio_file, timeout=(10, 90))
    
    response.raise_for_status()
    return response.json()

# Usage
result = transcribe_audio("audio.wav", "en-US")
if result.get("RecognitionStatus") == "Success" and result.get("NBest"):
    print(result["NBest"][0].get("Display", ""))
else:
    print("No successful detailed recognition result")

音声の要件

形式	コーデック	サンプルレート	備考
WAV	PCM	16 kHz、モノラル	推奨
OGG	OPUS	16 kHz、モノラル	ファイルサイズが小さくなります

制限事項：

• 音声は最大 60 秒です
• 発音評価の場合は最大 30 秒です
• 部分結果／途中結果はなく、最終結果のみです

Content-Type ヘッダー

# WAV PCM 16kHz
"Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000"

# OGG OPUS
"Content-Type": "audio/ogg; codecs=opus"

応答形式

シンプル形式（デフォルト）

params = {"language": "en-US", "format": "simple"}

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

詳細形式

params = {"language": "en-US", "format": "detailed"}

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    }
  ]
}

チャンク転送（推奨）

レイテンシを抑えるには、音声をチャンクに分けてストリーミングします。

import os
import requests

def transcribe_chunked(audio_file_path: str, language: str = "en-US") -> dict:
    """Stream audio in chunks for lower latency."""
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Accept": "application/json",
        "Transfer-Encoding": "chunked",
        "Expect": "100-continue"
    }
    
    params = {"language": language, "format": "detailed"}
    
    def generate_chunks(file_path: str, chunk_size: int = 1024):
        with open(file_path, "rb") as f:
            while chunk := f.read(chunk_size):
                yield chunk
    
    response = requests.post(
        url, 
        headers=headers, 
        params=params, 
        data=generate_chunks(audio_file_path),
        timeout=(10, 90)
    )
    
    response.raise_for_status()
    return response.json()

認証方法

方法 1：サブスクリプションキー（シンプル）

headers = {
    "Ocp-Apim-Subscription-Key": os.environ["AZURE_SPEECH_KEY"]
}

方法 2：ベアラートークン

import requests
import os

def get_access_token() -> str:
    """Get access token from the token endpoint."""
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    token_url = f"https://{region}.api.cognitive.microsoft.com/sts/v1.0/issueToken"
    
    response = requests.post(
        token_url,
        headers={
            "Ocp-Apim-Subscription-Key": api_key,
            "Content-Type": "application/x-www-form-urlencoded",
            "Content-Length": "0"
        },
        timeout=(10, 30)
    )
    response.raise_for_status()
    return response.text

# Use token in requests (valid for 10 minutes)
token = get_access_token()
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
    "Accept": "application/json"
}

クエリパラメーター

パラメーター	必須	値	説明
language	はい	en-US、de-DE など	音声の言語
format	いいえ	simple、detailed	結果の形式（デフォルト：simple）
profanity	いいえ	masked、removed、raw	侮辱的な表現の処理（デフォルト：masked）

認識ステータスの値

ステータス	説明
Success	認識に成功しました
NoMatch	音声は検出されましたが、一致する単語がありませんでした
InitialSilenceTimeout	無音のみが検出されました
BabbleTimeout	ノイズのみが検出されました
Error	サービス内部エラー

侮辱的な表現の処理

# Mask profanity with asterisks (default)
params = {"language": "en-US", "profanity": "masked"}

# Remove profanity entirely
params = {"language": "en-US", "profanity": "removed"}

# Include profanity as-is
params = {"language": "en-US", "profanity": "raw"}

エラー処理

import requests

def transcribe_with_error_handling(audio_path: str, language: str = "en-US") -> dict | None:
    """Transcribe with proper error handling."""
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    try:
        with open(audio_path, "rb") as audio_file:
            response = requests.post(
                url,
                headers={
                    "Ocp-Apim-Subscription-Key": api_key,
                    "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
                    "Accept": "application/json"
                },
                params={"language": language, "format": "detailed"},
                data=audio_file,
                timeout=(10, 90)
            )
        
        if response.status_code == 200:
            result = response.json()
            if result.get("RecognitionStatus") == "Success":
                return result
            else:
                print(f"Recognition failed: {result.get('RecognitionStatus')}")
                return None
        elif response.status_code == 400:
            print(f"Bad request: Check language code or audio format")
        elif response.status_code == 401:
            print(f"Unauthorized: Check API key or token")
        elif response.status_code == 403:
            print("Forbidden: Check resource permissions, endpoint and service policy")
        else:
            print(f"Error {response.status_code}; response body withheld")
        
        return None
        
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

非同期バージョン

import os
import aiohttp
import asyncio

async def transcribe_async(audio_file_path: str, language: str = "en-US") -> dict:
    """Async version using aiohttp."""
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Accept": "application/json"
    }
    
    params = {"language": language, "format": "detailed"}
    
    async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=90)) as session:
        with open(audio_file_path, "rb") as f:
            audio_data = f.read()
        
        async with session.post(url, headers=headers, params=params, data=audio_data) as response:
            response.raise_for_status()
            return await response.json()

# Usage
result = asyncio.run(transcribe_async("audio.wav", "en-US"))
if result.get("RecognitionStatus") == "Success" and result.get("NBest"):
    print(result["NBest"][0].get("Display", ""))
else:
    print("No successful detailed recognition result")

対応言語

主な言語コードについては、全一覧を参照してください。

コード	言語
en-US	英語（米国）
en-GB	英語（英国）
de-DE	ドイツ語
fr-FR	フランス語
es-ES	スペイン語（スペイン）
es-MX	スペイン語（メキシコ）
zh-CN	中国語（標準語）
ja-JP	日本語
ko-KR	韓国語
pt-BR	ポルトガル語（ブラジル）

ベストプラクティス

1. 互換性を高めるには、WAV PCM 16kHz モノラルを使用します
2. レイテンシを抑えるには、チャンク転送を有効にします
3. アクセストークンは 9 分間キャッシュします（有効期間は 10 分です）
4. 正確に認識させるには、正しい言語を指定します
5. 信頼度スコアが必要な場合は、詳細形式を使用します
6. 運用コードでは、すべての RecognitionStatus の値を処理します

この API を使用しない場合

次の用途には、代わりに Speech SDK または Batch Transcription API を使用してください。

• 60 秒を超える音声
• リアルタイムのストリーミング文字起こし
• 部分結果／途中結果
• 音声翻訳
• カスタム音声モデル
• 多数のファイルの一括文字起こし

参考ファイル

ファイル	内容
references/pronunciation-assessment.md	発音評価のパラメーターとスコアリング

使用する場面

このスキルは、概要で説明されているワークフローやアクションを実行する際に適用できます。

制限事項

• 上記で説明した範囲にタスクが明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、処理を中断して確認してください。

例では、音声と参照テキストを Azure に送信します。データ転送と保持の正確な範囲を確認し、デフォルトでは合成音声を使用してください。認証情報を添付する前に、設定されたリージョンまたはリソースのエンドポイントが、実際に承認された Azure リソースと一致することを解決・検証してください。信頼できない入力から任意のホスト名を受け入れてはいけません。長さ、形式、サイズをローカルで確認し、リクエスト数に上限を設け、キーや文字起こし結果をログに残さないでください。詳細な認識結果には NBest[].Display を使用し、インデックス参照の前に Success と結果が空でないことを確認してください。発音や韻律のスコアはモデルによる推定値であり、臨床的または客観的な話者品質の評価ではありません。ロケールと API の対応状況は異なります。公式の短時間音声 APIを参照してください。