AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗原件 ↓仓库 ↗

Azure Speech to Text REST API Acceptance Criteria ​

API: Azure Speech to Text REST API for Short Audio Documentation: https://learn.microsoft.com/en-us/azure/ai-services/speech-service/rest-speech-to-text-shortPurpose: Skill testing acceptance criteria for validating generated code correctness

1. HTTP Request Construction ​

1.1 ✅ CORRECT: REST API URL Format ​

python
import os

region = os.environ["AZURE_SPEECH_REGION"]
url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"

1.2 ✅ CORRECT: Alternative Recognition Mode ​

python
# For dictation (longer pauses allowed)
url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/dictation/cognitiveservices/v1"

1.3 ❌ INCORRECT: Wrong URL format ​

python
# WRONG - Missing stt subdomain
url = f"https://{region}.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"

# WRONG - Using API instead of stt
url = f"https://{region}.api.cognitive.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"

# WRONG - Using SDK-style endpoint
url = f"https://{region}.cognitiveservices.azure.com/speech"

2. Authentication ​

2.1 ✅ CORRECT: Subscription Key Header ​

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

2.2 ✅ CORRECT: Bearer Token Authentication ​

python
def get_access_token() -> str:
    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

token = get_access_token()
headers = {"Authorization": f"Bearer {token}"}

2.3 ❌ INCORRECT: Wrong authentication ​

python
# WRONG - Hardcoded credentials
headers = {"Ocp-Apim-Subscription-Key": "abc123"}

# WRONG - Wrong header name
headers = {"X-Api-Key": os.environ["AZURE_SPEECH_KEY"]}

# WRONG - Using AzureKeyCredential (this is REST API, not SDK)
from azure.core.credentials import AzureKeyCredential
credential = AzureKeyCredential(os.environ["AZURE_SPEECH_KEY"])

3. Content-Type Headers ​

3.1 ✅ CORRECT: WAV PCM 16kHz ​

python
headers = {
    "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000"
}

3.2 ✅ CORRECT: OGG OPUS ​

python
headers = {
    "Content-Type": "audio/ogg; codecs=opus"
}

3.3 ❌ INCORRECT: Wrong content type ​

python
# WRONG - Missing codec and sample rate
headers = {"Content-Type": "audio/wav"}

# WRONG - Wrong MIME type
headers = {"Content-Type": "audio/mpeg"}

# WRONG - Missing codecs parameter
headers = {"Content-Type": "audio/ogg"}

4. Request Parameters ​

4.1 ✅ CORRECT: Required Language Parameter ​

python
params = {
    "language": "en-US"
}

4.2 ✅ CORRECT: Full Parameters ​

python
params = {
    "language": "en-US",
    "format": "detailed",  # or "simple"
    "profanity": "masked"  # or "removed", "raw"
}

4.3 ❌ INCORRECT: Missing language ​

python
# WRONG - Language is required
params = {"format": "detailed"}

# WRONG - Using locale instead of language
params = {"locale": "en-US"}

5. Making the Request ​

5.1 ✅ CORRECT: Basic Request ​

python
import requests

def transcribe_audio(audio_file_path: str, language: str = "en-US") -> dict:
    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"}
    
    with open(audio_file_path, "rb") as audio_file:
        response = requests.post(url, headers=headers, params=params, data=audio_file)
    
    response.raise_for_status()
    return response.json()

5.2 ✅ CORRECT: Chunked Transfer for Lower Latency ​

python
def transcribe_chunked(audio_file_path: str) -> dict:
    headers = {
        "Ocp-Apim-Subscription-Key": os.environ["AZURE_SPEECH_KEY"],
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Transfer-Encoding": "chunked",
        "Expect": "100-continue"
    }
    
    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))
    return response.json()

5.3 ❌ INCORRECT: Wrong request method or format ​

python
# WRONG - GET instead of POST
response = requests.get(url, headers=headers, params=params)

# WRONG - Using JSON body instead of binary audio
response = requests.post(url, headers=headers, json={"audio": audio_data})

# WRONG - Using Speech SDK client
from azure.cognitiveservices.speech import SpeechRecognizer

6. Response Handling ​

6.1 ✅ CORRECT: Simple Response ​

python
result = response.json()
if result.get("RecognitionStatus") == "Success":
    print(result["DisplayText"])

6.2 ✅ CORRECT: Detailed Response with NBest ​

python
result = response.json()
if result.get("RecognitionStatus") == "Success":
    for item in result.get("NBest", []):
        print(f"Text: {item['Display']}")
        print(f"Confidence: {item['Confidence']}")

6.3 ✅ CORRECT: Status Handling ​

python
status = result.get("RecognitionStatus")
if status == "Success":
    print(result["DisplayText"])
elif status == "NoMatch":
    print("No speech detected")
elif status == "InitialSilenceTimeout":
    print("Only silence detected")
elif status == "BabbleTimeout":
    print("Only noise detected")
else:
    print(f"Error: {status}")

6.4 ❌ INCORRECT: Wrong response access ​

python
# WRONG - Using lowercase keys
print(result["displayText"])

# WRONG - Assuming always has text
print(result["DisplayText"])  # May be None if NoMatch

# WRONG - SDK-style response
print(result.text)

7. Async Version ​

7.1 ✅ CORRECT: Using aiohttp ​

python
import aiohttp
import asyncio

async def transcribe_async(audio_file_path: str, language: str = "en-US") -> dict:
    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()

7.2 ❌ INCORRECT: Blocking in async ​

python
# WRONG - Using blocking requests in async
async def transcribe_wrong():
    response = requests.post(url, data=audio)  # Blocks event loop

8. Error Handling ​

8.1 ✅ CORRECT: HTTP and Recognition Errors ​

python
try:
    response = requests.post(url, headers=headers, params=params, 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')}")
    elif response.status_code == 400:
        print("Bad request: Check language code or audio format")
    elif response.status_code == 401:
        print("Unauthorized: Check API key")
    elif response.status_code == 403:
        print("Forbidden: Missing authorization header")
        
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

8.2 ❌ INCORRECT: No error handling ​

python
# WRONG - No error handling
response = requests.post(url, data=audio)
return response.json()["DisplayText"]

9. Do NOT Use ​

9.1 ❌ INCORRECT: Using Speech SDK ​

python
# WRONG - This skill is for REST API, not SDK
from azure.cognitiveservices.speech import SpeechRecognizer
from azure.cognitiveservices.speech import SpeechConfig

# WRONG - SDK-style configuration
speech_config = SpeechConfig(subscription=key, region=region)

9.2 ❌ INCORRECT: Using Azure SDK Credentials ​

python
# WRONG - REST API doesn't use Azure SDK credentials
from azure.identity import DefaultAzureCredential
from azure.core.credentials import AzureKeyCredential

10. Audio Limitations ​

10.1 ✅ CORRECT: Documented Limits ​

  • Maximum audio duration: 60 seconds
  • For pronunciation assessment: 30 seconds maximum
  • Supported formats: WAV PCM 16kHz mono, OGG OPUS

10.2 ❌ INCORRECT: Exceeding Limits ​

python
# WRONG - No validation of audio length
# Audio > 60 seconds will fail

Summary: Key Patterns ​

PatternCorrectIncorrect
URL format\{region\}.stt.speech.microsoft.com\{region\}.speech.microsoft.com
Auth headerOcp-Apim-Subscription-KeyX-Api-Key, hardcoded
Content-Typeaudio/wav; codecs=audio/pcm; samplerate=16000audio/wav (missing params)
Required paramlanguage=en-USMissing or locale=en-US
Response keyRecognitionStatus, DisplayTextrecognitionStatus, displayText
Libraryrequests, aiohttpazure.cognitiveservices.speech