API REST di sintesi vocale
Il servizio Voce consente di convertire il testo in sintesi vocale e ottenere un elenco di voci supportate per un'area usando un'API REST. In questo articolo vengono fornite informazioni sulle opzioni di autorizzazione, sulle opzioni di query, su come strutturare una richiesta e su come interpretare una risposta.
Suggerimento
I casi d'uso per l'API REST sintesi vocale sono limitati. Usarlo solo nei casi in cui non è possibile usare Speech SDK. Ad esempio, con Speech SDK è possibile sottoscrivere eventi per altre informazioni dettagliate sull'elaborazione vocale e sui risultati.
L'API REST sintesi vocale supporta il testo neurale per le voci vocali in molte impostazioni locali. Ogni endpoint disponibile è associato a un'area. È necessaria una chiave di risorsa voce per l'endpoint o l'area che si prevede di usare. Di seguito sono riportati i collegamenti ad altre informazioni:
- Per un elenco completo delle voci, vedere Lingua e supporto vocale per il servizio Voce.
- Per informazioni sulla disponibilità a livello di area, vedere Aree supportate dal servizio Voce.
- Per Azure per enti pubblici e Microsoft Azure gestito da 21 EndpointVianet, vedere questo articolo sui cloud sovrani.
Importante
I costi variano per le voci neurali predefinite (denominate Neural nella pagina dei prezzi) e per le voci neurali personalizzate (denominate Neurale personalizzato nella pagina dei prezzi). Per altre informazioni, vedere Prezzi del servizio Voce.
Prima di usare l'API REST sintesi vocale, è necessario completare uno scambio di token come parte dell'autenticazione per accedere al servizio. Per altre informazioni, vedere Autenticazione.
Ottenere un elenco di voci
È possibile usare l'endpoint tts.speech.microsoft.com/cognitiveservices/voices/list per ottenere un elenco completo di voci per un'area o un endpoint specifico. Aggiungere un prefisso all'endpoint dell'elenco voci con un'area per ottenere un elenco di voci per tale area. Ad esempio, per ottenere un elenco di voci per l'area westus , usare l'endpoint https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list . Per un elenco di tutte le aree supportate, vedere la documentazione sulle aree .
Nota
Le voci e gli stili in anteprima sono disponibili solo in tre aree di servizio: Stati Uniti orientali, Europa occidentale e Asia sud-orientale.
Intestazioni delle richieste
Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di sintesi vocale:
| Intestazione | Descrizione | Obbligatorio o facoltativo |
|---|---|---|
Ocp-Apim-Subscription-Key |
La chiave della risorsa Voce. | È necessaria questa intestazione o Authorization. |
Authorization |
Un token di autorizzazione preceduto dalla parola Bearer. Per altre informazioni, vedere Autenticazione. |
È necessaria questa intestazione o Ocp-Apim-Subscription-Key. |
Testo della richiesta
Un corpo non è necessario per GET le richieste a questo endpoint.
Esempio di richiesta
Questa richiesta richiede solo un'intestazione di autorizzazione:
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Ecco un comando curl di esempio:
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Risposta di esempio
Si dovrebbe ricevere una risposta con un corpo JSON che include tutte le impostazioni locali, le voci, il sesso, gli stili e altri dettagli supportati. La WordsPerMinute proprietà per ogni voce può essere usata per stimare la lunghezza della voce di output. Questo esempio JSON mostra risultati parziali per illustrare la struttura di una risposta:
[
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
"DisplayName": "Jenny",
"LocalName": "Jenny",
"ShortName": "en-US-JennyNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"StyleList": [
"assistant",
"chat",
"customerservice",
"newscast",
"angry",
"cheerful",
"sad",
"excited",
"friendly",
"terrified",
"shouting",
"unfriendly",
"whispering",
"hopeful"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"ExtendedPropertyMap": {
"IsHighQuality48K": "True"
},
"WordsPerMinute": "152"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
"DisplayName": "Jenny Multilingual",
"LocalName": "Jenny Multilingual",
"ShortName": "en-US-JennyMultilingualNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"SecondaryLocaleList": [
"de-DE",
"en-AU",
"en-CA",
"en-GB",
"es-ES",
"es-MX",
"fr-CA",
"fr-FR",
"it-IT",
"ja-JP",
"ko-KR",
"pt-BR",
"zh-CN"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "190"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
"DisplayName": "Orla",
"LocalName": "Orla",
"ShortName": "ga-IE-OrlaNeural",
"Gender": "Female",
"Locale": "ga-IE",
"LocaleName": "Irish (Ireland)",
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "139"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
"DisplayName": "Yunxi",
"LocalName": "云希",
"ShortName": "zh-CN-YunxiNeural",
"Gender": "Male",
"Locale": "zh-CN",
"LocaleName": "Chinese (Mandarin, Simplified)",
"StyleList": [
"narration-relaxed",
"embarrassed",
"fearful",
"cheerful",
"disgruntled",
"serious",
"angry",
"sad",
"depressed",
"chat",
"assistant",
"newscast"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"RolePlayList": [
"Narrator",
"YoungAdultMale",
"Boy"
],
"WordsPerMinute": "293"
},
// Redacted for brevity
]
Codici di stato HTTP
Il codice di stato HTTP di ogni risposta indica esito positivo o errori comuni.
| Codice di stato HTTP | Descrizione | Possibile motivo |
|---|---|---|
| 200 | OK | La richiesta è stata completata. |
| 400 | Richiesta non valida | Un parametro obbligatorio è mancante, vuoto o Null. In alternativa, il valore passato a un parametro obbligatorio o facoltativo non è valido. Un motivo comune è un'intestazione troppo lunga. |
| 401 | Non autorizzata | La richiesta non è autorizzata. Assicurarsi che la chiave o il token della risorsa sia valido e nell'area corretta. |
| 429 | Numero eccessivo di richieste | È stata superata la quota o la frequenza di richieste consentite per la risorsa. |
| 502 | Gateway non valido | Si è verificato un problema di rete o lato server. Questo stato potrebbe anche indicare intestazioni non valide. |
Sintesi vocale
L'endpoint cognitiveservices/v1 consente di convertire il testo in voce usando Speech Synthesis Markup Language (SSML).
Aree ed endpoint
Queste aree sono supportate per la sintesi vocale tramite l'API REST. Assicurarsi di selezionare l'endpoint corrispondente all'area della risorsa Voce.
Voci neurali predefinite
Usare questa tabella per determinare la disponibilità delle voci neurali in base all'area o all'endpoint:
| Paese | Endpoint |
|---|---|
| Australia orientale | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Brasile meridionale | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Canada centrale | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti centrali | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asia orientale | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti orientali | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti orientali 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Francia centrale | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Germania centro-occidentale | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| India centrale | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Giappone orientale | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Giappone occidentale | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| India occidentale Jio | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Corea centrale | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti centro-settentrionali | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europa settentrionale | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norvegia orientale | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti centro-meridionali | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asia sud-orientale | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Svezia centrale | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Svizzera settentrionale | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Svizzera occidentale | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Emirati Arabi Uniti settentrionali | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Gov Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| US Gov Virginia | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| Regno Unito meridionale | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti centro-occidentali | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europa occidentale | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti occidentali | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| West US 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Stati Uniti occidentali 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Suggerimento
Le voci in anteprima sono disponibili solo in queste tre aree: Stati Uniti orientali, Europa occidentale e Asia sud-orientale.
Voci neurali personalizzate
Se è stato creato un tipo di carattere vocale neurale personalizzato, usare l'endpoint creato. È anche possibile usare gli endpoint seguenti. Sostituire {deploymentId} con l'ID di distribuzione per il modello vocale neurale.
| Paese | Formazione | Distribuzione | Endpoint |
|---|---|---|---|
| Australia orientale | Sì | Sì | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Brasile meridionale | No | Sì | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Canada centrale | No | Sì | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti centrali | No | Sì | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asia orientale | No | Sì | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti orientali | Sì | Sì | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti orientali 2 | Sì | Sì | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Francia centrale | No | Sì | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Germania centro-occidentale | No | Sì | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| India centrale | Sì | Sì | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Giappone orientale | Sì | Sì | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Giappone occidentale | No | Sì | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| India occidentale Jio | No | Sì | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Corea centrale | Sì | Sì | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti centro-settentrionali | No | Sì | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europa settentrionale | Sì | Sì | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norvegia orientale | No | Sì | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sudafrica settentrionale | No | Sì | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti centro-meridionali | Sì | Sì | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asia sud-orientale | Sì | Sì | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Svizzera settentrionale | No | Sì | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Svizzera occidentale | No | Sì | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Emirati Arabi Uniti settentrionali | No | Sì | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Regno Unito meridionale | Sì | Sì | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti centro-occidentali | No | Sì | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europa occidentale | Sì | Sì | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti occidentali | Sì | Sì | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| West US 2 | Sì | Sì | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Stati Uniti occidentali 3 | No | Sì | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Nota
Le aree precedenti sono disponibili per l'hosting del modello vocale neurale e la sintesi in tempo reale. Il training vocale neurale personalizzato è disponibile solo in alcune aree. Gli utenti possono tuttavia copiare facilmente un modello vocale neurale da queste aree in altre aree nell'elenco precedente.
API Audio lungo
L'API Audio lungo è disponibile in più aree con endpoint univoci:
| Paese | Endpoint |
|---|---|
| Australia orientale | https://australiaeast.customvoice.api.speech.microsoft.com |
| Stati Uniti orientali | https://eastus.customvoice.api.speech.microsoft.com |
| India centrale | https://centralindia.customvoice.api.speech.microsoft.com |
| Stati Uniti centro-meridionali | https://southcentralus.customvoice.api.speech.microsoft.com |
| Asia sud-orientale | https://southeastasia.customvoice.api.speech.microsoft.com |
| Regno Unito meridionale | https://uksouth.customvoice.api.speech.microsoft.com |
| Europa occidentale | https://westeurope.customvoice.api.speech.microsoft.com |
Intestazioni delle richieste
Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di sintesi vocale:
| Intestazione | Descrizione | Obbligatorio o facoltativo |
|---|---|---|
Authorization |
Un token di autorizzazione preceduto dalla parola Bearer. Per altre informazioni, vedere Autenticazione. |
Richiesto |
Content-Type |
Specifica il tipo di contenuto per il testo specificato. Valore accettato: application/ssml+xml. |
Richiesto |
X-Microsoft-OutputFormat |
Specifica il formato di output audio. Per un elenco completo dei valori accettati, vedi Output audio. | Richiesto |
User-Agent |
Il nome dell'applicazione. Il valore specificato deve essere inferiore a 255 caratteri. | Richiesto |
Testo della richiesta
Se si usa una voce neurale personalizzata, il corpo di una richiesta può essere inviato come testo normale (ASCII o UTF-8). In caso contrario, il corpo di ogni POST richiesta viene inviato come SSML. SSML consente di scegliere la voce e la lingua del parlato sintetizzato restituito dalla funzionalità di sintesi vocale. Per un elenco completo delle voci supportate, vedere Lingua e supporto vocale per il servizio Voce.
Esempio di richiesta
Questa richiesta HTTP utilizza SSML per specificare la lingua e la voce. Se la lunghezza del corpo è lunga e l'audio risultante supera 10 minuti, viene troncato a 10 minuti. In altre parole, la lunghezza audio non può superare i 10 minuti.
POST /cognitiveservices/v1 HTTP/1.1
X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>
<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
name='en-US-ChristopherNeural'>
I'm excited to try text to speech!
</voice></speak>
* Per Content-Length, è consigliabile usare la lunghezza del contenuto personalizzata. Nella maggior parte dei casi, questo valore viene calcolato automaticamente.
Codici di stato HTTP
Il codice di stato HTTP per ogni risposta indica l'esito positivo o gli errori comuni:
| Codice di stato HTTP | Descrizione | Possibile motivo |
|---|---|---|
| 200 | OK | La richiesta è stata completata. Il corpo della risposta è un file audio. |
| 400 | Richiesta non valida | Un parametro obbligatorio è mancante, vuoto o Null. In alternativa, il valore passato a un parametro obbligatorio o facoltativo non è valido. Un motivo comune è un'intestazione troppo lunga. |
| 401 | Non autorizzata | La richiesta non è autorizzata. Assicurarsi che la chiave o il token della risorsa Voce sia valido e nell'area corretta. |
| 415 | Tipo di supporto non supportato | È possibile che sia stato fornito il valore errato Content-Type . Content-Type deve essere impostato su application/ssml+xml. |
| 429 | Numero eccessivo di richieste | È stata superata la quota o la frequenza di richieste consentite per la risorsa. |
| 502 | Gateway non valido | Si è verificato un problema di rete o lato server. Questo stato potrebbe anche indicare intestazioni non valide. |
Se lo stato HTTP è 200 OK, il corpo della risposta contiene un file audio nel formato richiesto. Questo file può essere riprodotto, poiché è trasferito, salvato in un buffer o salvato in un file.
Output audio
I formati audio di streaming e non di streaming supportati vengono inviati in ogni richiesta come X-Microsoft-OutputFormat intestazione. Ogni formato incorpora una velocità di bit e un tipo di codifica. Il servizio Voce supporta output audio a 48 kHz, 24 kHz, 16 kHz e 8 kHz. Ogni modello di voce neurale predefinita è disponibile a 24 kHz e ad alta fedeltà a 48 kHz.
amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus
Nota
Se si seleziona il formato di output a 48 kHz, il modello vocale ad alta fedeltà con 48 kHz verrà richiamato di conseguenza. Le frequenze di campionamento diverse da 24kHz e 48kHz possono essere ottenute tramite l'upsampling o il downcampionamento durante la sintesi, ad esempio, 44,1 kHz viene ridotto da 48 kHz.
Se la voce selezionata e il formato di output hanno velocità in bit diverse, il campionamento audio viene ripetuto secondo necessità. È possibile decodificare il ogg-24khz-16bit-mono-opus formato usando il codec Opus.
Autenticazione
Ogni richiesta richiede un'intestazione di autorizzazione. Questa tabella illustra le intestazioni supportate per ogni funzionalità:
| Intestazione di autorizzazione supportata | Riconoscimento vocale | Sintesi vocale |
|---|---|---|
Ocp-Apim-Subscription-Key |
Sì | Sì |
Authorization: Bearer |
Sì | Sì |
Quando si usa l'intestazione Ocp-Apim-Subscription-Key , è necessario specificare solo la chiave di risorsa. Ad esempio:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Quando si usa l'intestazione Authorization: Bearer , è necessario effettuare una richiesta all'endpoint issueToken . In questa richiesta si scambia la chiave della risorsa per un token di accesso valido per 10 minuti.
Un'altra opzione consiste nell'usare l'autenticazione di Microsoft Entra che usa anche l'intestazione Authorization: Bearer , ma con un token rilasciato tramite Microsoft Entra ID. Vedere Usare l'autenticazione di Microsoft Entra.
Come ottenere un token di accesso
Per ottenere un token di accesso, è necessario effettuare una richiesta all'endpoint issueToken usando Ocp-Apim-Subscription-Key e la chiave della risorsa.
L'endpoint issueToken ha questo formato:
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Sostituire <REGION_IDENTIFIER> con l'identificatore corrispondente all'area della sottoscrizione.
Usare gli esempi seguenti per creare la richiesta di token di accesso.
Esempio di HTTP
Questo esempio è una semplice richiesta HTTP per ottenere un token. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Se la sottoscrizione non si trova nell'area Stati Uniti occidentali, sostituire l'intestazione Host con il nome host della propria area.
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
Il corpo della risposta contiene il token di accesso in formato JWT (JSON Web Token).
Esempio PowerShell
Questo esempio è un semplice script di PowerShell per ottenere un token di accesso. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Assicurarsi di usare l'endpoint corretto per l'area che corrisponde alla sottoscrizione. Questo esempio è attualmente impostato sugli Stati Uniti occidentali.
$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
esempio di cURL
cURL è uno strumento da riga di comando disponibile in Linux (e nel sottosistema Windows per Linux). Il comando cURL illustra come ottenere un token di accesso. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Assicurarsi di usare l'endpoint corretto per l'area che corrisponde alla sottoscrizione. Questo esempio è attualmente impostato sugli Stati Uniti occidentali.
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"
Esempio in C#
La classe C# illustra come ottenere un token di accesso. Passare la chiave di risorsa per il servizio Voce quando si crea un'istanza della classe . Se la sottoscrizione non è nell'area Stati Uniti occidentali, modificare il valore di FetchTokenUri in modo che corrisponda all'area della sottoscrizione.
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();
}
}
}
Esempio in Python
# 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)
Come usare un token di accesso
Il token di accesso deve essere inviato al servizio come intestazione Authorization: Bearer <TOKEN>. Ogni token di accesso è valido per 10 minuti. È possibile ottenere un nuovo token in qualsiasi momento, ma per ridurre al minimo il traffico di rete e la latenza, è consigliabile usare lo stesso token per nove minuti.
Ecco una richiesta HTTP di esempio all'API REST Riconoscimento vocale per brevi 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...
Utilizzare Autenticazione Microsoft Entra
Per usare l'autenticazione di Microsoft Entra con l'API REST Riconoscimento vocale per brevi audio, è necessario creare un token di accesso. I passaggi per ottenere il token di accesso costituito da ID risorsa e token di accesso Microsoft Entra sono uguali a quando si usa Speech SDK. Seguire la procedura descritta qui Usare l'autenticazione di Microsoft Entra
- Creare una risorsa Voce
- Configurare la risorsa Voce per l'autenticazione di Microsoft Entra
- Ottenere un token di accesso di Microsoft Entra
- Ottenere l'ID della risorsa Voce
Dopo aver ottenuto l'ID risorsa e il token di accesso Microsoft Entra, il token di accesso effettivo può essere costruito seguendo questo formato:
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
È necessario includere il prefisso "aad#" e il separatore "#" (hash) tra l'ID risorsa e il token di accesso.
Ecco una richiesta HTTP di esempio all'API REST Riconoscimento vocale per brevi 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...
Per altre informazioni sui token di accesso di Microsoft Entra, inclusa la durata dei token, vedere Token di accesso in Microsoft Identity Platform.