REST API voor spraak-naar-tekst voor korte audio
Use cases for the Speech to text REST API for short audio are limited. Gebruik deze alleen in gevallen waarin u de Speech SDK niet kunt gebruiken.
Voordat u de Speech to Text REST API voor korte audio gebruikt, moet u rekening houden met de volgende beperkingen:
- Aanvragen die gebruikmaken van de REST API voor korte audio en het rechtstreeks verzenden van audio kunnen niet meer dan 60 seconden audio bevatten. De audio-indelingen voor invoer zijn beperkter in vergelijking met de Speech SDK.
- De REST API voor korte audio retourneert alleen uiteindelijke resultaten. Het biedt geen gedeeltelijke resultaten.
- Spraakomzetting wordt niet ondersteund via REST API voor korte audio. U moet speech-SDK gebruiken.
- Batchtranscriptie en aangepaste spraak worden niet ondersteund via REST API voor korte audio. U moet altijd de Speech to Text REST API gebruiken voor batchtranscriptie en aangepaste spraak.
Voordat u de Speech to Text REST API voor korte audio gebruikt, moet u een tokenuitwisseling voltooien als onderdeel van verificatie voor toegang tot de service. Zie Verificatie voor meer informatie.
Regio's en eindpunten
Het eindpunt voor de REST API voor korte audio heeft deze indeling:
https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1
Vervang <REGION_IDENTIFIER> door de id die overeenkomt met de regio van uw Spraak-resource.
Notitie
Zie dit artikel over onafhankelijke clouds voor Azure Government en Microsoft Azure beheerd door 21Vianet-eindpunten.
Audio-indelingen
Audio wordt verzonden in de hoofdtekst van de HTTP-aanvraag POST . Deze moet een van de notaties in deze tabel hebben:
| Indeling | Codec | Bitrate | Samplefrequentie |
|---|---|---|---|
| WAV | PCM | 256 kbps | 16 kHz, mono |
| OGG | OPUS | 256 kbps | 16 kHz, mono |
Notitie
De voorgaande indelingen worden ondersteund via de REST API voor korte audio en WebSocket in de Speech-service. De Speech SDK ondersteunt de WAV-indeling met PCM-codec en andere indelingen.
Aanvraagheaders
Deze tabel bevat vereiste en optionele headers voor spraak-naar-tekstaanvragen:
| Koptekst | Beschrijving | Vereist of optioneel |
|---|---|---|
Ocp-Apim-Subscription-Key |
Uw resourcesleutel voor de Speech-service. | Deze header of Authorization is vereist. |
Authorization |
Een autorisatietoken voorafgegaan door het woord Bearer. Zie Verificatie voor meer informatie. |
Deze header of Ocp-Apim-Subscription-Key is vereist. |
Pronunciation-Assessment |
Hiermee geeft u de parameters voor het weergeven van uitspraakscores in herkenningsresultaten. Deze scores beoordelen de uitspraakkwaliteit van spraakinvoer, met indicatoren zoals nauwkeurigheid, vloeiendheid en volledigheid. Deze parameter is een met Base64 gecodeerde JSON die meerdere gedetailleerde parameters bevat. Zie De beoordelingsparameters van de uitspraak voor meer informatie over het bouwen van deze header. |
Optioneel |
Content-type |
Beschrijft de indeling en codec van de opgegeven audiogegevens. Geaccepteerde waarden zijn audio/wav; codecs=audio/pcm; samplerate=16000 en audio/ogg; codecs=opus. |
Vereist |
Transfer-Encoding |
Hiermee geeft u op dat gesegmenteerde audiogegevens worden verzonden in plaats van één bestand. Gebruik deze koptekst alleen als u audiogegevens segmenteert. | Optioneel |
Expect |
Als u gesegmenteerde overdracht gebruikt, verzendt u het Expect: 100-continue. De Speech-service bevestigt de eerste aanvraag en wacht op meer gegevens. |
Vereist als u gesegmenteerde audiogegevens verzendt. |
Accept |
Indien opgegeven, moet het zijn application/json. De Speech-service levert resultaten in JSON. Sommige aanvraagframeworks bieden een niet-compatibele standaardwaarde. Het is een goede gewoonte om altijd op te nemen Accept. |
Optioneel, maar aanbevolen. |
Queryparameters
Deze parameters kunnen worden opgenomen in de querytekenreeks van de REST-aanvraag.
Notitie
U moet de taalparameter toevoegen aan de URL om te voorkomen dat er een 4xx HTTP-fout wordt weergegeven. De taal die is ingesteld op Amerikaans-Engels via het eindpunt VS - west is bijvoorbeeld: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.
| Parameter | Description | Vereist of optioneel |
|---|---|---|
language |
Identificeert de gesproken taal die wordt herkend. Zie ondersteunde talen. | Vereist |
format |
Hiermee geeft u de resultaatindeling op. Geaccepteerde waarden zijn simple en detailed. Eenvoudige resultaten zijn onder andere RecognitionStatus, DisplayText, Offseten Duration. Gedetailleerde antwoorden bevatten vier verschillende weergaven van weergavetekst. De standaardinstelling is simple. |
Optioneel |
profanity |
Hiermee geeft u op hoe grof taalgebruik moet worden verwerkt in herkenningsresultaten. Geaccepteerde waarden zijn: masked, die grof taalgebruik vervangt door sterretjes. removed, waarmee alle grof taalgebruik uit het resultaat wordt verwijderd. raw, die grof taalgebruik in het resultaat omvat. De standaardinstelling is masked. |
Optioneel |
cid |
Wanneer u Speech Studio gebruikt om aangepaste modellen te maken, kunt u profiteren van de waarde van de eindpunt-id op de pagina Implementatie. Gebruik de waarde eindpunt-id als argument voor de cid querytekenreeksparameter. |
Optioneel |
Beoordelingsparameters voor uitspraak
Deze tabel bevat vereiste en optionele parameters voor uitspraakbeoordeling:
| Parameter | Description | Vereist of optioneel |
|---|---|---|
ReferenceText |
De tekst waarop de uitspraak wordt geëvalueerd. | Vereist |
GradingSystem |
Het puntsysteem voor de kalibratie van de score. Het FivePoint systeem geeft een drijvende kommascore van 0-5 en HundredMark geeft een 0-100 drijvende kommascore. Standaard: FivePoint. |
Optioneel |
Granularity |
De granulariteit van de evaluatie. Geaccepteerde waarden zijn:Phoneme, waarin de score wordt weergegeven op de niveaus voor volledige tekst, woord en telefoon.Word, waarmee de score wordt weergegeven op de volledige tekst- en woordniveaus. FullText, waarmee de score alleen op volledig tekstniveau wordt weergegeven.De standaardinstelling is Phoneme. |
Optioneel |
Dimension |
Definieert de uitvoercriteria. Geaccepteerde waarden zijn:Basic, waarmee alleen de nauwkeurigheidsscore wordt weergegeven. Comprehensive, waarin scores voor meer dimensies worden weergegeven (bijvoorbeeld de beoordeling van de vloeiendheid en volledigheid op het niveau van de volledige tekst en het fouttype op het woordniveau).Zie de antwoordeigenschappen voor definities van verschillende scoredimensies en woordfouttypen. De standaardinstelling is Basic. |
Optioneel |
EnableMiscue |
Hiermee schakelt u een onjuiste berekening in. Als deze parameter is ingeschakeld, worden de uitgesproken woorden vergeleken met de verwijzingstekst. Ze worden gemarkeerd met weglating of invoeging op basis van de vergelijking. Geaccepteerde waarden zijn False en True. De standaardinstelling is False. |
Optioneel |
ScenarioId |
Een GUID die een aangepast puntsysteem aangeeft. | Optioneel |
Hier volgt een voorbeeld van JSON dat de beoordelingsparameters van de uitspraak bevat:
{
"ReferenceText": "Good morning.",
"GradingSystem": "HundredMark",
"Granularity": "FullText",
"Dimension": "Comprehensive"
}
In de volgende voorbeeldcode ziet u hoe u de beoordelingsparameters van de uitspraak in de Pronunciation-Assessment header kunt bouwen:
var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);
We raden u ten zeerste aan streaming (gesegmenteerde overdracht) te uploaden terwijl u de audiogegevens plaatst, waardoor de latentie aanzienlijk kan worden verminderd. Zie de voorbeeldcode in verschillende programmeertalen voor meer informatie over het inschakelen van streaming.
Notitie
Zie uitspraakbeoordeling voor meer informatie.
Voorbeeldaanvraag
Het volgende voorbeeld bevat de hostnaam en de vereiste headers. Het is belangrijk om te weten dat de service ook audiogegevens verwacht, die niet zijn opgenomen in dit voorbeeld. Zoals eerder vermeld, wordt segmentering aanbevolen, maar niet vereist.
POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue
Als u uitspraakbeoordeling wilt inschakelen, kunt u de volgende header toevoegen. Zie De beoordelingsparameters van de uitspraak voor meer informatie over het bouwen van deze header.
Pronunciation-Assessment: eyJSZWZlcm...
HTTP-statuscode
De HTTP-statuscode voor elk antwoord duidt op geslaagde of veelvoorkomende fouten.
| HTTP-statuscode | Beschrijving | Mogelijke redenen |
|---|---|---|
| 100 | Verdergaan | De eerste aanvraag wordt geaccepteerd. Ga verder met het verzenden van de rest van de gegevens. (Deze code wordt gebruikt met gesegmenteerde overdracht.) |
| 200 | OK | De aanvraag is geslaagd. De hoofdtekst van het antwoord is een JSON-object. |
| 400 | Ongeldige aanvraag | De taalcode is niet opgegeven, de taal wordt niet ondersteund of het audiobestand is ongeldig (bijvoorbeeld). |
| 401 | Niet geautoriseerd | Een resourcesleutel of een autorisatietoken is ongeldig in de opgegeven regio of een eindpunt is ongeldig. |
| 403 | Verboden | Er ontbreekt een resourcesleutel of autorisatietoken. |
Voorbeeldantwoorden
Hier volgt een typisch antwoord voor simple herkenning:
{
"RecognitionStatus": "Success",
"DisplayText": "Remind me to buy 5 pencils.",
"Offset": "1236645672289",
"Duration": "1236645672289"
}
Hier volgt een typisch antwoord voor detailed herkenning:
{
"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"
},
{
"Confidence": 0.92459863,
"Display": "what is the weather like",
"ITN": "what is the weather like",
"Lexical": "what is the weather like",
"MaskedITN": "what is the weather like"
}
]
}
Hier volgt een typisch antwoord voor herkenning met uitspraakbeoordeling:
{
"RecognitionStatus": "Success",
"Offset": "400000",
"Duration": "11000000",
"NBest": [
{
"Confidence" : "0.87",
"Lexical" : "good morning",
"ITN" : "good morning",
"MaskedITN" : "good morning",
"Display" : "Good morning.",
"PronScore" : 84.4,
"AccuracyScore" : 100.0,
"FluencyScore" : 74.0,
"CompletenessScore" : 100.0,
"Words": [
{
"Word" : "Good",
"AccuracyScore" : 100.0,
"ErrorType" : "None",
"Offset" : 500000,
"Duration" : 2700000
},
{
"Word" : "morning",
"AccuracyScore" : 100.0,
"ErrorType" : "None",
"Offset" : 5300000,
"Duration" : 900000
}
]
}
]
}
Responseigenschappen
Resultaten worden geleverd als JSON. De simple indeling bevat de volgende velden op het hoogste niveau:
| Eigenschappen | Beschrijving |
|---|---|
RecognitionStatus |
Status, zoals Success voor geslaagde herkenning. Zie de volgende tabel. |
DisplayText |
De herkende tekst na hoofdlettergebruik, interpunctie, inverse tekstnormalisatie en maskering van grof taalgebruik. Presenteer alleen op succes. Inverse tekstnormalisatie is conversie van gesproken tekst naar kortere vormen, zoals 200 voor 'tweehonderd' of 'Dr. Smith' voor 'dokter smith'. |
Offset |
De tijd (in 100 nanoseconden) waarop de herkende spraak begint in de audiostream. |
Duration |
De duur (in 100 nanoseconden) van de herkende spraak in de audiostream. |
Het RecognitionStatus veld kan deze waarden bevatten:
| -Status | Beschrijving |
|---|---|
Success |
De herkenning is geslaagd en het DisplayText veld is aanwezig. |
NoMatch |
Spraak is gedetecteerd in de audiostream, maar er zijn geen woorden uit de doeltaal gevonden. Deze status betekent meestal dat de herkenningstaal verschilt van de taal die de gebruiker spreekt. |
InitialSilenceTimeout |
Het begin van de audiostream bevatte alleen stilte en de service heeft een time-out opgetreden tijdens het wachten op spraak. |
BabbleTimeout |
Het begin van de audiostream bevatte alleen ruis en de service heeft een time-out opgetreden tijdens het wachten op spraak. |
Error |
Er is een interne fout opgetreden in de herkenningsservice en kan niet worden voortgezet. Probeer het indien mogelijk opnieuw. |
Notitie
Als de audio alleen uit grof taalgebruik bestaat en de profanity queryparameter is ingesteld removeop, retourneert de service geen spraakresultaat.
De detailed indeling bevat meer vormen van herkende resultaten.
Wanneer u de detailed indeling gebruikt, DisplayText wordt deze opgegeven zoals Display voor elk resultaat in de NBest lijst.
Het object in de NBest lijst kan het volgende bevatten:
| Eigenschappen | Beschrijving |
|---|---|
Confidence |
De betrouwbaarheidsscore van de vermelding, van 0,0 (geen betrouwbaarheid) tot 1,0 (volledig vertrouwen). |
Lexical |
De lexicale vorm van de herkende tekst: de werkelijke woorden die worden herkend. |
ITN |
De inverse-tekst-genormaliseerde (ITN) of canonieke vorm van de herkende tekst, met telefoonnummers, nummers, afkortingen (dokter smith tot dr smith) en andere toegepaste transformaties. |
MaskedITN |
Het ITN-formulier waarop grof taalmaskering is toegepast, indien aangevraagd. |
Display |
De weergavevorm van de herkende tekst, met interpunctie en hoofdlettergebruik toegevoegd. Deze parameter is hetzelfde als wat DisplayText u opgeeft wanneer de notatie is ingesteld op simple. |
AccuracyScore |
Uitspraaknauwkeurigheid van de spraak. Nauwkeurigheid geeft aan hoe dicht de telefoontjes overeenkomen met de uitspraak van een systeemeigen spreker. De nauwkeurigheidsscore op het woord- en volledige-tekstniveau wordt geaggregeerd op basis van de nauwkeurigheidsscore op het niveau van het foneme. |
FluencyScore |
Vloeiendheid van de opgegeven spraak. Fluency geeft aan hoe nauw de spraak overeenkomt met het gebruik van stille pauzes tussen woorden. |
CompletenessScore |
Volledigheid van de spraak, bepaald door de verhouding van uitgesproken woorden te berekenen om te verwijzen naar tekstinvoer. |
PronScore |
Algemene score die de uitspraakkwaliteit van de geleverde spraak aangeeft. Deze score wordt geaggregeerd van AccuracyScore, FluencyScoreen CompletenessScore met gewicht. |
ErrorType |
Waarde die aangeeft of een woord wordt weggelaten, ingevoegd of slecht uitgesproken, vergeleken met ReferenceText. Mogelijke waarden zijn None (wat betekent geen fout op dit woord), Omission, en MispronunciationInsertion. |
Gesegmenteerde overdracht
Gesegmenteerde overdracht (Transfer-Encoding: chunked) kan helpen bij het verminderen van de herkenningslatentie. Hiermee kan de Speech-service beginnen met het verwerken van het audiobestand terwijl het wordt verzonden. De REST API voor korte audio biedt geen gedeeltelijke of tussentijdse resultaten.
In het volgende codevoorbeeld ziet u hoe u audio in segmenten verzendt. Alleen het eerste segment moet de koptekst van het audiobestand bevatten. request is een HttpWebRequest object dat is verbonden met het juiste REST-eindpunt. audioFile is het pad naar een audiobestand op schijf.
var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;
using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
// Open a request stream and write 1,024-byte chunks in the stream one at a time.
byte[] buffer = null;
int bytesRead = 0;
using (var requestStream = request.GetRequestStream())
{
// Read 1,024 raw bytes from the input audio file.
buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
{
requestStream.Write(buffer, 0, bytesRead);
}
requestStream.Flush();
}
}
Verificatie
Voor elke aanvraag is een autorisatieheader vereist. In deze tabel ziet u welke headers worden ondersteund voor elke functie:
| Ondersteunde autorisatieheader | Spraak-naar-tekst | Tekst naar spraak |
|---|---|---|
Ocp-Apim-Subscription-Key |
Ja | Ja |
Authorization: Bearer |
Ja | Ja |
Wanneer u de Ocp-Apim-Subscription-Key header gebruikt, hoeft u alleen uw resourcesleutel op te geven. Voorbeeld:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Wanneer u de Authorization: Bearer header gebruikt, moet u een aanvraag indienen bij het issueToken eindpunt. In deze aanvraag wisselt u uw resourcesleutel uit voor een toegangstoken dat tien minuten geldig is.
Een toegangstoken ophalen
Als u een toegangstoken wilt ophalen, moet u een aanvraag indienen bij het issueToken eindpunt met behulp van Ocp-Apim-Subscription-Key en uw resourcesleutel.
Het issueToken eindpunt heeft deze indeling:
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Vervang <REGION_IDENTIFIER> door de id die overeenkomt met de regio van uw abonnement.
Gebruik de volgende voorbeelden om uw toegangstokenaanvraag te maken.
HTTP-voorbeeld
Dit voorbeeld is een eenvoudige HTTP-aanvraag om een token op te halen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Als uw abonnement zich niet in de regio VS - west bevindt, vervangt u de header door de Host hostnaam van uw regio.
POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0
De hoofdtekst van het antwoord bevat het toegangstoken in de JSON Web Token-indeling (JWT).
Voorbeeld van PowerShell
Dit voorbeeld is een eenvoudig PowerShell-script om een toegangstoken op te halen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Zorg ervoor dat u het juiste eindpunt gebruikt voor de regio die overeenkomt met uw abonnement. Dit voorbeeld is momenteel ingesteld op VS - west.
$FetchTokenHeader = @{
'Content-type'='application/x-www-form-urlencoded';
'Content-Length'= '0';
'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}
$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
-Headers $FetchTokenHeader
# show the token received
$OAuthToken
cURL-voorbeeld
cURL is een opdrachtregelprogramma dat beschikbaar is in Linux (en in de Windows-subsysteem voor Linux). Deze cURL-opdracht illustreert hoe u een toegangstoken kunt ophalen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Zorg ervoor dat u het juiste eindpunt gebruikt voor de regio die overeenkomt met uw abonnement. Dit voorbeeld is momenteel ingesteld op VS - west.
curl -v -X POST \
"https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-Length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"
C#-voorbeeld
Deze C#-klasse laat zien hoe u een toegangstoken kunt verkrijgen. Geef uw resourcesleutel door voor de Speech-service wanneer u de klasse instantiëren. Als uw abonnement zich niet in de regio VS - west bevindt, wijzigt u de waarde zodat FetchTokenUri deze overeenkomt met de regio voor uw abonnement.
public class Authentication
{
public static readonly string FetchTokenUri =
"https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
private string subscriptionKey;
private string token;
public Authentication(string subscriptionKey)
{
this.subscriptionKey = subscriptionKey;
this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
}
public string GetAccessToken()
{
return this.token;
}
private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
{
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
UriBuilder uriBuilder = new UriBuilder(fetchUri);
var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
return await result.Content.ReadAsStringAsync();
}
}
}
Python-voorbeeld
# Request module must be installed.
# Run pip install requests if necessary.
import requests
subscription_key = 'REPLACE_WITH_YOUR_KEY'
def get_token(subscription_key):
fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
headers = {
'Ocp-Apim-Subscription-Key': subscription_key
}
response = requests.post(fetch_token_url, headers=headers)
access_token = str(response.text)
print(access_token)
Een toegangstoken gebruiken
Het toegangstoken moet als header Authorization: Bearer <TOKEN> naar de service worden verzonden. Elk toegangstoken is 10 minuten geldig. U kunt op elk gewenst moment een nieuw token krijgen, maar om netwerkverkeer en latentie te minimaliseren, raden we u aan om hetzelfde token negen minuten te gebruiken.
Hier volgt een voorbeeld van een HTTP-aanvraag voor de REST API voor spraak naar tekst voor korte audio:
POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive
// Message body here...