Condividi tramite


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:

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 https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Brasile meridionale No https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Canada centrale No https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti centrali No https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Asia orientale No https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti orientali https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti orientali 2 https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Francia centrale No https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Germania centro-occidentale No https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
India centrale https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Giappone orientale https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Giappone occidentale No https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
India occidentale Jio No https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Corea centrale https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti centro-settentrionali No https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Europa settentrionale https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Norvegia orientale No https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Sudafrica settentrionale No https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti centro-meridionali https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Asia sud-orientale https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Svizzera settentrionale No https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Svizzera occidentale No https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Emirati Arabi Uniti settentrionali No https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Regno Unito meridionale https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti centro-occidentali No https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Europa occidentale https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti occidentali https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
West US 2 https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Stati Uniti occidentali 3 No 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
Authorization: Bearer

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.

Passaggi successivi