[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69AT73VVYDNJ3MQ2V16SDJF":3,"skill-same:01M69AT73VVYDNJ3MQ2V16SDJF":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":58,"ownerHtmlUrl":59,"ownerBlogUrl":60,"ownerDescription":61,"updatedAt":62,"install":63,"resources":76},"01M69AT73VVYDNJ3MQ2V16SDJF","azure-speech-to-text-rest-py",null,"Azure Speech to Text REST API for short audio (Python). Use for simple speech recognition of audio files up to 60 seconds without the Speech SDK.\nTriggers: \"speech to text REST\", \"short audio transcription\", \"speech recognition REST API\", \"STT REST\", \"recognize speech REST\".\nDO NOT USE FOR: Long audio (>60 seconds), real-time streaming, batch transcription, custom speech models, speech translation. Use Speech SDK or Batch Transcription API instead.","microsoft\u002Fskills","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69AJYYW4E1RMSYCQDJ4FJSH",3204,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002Fazure-speech-to-text-rest-py\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,9,45],"azure speech","azure","azure speech to text rest py","speech","REST","text","speech to text","for","python","time","stt","do","translation","files","up","short","speech recognition","Audio","api","streaming","batch","sdk","2026-11-10 10:12:30",false,"---\nname: azure-speech-to-text-rest-py\ndescription: |-\n  Azure Speech to Text REST API for short audio (Python). Use for simple speech recognition of audio files up to 60 seconds without the Speech SDK.\n  Triggers: \"speech to text REST\", \"short audio transcription\", \"speech recognition REST API\", \"STT REST\", \"recognize speech REST\".\n  DO NOT USE FOR: Long audio (>60 seconds), real-time streaming, batch transcription, custom speech models, speech translation. Use Speech SDK or Batch Transcription API instead.\nlicense: MIT\nmetadata:\n  author: Microsoft\n  version: \"1.0.0\"\n---\n\n# Azure Speech to Text REST API for Short Audio\n\nSimple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.\n\n## Prerequisites\n\n1. **Azure subscription** - [Create one free](https:\u002F\u002Fazure.microsoft.com\u002Ffree\u002F)\n2. **Speech resource** - Create in [Azure Portal](https:\u002F\u002Fportal.azure.com\u002F#create\u002FMicrosoft.CognitiveServicesSpeechServices)\n3. **Get credentials** - After deployment, go to resource > Keys and Endpoint\n\n## Environment Variables\n\n```bash\n# Required\nAZURE_SPEECH_KEY=\u003Cyour-speech-resource-key>\nAZURE_SPEECH_REGION=\u003Cregion>  # e.g., eastus, westus2, westeurope\n\n# Alternative: Use endpoint directly\nAZURE_SPEECH_ENDPOINT=https:\u002F\u002F\u003Cregion>.stt.speech.microsoft.com\n```\n\n## Installation\n\n```bash\npip install requests\n```\n\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra token (including one acquired with `DefaultAzureCredential`) via the `Authorization` request header (see \"Option 2\" below). Never hardcode credentials in source.\n> 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically:\n>    - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:`\n>    - Async: `async with aiohttp.ClientSession() as session:`\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n\n## Quick Start\n\n```python\nimport os\nimport requests\n\ndef transcribe_audio(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Transcribe short audio file (max 60 seconds) using REST API.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\"\n    }\n    \n    params = {\n        \"language\": language,\n        \"format\": \"detailed\"  # or \"simple\"\n    }\n    \n    with open(audio_file_path, \"rb\") as audio_file:\n        response = requests.post(url, headers=headers, params=params, data=audio_file)\n    \n    response.raise_for_status()\n    return response.json()\n\n# Usage\nresult = transcribe_audio(\"audio.wav\", \"en-US\")\nprint(result[\"DisplayText\"])\n```\n\n## Audio Requirements\n\n| Format | Codec | Sample Rate | Notes |\n|--------|-------|-------------|-------|\n| WAV | PCM | 16 kHz, mono | **Recommended** |\n| OGG | OPUS | 16 kHz, mono | Smaller file size |\n\n**Limitations:**\n- Maximum 60 seconds of audio\n- For pronunciation assessment: maximum 30 seconds\n- No partial\u002Finterim results (final only)\n\n## Content-Type Headers\n\n```python\n# WAV PCM 16kHz\nwav_headers = {\n    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\"\n}\n\n# OGG OPUS\nogg_headers = {\n    \"Content-Type\": \"audio\u002Fogg; codecs=opus\"\n}\n```\n\n## Response Formats\n\n### Simple Format (default)\n\n```python\nparams = {\"language\": \"en-US\", \"format\": \"simple\"}\n```\n\n```json\n{\n  \"RecognitionStatus\": \"Success\",\n  \"DisplayText\": \"Remind me to buy 5 pencils.\",\n  \"Offset\": \"1236645672289\",\n  \"Duration\": \"1236645672289\"\n}\n```\n\n### Detailed Format\n\n```python\nparams = {\"language\": \"en-US\", \"format\": \"detailed\"}\n```\n\n```json\n{\n  \"RecognitionStatus\": \"Success\",\n  \"Offset\": \"1236645672289\",\n  \"Duration\": \"1236645672289\",\n  \"NBest\": [\n    {\n      \"Confidence\": 0.9052885,\n      \"Display\": \"What's the weather like?\",\n      \"ITN\": \"what's the weather like\",\n      \"Lexical\": \"what's the weather like\",\n      \"MaskedITN\": \"what's the weather like\"\n    }\n  ]\n}\n```\n\n## Chunked Transfer (Recommended)\n\nFor lower latency, stream audio in chunks:\n\n```python\nimport os\nimport requests\n\ndef transcribe_chunked(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Stream audio in chunks for lower latency.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\",\n        \"Transfer-Encoding\": \"chunked\",\n        \"Expect\": \"100-continue\"\n    }\n    \n    params = {\"language\": language, \"format\": \"detailed\"}\n    \n    def generate_chunks(file_path: str, chunk_size: int = 1024):\n        with open(file_path, \"rb\") as f:\n            while chunk := f.read(chunk_size):\n                yield chunk\n    \n    response = requests.post(\n        url, \n        headers=headers, \n        params=params, \n        data=generate_chunks(audio_file_path)\n    )\n    \n    response.raise_for_status()\n    return response.json()\n```\n\n## Authentication Options\n\n### Option 1: Subscription Key (Simple)\n\n```python\nheaders = {\n    \"Ocp-Apim-Subscription-Key\": os.environ[\"AZURE_SPEECH_KEY\"]\n}\n```\n\n### Option 2: Bearer Token\n\n```python\nimport requests\nimport os\n\ndef get_access_token() -> str:\n    \"\"\"Get access token from the token endpoint.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    token_url = f\"https:\u002F\u002F{region}.api.cognitive.microsoft.com\u002Fsts\u002Fv1.0\u002FissueToken\"\n    \n    response = requests.post(\n        token_url,\n        headers={\n            \"Ocp-Apim-Subscription-Key\": api_key,\n            \"Content-Type\": \"application\u002Fx-www-form-urlencoded\",\n            \"Content-Length\": \"0\"\n        }\n    )\n    response.raise_for_status()\n    return response.text\n\n# Use token in requests (valid for 10 minutes)\ntoken = get_access_token()\nheaders = {\n    \"Authorization\": f\"Bearer {token}\",\n    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n    \"Accept\": \"application\u002Fjson\"\n}\n```\n\n## Query Parameters\n\n| Parameter | Required | Values | Description |\n|-----------|----------|--------|-------------|\n| `language` | **Yes** | `en-US`, `de-DE`, etc. | Language of speech |\n| `format` | No | `simple`, `detailed` | Result format (default: simple) |\n| `profanity` | No | `masked`, `removed`, `raw` | Profanity handling (default: masked) |\n\n## Recognition Status Values\n\n| Status | Description |\n|--------|-------------|\n| `Success` | Recognition succeeded |\n| `NoMatch` | Speech detected but no words matched |\n| `InitialSilenceTimeout` | Only silence detected |\n| `BabbleTimeout` | Only noise detected |\n| `Error` | Internal service error |\n\n## Profanity Handling\n\n```python\n# Mask profanity with asterisks (default)\nparams = {\"language\": \"en-US\", \"profanity\": \"masked\"}\n\n# Remove profanity entirely\nparams = {\"language\": \"en-US\", \"profanity\": \"removed\"}\n\n# Include profanity as-is\nparams = {\"language\": \"en-US\", \"profanity\": \"raw\"}\n```\n\n## Error Handling\n\n```python\nimport requests\n\ndef transcribe_with_error_handling(audio_path: str, language: str = \"en-US\") -> dict | None:\n    \"\"\"Transcribe with proper error handling.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    try:\n        with open(audio_path, \"rb\") as audio_file:\n            response = requests.post(\n                url,\n                headers={\n                    \"Ocp-Apim-Subscription-Key\": api_key,\n                    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n                    \"Accept\": \"application\u002Fjson\"\n                },\n                params={\"language\": language, \"format\": \"detailed\"},\n                data=audio_file\n            )\n        \n        if response.status_code == 200:\n            result = response.json()\n            if result.get(\"RecognitionStatus\") == \"Success\":\n                return result\n            else:\n                print(f\"Recognition failed: {result.get('RecognitionStatus')}\")\n                return None\n        elif response.status_code == 400:\n            print(f\"Bad request: Check language code or audio format\")\n        elif response.status_code == 401:\n            print(f\"Unauthorized: Check API key or token\")\n        elif response.status_code == 403:\n            print(f\"Forbidden: Missing authorization header\")\n        else:\n            print(f\"Error {response.status_code}: {response.text}\")\n        \n        return None\n        \n    except requests.exceptions.RequestException as e:\n        print(f\"Request failed: {e}\")\n        return None\n```\n\n## Async Version\n\n```python\nimport os\nimport aiohttp\nimport asyncio\n\nasync def transcribe_async(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Async version using aiohttp.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\"\n    }\n    \n    params = {\"language\": language, \"format\": \"detailed\"}\n    \n    async with aiohttp.ClientSession() as session:\n        with open(audio_file_path, \"rb\") as f:\n            audio_data = f.read()\n        \n        async with session.post(url, headers=headers, params=params, data=audio_data) as response:\n            response.raise_for_status()\n            return await response.json()\n\n# Usage\nresult = asyncio.run(transcribe_async(\"audio.wav\", \"en-US\"))\nprint(result[\"DisplayText\"])\n```\n\n## Supported Languages\n\nCommon language codes (see [full list](https:\u002F\u002Flearn.microsoft.com\u002Fazure\u002Fai-services\u002Fspeech-service\u002Flanguage-support)):\n\n| Code | Language |\n|------|----------|\n| `en-US` | English (US) |\n| `en-GB` | English (UK) |\n| `de-DE` | German |\n| `fr-FR` | French |\n| `es-ES` | Spanish (Spain) |\n| `es-MX` | Spanish (Mexico) |\n| `zh-CN` | Chinese (Mandarin) |\n| `ja-JP` | Japanese |\n| `ko-KR` | Korean |\n| `pt-BR` | Portuguese (Brazil) |\n\n## Best Practices\n\n1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module.\n2. **Use context managers for files and HTTP resources.** Use `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` for sync code, or `async with aiohttp.ClientSession() as session:` for async code.\n3. **Use WAV PCM 16kHz mono** for best compatibility\n4. **Enable chunked transfer** for lower latency\n5. **Cache access tokens** for 9 minutes (valid for 10)\n6. **Specify the correct language** for accurate recognition\n7. **Use detailed format** when you need confidence scores\n8. **Handle all RecognitionStatus values** in production code\n\n## When NOT to Use This API\n\nUse the Speech SDK or Batch Transcription API instead when you need:\n\n- Audio longer than 60 seconds\n- Real-time streaming transcription\n- Partial\u002Finterim results\n- Speech translation\n- Custom speech models\n- Batch transcription of many files\n\n## Reference Files\n\n| File | Contents |\n|------|----------|\n| [references\u002Fpronunciation-assessment.md](references\u002Fpronunciation-assessment.md) | Pronunciation assessment parameters and scoring |\n","# Azure Speech to Text REST API for Short Audio\n\nSimple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.\n\n## Prerequisites\n\n1. **Azure subscription** - [Create one free](https:\u002F\u002Fazure.microsoft.com\u002Ffree\u002F)\n2. **Speech resource** - Create in [Azure Portal](https:\u002F\u002Fportal.azure.com\u002F#create\u002FMicrosoft.CognitiveServicesSpeechServices)\n3. **Get credentials** - After deployment, go to resource > Keys and Endpoint\n\n## Environment Variables\n\n```bash\n# Required\nAZURE_SPEECH_KEY=\u003Cyour-speech-resource-key>\nAZURE_SPEECH_REGION=\u003Cregion>  # e.g., eastus, westus2, westeurope\n\n# Alternative: Use endpoint directly\nAZURE_SPEECH_ENDPOINT=https:\u002F\u002F\u003Cregion>.stt.speech.microsoft.com\n```\n\n## Installation\n\n```bash\npip install requests\n```\n\n## Authentication & Lifecycle\n\n> **? Two rules apply to every code sample below:**\n>\n> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra token (including one acquired with `DefaultAzureCredential`) via the `Authorization` request header (see \"Option 2\" below). Never hardcode credentials in source.\n> 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically:\n>    - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:`\n>    - Async: `async with aiohttp.ClientSession() as session:`\n>\n> Snippets may abbreviate this setup, but production code should always follow both rules.\n\n## Quick Start\n\n```python\nimport os\nimport requests\n\ndef transcribe_audio(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Transcribe short audio file (max 60 seconds) using REST API.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\"\n    }\n    \n    params = {\n        \"language\": language,\n        \"format\": \"detailed\"  # or \"simple\"\n    }\n    \n    with open(audio_file_path, \"rb\") as audio_file:\n        response = requests.post(url, headers=headers, params=params, data=audio_file)\n    \n    response.raise_for_status()\n    return response.json()\n\n# Usage\nresult = transcribe_audio(\"audio.wav\", \"en-US\")\nprint(result[\"DisplayText\"])\n```\n\n## Audio Requirements\n\n| Format | Codec | Sample Rate | Notes |\n|--------|-------|-------------|-------|\n| WAV | PCM | 16 kHz, mono | **Recommended** |\n| OGG | OPUS | 16 kHz, mono | Smaller file size |\n\n**Limitations:**\n- Maximum 60 seconds of audio\n- For pronunciation assessment: maximum 30 seconds\n- No partial\u002Finterim results (final only)\n\n## Content-Type Headers\n\n```python\n# WAV PCM 16kHz\nwav_headers = {\n    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\"\n}\n\n# OGG OPUS\nogg_headers = {\n    \"Content-Type\": \"audio\u002Fogg; codecs=opus\"\n}\n```\n\n## Response Formats\n\n### Simple Format (default)\n\n```python\nparams = {\"language\": \"en-US\", \"format\": \"simple\"}\n```\n\n```json\n{\n  \"RecognitionStatus\": \"Success\",\n  \"DisplayText\": \"Remind me to buy 5 pencils.\",\n  \"Offset\": \"1236645672289\",\n  \"Duration\": \"1236645672289\"\n}\n```\n\n### Detailed Format\n\n```python\nparams = {\"language\": \"en-US\", \"format\": \"detailed\"}\n```\n\n```json\n{\n  \"RecognitionStatus\": \"Success\",\n  \"Offset\": \"1236645672289\",\n  \"Duration\": \"1236645672289\",\n  \"NBest\": [\n    {\n      \"Confidence\": 0.9052885,\n      \"Display\": \"What's the weather like?\",\n      \"ITN\": \"what's the weather like\",\n      \"Lexical\": \"what's the weather like\",\n      \"MaskedITN\": \"what's the weather like\"\n    }\n  ]\n}\n```\n\n## Chunked Transfer (Recommended)\n\nFor lower latency, stream audio in chunks:\n\n```python\nimport os\nimport requests\n\ndef transcribe_chunked(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Stream audio in chunks for lower latency.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\",\n        \"Transfer-Encoding\": \"chunked\",\n        \"Expect\": \"100-continue\"\n    }\n    \n    params = {\"language\": language, \"format\": \"detailed\"}\n    \n    def generate_chunks(file_path: str, chunk_size: int = 1024):\n        with open(file_path, \"rb\") as f:\n            while chunk := f.read(chunk_size):\n                yield chunk\n    \n    response = requests.post(\n        url, \n        headers=headers, \n        params=params, \n        data=generate_chunks(audio_file_path)\n    )\n    \n    response.raise_for_status()\n    return response.json()\n```\n\n## Authentication Options\n\n### Option 1: Subscription Key (Simple)\n\n```python\nheaders = {\n    \"Ocp-Apim-Subscription-Key\": os.environ[\"AZURE_SPEECH_KEY\"]\n}\n```\n\n### Option 2: Bearer Token\n\n```python\nimport requests\nimport os\n\ndef get_access_token() -> str:\n    \"\"\"Get access token from the token endpoint.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    token_url = f\"https:\u002F\u002F{region}.api.cognitive.microsoft.com\u002Fsts\u002Fv1.0\u002FissueToken\"\n    \n    response = requests.post(\n        token_url,\n        headers={\n            \"Ocp-Apim-Subscription-Key\": api_key,\n            \"Content-Type\": \"application\u002Fx-www-form-urlencoded\",\n            \"Content-Length\": \"0\"\n        }\n    )\n    response.raise_for_status()\n    return response.text\n\n# Use token in requests (valid for 10 minutes)\ntoken = get_access_token()\nheaders = {\n    \"Authorization\": f\"Bearer {token}\",\n    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n    \"Accept\": \"application\u002Fjson\"\n}\n```\n\n## Query Parameters\n\n| Parameter | Required | Values | Description |\n|-----------|----------|--------|-------------|\n| `language` | **Yes** | `en-US`, `de-DE`, etc. | Language of speech |\n| `format` | No | `simple`, `detailed` | Result format (default: simple) |\n| `profanity` | No | `masked`, `removed`, `raw` | Profanity handling (default: masked) |\n\n## Recognition Status Values\n\n| Status | Description |\n|--------|-------------|\n| `Success` | Recognition succeeded |\n| `NoMatch` | Speech detected but no words matched |\n| `InitialSilenceTimeout` | Only silence detected |\n| `BabbleTimeout` | Only noise detected |\n| `Error` | Internal service error |\n\n## Profanity Handling\n\n```python\n# Mask profanity with asterisks (default)\nparams = {\"language\": \"en-US\", \"profanity\": \"masked\"}\n\n# Remove profanity entirely\nparams = {\"language\": \"en-US\", \"profanity\": \"removed\"}\n\n# Include profanity as-is\nparams = {\"language\": \"en-US\", \"profanity\": \"raw\"}\n```\n\n## Error Handling\n\n```python\nimport requests\n\ndef transcribe_with_error_handling(audio_path: str, language: str = \"en-US\") -> dict | None:\n    \"\"\"Transcribe with proper error handling.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    try:\n        with open(audio_path, \"rb\") as audio_file:\n            response = requests.post(\n                url,\n                headers={\n                    \"Ocp-Apim-Subscription-Key\": api_key,\n                    \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n                    \"Accept\": \"application\u002Fjson\"\n                },\n                params={\"language\": language, \"format\": \"detailed\"},\n                data=audio_file\n            )\n        \n        if response.status_code == 200:\n            result = response.json()\n            if result.get(\"RecognitionStatus\") == \"Success\":\n                return result\n            else:\n                print(f\"Recognition failed: {result.get('RecognitionStatus')}\")\n                return None\n        elif response.status_code == 400:\n            print(f\"Bad request: Check language code or audio format\")\n        elif response.status_code == 401:\n            print(f\"Unauthorized: Check API key or token\")\n        elif response.status_code == 403:\n            print(f\"Forbidden: Missing authorization header\")\n        else:\n            print(f\"Error {response.status_code}: {response.text}\")\n        \n        return None\n        \n    except requests.exceptions.RequestException as e:\n        print(f\"Request failed: {e}\")\n        return None\n```\n\n## Async Version\n\n```python\nimport os\nimport aiohttp\nimport asyncio\n\nasync def transcribe_async(audio_file_path: str, language: str = \"en-US\") -> dict:\n    \"\"\"Async version using aiohttp.\"\"\"\n    region = os.environ[\"AZURE_SPEECH_REGION\"]\n    api_key = os.environ[\"AZURE_SPEECH_KEY\"]\n    \n    url = f\"https:\u002F\u002F{region}.stt.speech.microsoft.com\u002Fspeech\u002Frecognition\u002Fconversation\u002Fcognitiveservices\u002Fv1\"\n    \n    headers = {\n        \"Ocp-Apim-Subscription-Key\": api_key,\n        \"Content-Type\": \"audio\u002Fwav; codecs=audio\u002Fpcm; samplerate=16000\",\n        \"Accept\": \"application\u002Fjson\"\n    }\n    \n    params = {\"language\": language, \"format\": \"detailed\"}\n    \n    async with aiohttp.ClientSession() as session:\n        with open(audio_file_path, \"rb\") as f:\n            audio_data = f.read()\n        \n        async with session.post(url, headers=headers, params=params, data=audio_data) as response:\n            response.raise_for_status()\n            return await response.json()\n\n# Usage\nresult = asyncio.run(transcribe_async(\"audio.wav\", \"en-US\"))\nprint(result[\"DisplayText\"])\n```\n\n## Supported Languages\n\nCommon language codes (see [full list](https:\u002F\u002Flearn.microsoft.com\u002Fazure\u002Fai-services\u002Fspeech-service\u002Flanguage-support)):\n\n| Code | Language |\n|------|----------|\n| `en-US` | English (US) |\n| `en-GB` | English (UK) |\n| `de-DE` | German |\n| `fr-FR` | French |\n| `es-ES` | Spanish (Spain) |\n| `es-MX` | Spanish (Mexico) |\n| `zh-CN` | Chinese (Mandarin) |\n| `ja-JP` | Japanese |\n| `ko-KR` | Korean |\n| `pt-BR` | Portuguese (Brazil) |\n\n## Best Practices\n\n1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module.\n2. **Use context managers for files and HTTP resources.** Use `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` for sync code, or `async with aiohttp.ClientSession() as session:` for async code.\n3. **Use WAV PCM 16kHz mono** for best compatibility\n4. **Enable chunked transfer** for lower latency\n5. **Cache access tokens** for 9 minutes (valid for 10)\n6. **Specify the correct language** for accurate recognition\n7. **Use detailed format** when you need confidence scores\n8. **Handle all RecognitionStatus values** in production code\n\n## When NOT to Use This API\n\nUse the Speech SDK or Batch Transcription API instead when you need:\n\n- Audio longer than 60 seconds\n- Real-time streaming transcription\n- Partial\u002Finterim results\n- Speech translation\n- Custom speech models\n- Batch transcription of many files\n\n## Reference Files\n\n| File | Contents |\n|------|----------|\n| [references\u002Fpronunciation-assessment.md](references\u002Fpronunciation-assessment.md) | Pronunciation assessment parameters and scoring |\n",{"name":5,"license":15,"metadata":51,"description":7},{"author":12,"version":52},"1.0.0","main","3f5b461b2314e01c400564051e92469114c5b68f",".github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002Fazure-speech-to-text-rest-py",368,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills","https:\u002F\u002Fmicrosoft.github.io\u002Fskills\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 06:48:25",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add microsoft\u002Fskills --skill azure-speech-to-text-rest-py",{"tool":69,"command":70},"bunx","bunx skills add microsoft\u002Fskills --skill azure-speech-to-text-rest-py",{"tool":72,"command":73},"pnpm","pnpm dlx skills add microsoft\u002Fskills --skill azure-speech-to-text-rest-py","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002Fazure-speech-to-text-rest-py\u002FSKILL.md",true,[77],{"path":78,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fpronunciation-assessment.md","REFERENCE","参考文档",7772,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-python\u002Fskills\u002Fazure-speech-to-text-rest-py\u002Freferences\u002Fpronunciation-assessment.md",[84,92,118,149,176,196],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":91},"01M741JBE1VH8A2Y3FXX2P7386","azure-advisor-cost-optimization","Analyze Azure Advisor Cost\u002FIdleResources findings and prevalidate deletion safety, including Service Groups. WHEN: \"find unused Azure resources\", \"what resources am I paying for but no longer using\", \"idle-resource savings\", \"historical idle-resource savings\", \"are these idle resources safe to delete\". Generic Cost, other subcategories, and cross-category requests use azure-advisor.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-advisor\u002Fskills\u002Fazure-advisor-cost-optimization\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":101,"publishedAt":46},"01M69B4JCRQV5SPXAFCKXQRV0H","skill-creator","Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002FSKILL.md",[98],{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[102,103,104,105,9,25,106,107,108,109,31,110,111,112,113,114,115,116,117],"skill creator","creator","ai coding agents","coding agents","foundry","microsoft foundry","coding","guide","use","Existing","services","new","when","sdks","with","ai coding",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":132,"publishedAt":46},"01M69B4FD57V1MYKRWAJJECTZ7","podcast-generation","Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fpodcast-generation\u002FSKILL.md",[124,127,130,131],{"categoryNo":125,"categoryName":126,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":128,"categoryName":129,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},[133,134,135,136,25,137,138,139,32,41,140,141,142,143,144,114,42,43,29,145,146,147,148],"podcast generation","generation","podcast","frontend","azure openai","realtime","react","creation","model","fastapi backend","python fastapi","fastapi","narrative","stack","generate","features",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":156,"publishedAt":46},"01M69B4CYPM5SESY5ZWEFDXEQZ","microsoft-docs","Understand Microsoft technologies by querying official documentation. Use whenever the user asks how something works, wants tutorials, needs configuration options, limits, quotas, or best practices for any Microsoft technology (Azure, .NET, M365, Windows, Power Platform, etc.)—even if they don't mention \"docs.\" If the question is about understanding a concept rather than writing code, this is the right skill.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmicrosoft-docs\u002FSKILL.md",[155],{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},[157,9,158,159,160,161,162,25,163,164,165,166,167,168,169,170,31,171,66,172,110,173,174,175],"microsoft docs","docs","documentation","windows","official","cli","MCP","writing","power platform","mcp server","back","concept","power","platform","technology","question","learn mcp","learn","best practices",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":183,"publishedAt":46},"01M69B49C3YPD1ZJ3NC0HPCY58","mcp-builder","Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node\u002FTypeScript (MCP SDK), or C#\u002F.NET (Microsoft MCP SDK).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmcp-builder\u002FSKILL.md",[182],{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},[184,163,185,186,45,9,32,187,188,141,189,114,190,191,192,109,193,194,31,195,110,116],"mcp builder","builder","llms","typescript","model context protocol","building mcp servers","node","integrate","Tools","context","fastmcp","mcp sdk",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":214,"publishedAt":46},"01M69B467A7CDMFQ0T6Q0ZA12Q","kql","KQL language expertise for writing correct, efficient Kusto Query Language queries. Covers syntax gotchas, join patterns, dynamic types, datetime pitfalls, regex patterns, serialization, memory management, result-size discipline, and advanced functions (geo, vector, graph). USE THIS SKILL whenever writing, debugging, or reviewing KQL queries — even simple ones — because the gotchas section prevents the most common errors that waste tool calls and cause expensive retry cascades. Trigger on: KQL, Kusto, ADX, Azure Data Explorer, Fabric Real-Time Intelligence, EventHouse, Log Analytics, log analysis, data exploration, time series, anomaly detection, summarize, where clause, join, extend, project, let statement, parse operator, extract function, any mention of pipe-forward query syntax.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fkql\u002FSKILL.md",[202,205,206,211],{"categoryNo":203,"categoryName":204,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":207,"categoryName":208,"taxonomyType":209,"taxonomyTypeDesc":210},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",{"categoryNo":212,"categoryName":213,"taxonomyType":209,"taxonomyTypeDesc":210},"01JBSEEDCAT000000000000036","内容创作者",[198,25,164,215,216,217,218,219,220,33,221,222,223,224,225,226,227,228,229,31,230,231,232],"analytics","memory","summarize","exploration","parse","project","vector","join","log","pipe","datetime","discipline","time series","regex","anomaly","section","tool","geo"]