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.

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.

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 .

Intestazioni delle richieste

Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di sintesi vocale:

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.

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:

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.

API Audio lungo

L'API Audio lungo è disponibile in più aree con endpoint univoci:

Intestazioni delle richieste

Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di sintesi vocale:

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:

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

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

Autenticazione

Ogni richiesta richiede un'intestazione di autorizzazione. Questa tabella illustra le intestazioni supportate per ogni funzionalità:

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

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

• Creare un account Azure gratuito
• Introduzione a Sintesi vocale neurale
• Sintesi batch