Labsco
microsoft logo

azure-speech-to-text-rest-py

✓ Official★ 2,700

by microsoft · part of microsoft/skills

Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.

🔥🔥🔥✓ VerifiedFreeQuick setup
#voice#cloud#devops#git#weather#translation
🧩 One of 7 skills in the microsoft/skills package — works on its own, and pairs well with its siblings.

Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by microsoft

Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests. npx skills add https://github.com/microsoft/agent-skills --skill azure-speech-to-text-rest-py Download ZIPGitHub2.7k

Azure Speech to Text REST API for Short Audio

Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.

Environment Variables

Copy & paste — that's it
# Required
AZURE_SPEECH_KEY= 
AZURE_SPEECH_REGION= # e.g., eastus, westus2, westeurope

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

Content-Type Headers

Copy & paste — that's it
# WAV PCM 16kHz
"Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000"

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

Response Formats

Simple Format (default)

Copy & paste — that's it
params = {"language": "en-US", "format": "simple"}
Copy & paste — that's it
{
 "RecognitionStatus": "Success",
 "DisplayText": "Remind me to buy 5 pencils.",
 "Offset": "1236645672289",
 "Duration": "1236645672289"
}

Detailed Format

Copy & paste — that's it
params = {"language": "en-US", "format": "detailed"}
Copy & paste — that's it
{
 "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"
 }
 ]
}

Chunked Transfer (Recommended)

For lower latency, stream audio in chunks:

Copy & paste — that's it
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)
 )
 
 response.raise_for_status()
 return response.json()

Authentication Options

Option 1: Subscription Key (Simple)

Copy & paste — that's it
headers = {
 "Ocp-Apim-Subscription-Key": os.environ["AZURE_SPEECH_KEY"]
}

Option 2: Bearer Token

Copy & paste — that's it
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"
 }
 )
 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"
}

Query Parameters

Parameter Required Values Description language Yes en-US, de-DE, etc. Language of speech format No simple, detailed Result format (default: simple) profanity No masked, removed, raw Profanity handling (default: masked)

Recognition Status Values

Status Description Success Recognition succeeded NoMatch Speech detected but no words matched InitialSilenceTimeout Only silence detected BabbleTimeout Only noise detected Error Internal service error

Profanity Handling

Copy & paste — that's it
# 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"}

Error Handling

Copy & paste — that's it
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
 )
 
 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(f"Forbidden: Missing authorization header")
 else:
 print(f"Error {response.status_code}: {response.text}")
 
 return None
 
 except requests.exceptions.RequestException as e:
 print(f"Request failed: {e}")
 return None

Async Version

Copy & paste — that's it
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() 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"))
print(result["DisplayText"])

Supported Languages

Common language codes (see full list):

Code Language en-US English (US) en-GB English (UK) de-DE German fr-FR French es-ES Spanish (Spain) es-MX Spanish (Mexico) zh-CN Chinese (Mandarin) ja-JP Japanese ko-KR Korean pt-BR Portuguese (Brazil)

Best Practices

  • 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.

  • Always use context managers for clients. Use with httpx.Client(...) as client: (sync) or async with httpx.AsyncClient(...) as client: (async) so connections are pooled and closed deterministically.

  • Use WAV PCM 16kHz mono for best compatibility

  • Enable chunked transfer for lower latency

  • Cache access tokens for 9 minutes (valid for 10)

  • Specify the correct language for accurate recognition

  • Use detailed format when you need confidence scores

  • Handle all RecognitionStatus values in production code

When NOT to Use This API

Use the Speech SDK or Batch Transcription API instead when you need:

  • Audio longer than 60 seconds

  • Real-time streaming transcription

  • Partial/interim results

  • Speech translation

  • Custom speech models

  • Batch transcription of many files

Reference Files

File Contents references/pronunciation-assessment.md Pronunciation assessment parameters and scoring