Condividi tramite

Proprietà di sintesi batch per il riconoscimento vocale

  • Articolo

Importante

L'API di sintesi batch è disponibile a livello generale. L'API Audio lungo verrà ritirata il 1° aprile 2027. Per altre informazioni, vedere Eseguire la migrazione all'API di sintesi batch.

L'API di sintesi batch può sintetizzare in modo asincrono un volume elevato di input di testo (long e short). Gli editori e le piattaforme di contenuti audio possono creare contenuti audio lunghi in un batch. Ad esempio: libri audio, articoli di notizie e documenti. L'API di sintesi batch può creare audio sintetizzato di lunghezza superiore a 10 minuti.

Quando si crea un nuovo processo di sintesi batch, sono necessarie alcune proprietà in formato JSON. Le altre proprietà sono facoltative. La risposta di sintesi batch include altre proprietà volte a fornire informazioni sullo stato e sui risultati della sintesi. Ad esempio, la outputs.result proprietà contiene il percorso dei file dei risultati di sintesi batch con output audio e log.

Proprietà della sintesi batch

Nella tabella seguente sono descritte le proprietà della sintesi batch.

Proprietà Descrizione
createdDateTime Data e ora di creazione del processo di sintesi batch.

Questa proprietà è di sola lettura.
customVoices Mappa di un nome di voce personalizzata e del relativo ID di distribuzione.

Ad esempio: "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}

È possibile usare il nome della voce in synthesisConfig.voice (quando la proprietà inputKind è impostata su "PlainText") o all'interno del testo SSML di inputs (quando inputKind è impostata su "SSML").

Questa proprietà è necessaria per usare una voce personalizzata. Se si cerca di usare una voce personalizzata non definita qui, il servizio restituisce un errore.
description Descrizione della sintesi batch.

Questa proprietà è facoltativa.
id ID processo di sintesi batch passato nel percorso.

Questa proprietà è obbligatoria nel percorso.
inputs Testo normale o SSML da sintetizzare.

Quando la proprietà inputKind è impostata su "PlainText", specificare testo normale, come illustrato qui: "inputs": [{"text": "The rainbow has seven colors."}]. Quando invece inputKind è impostata su "SSML", specificare testo in linguaggio SSML (Speech Synthesis Markup Language), come illustrato qui: "inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}].

Se si desiderano più file di output audio, includere al massimo 1000 oggetti di testo. Di seguito è riportato un esempio di testo di input da sintetizzare in due file di output audio: "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]. Tuttavia, se la properties.concatenateResult proprietà è impostata su true, ogni risultato sintetizzato viene scritto nello stesso file di output audio.

Non sono necessari input di testo separati per i nuovi paragrafi. All'interno di uno degli input di testo (fino a 1000) è possibile specificare nuovi paragrafi usando la stringa "\r\n" (nuova riga). Ecco un esempio di testo di input con due paragrafi da sintetizzare nello stesso file di output audio: "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]

Non sono previsti limiti di paragrafo, ma la dimensione massima del payload JSON (inclusi tutti gli input di testo e altre proprietà) è di 2 megabyte.

Questa proprietà è obbligatoria quando si crea un nuovo processo di sintesi batch. Questa proprietà non è inclusa nella risposta quando si ottiene il processo di sintesi.
internalId ID processo di sintesi batch interno.

Questa proprietà è di sola lettura.
lastActionDateTime Data e ora più recenti in cui è stato modificato il valore della proprietà status.

Questa proprietà è di sola lettura.
outputs.result Percorso dei file dei risultati della sintesi batch con output audio e log.

Questa proprietà è di sola lettura.
properties Set definito di impostazioni di configurazione facoltative per la sintesi batch.
properties.sizeInBytes Dimensione dell'output audio in byte.

Questa proprietà è di sola lettura.
properties.billingDetails Numero di parole elaborate e fatturate per voci customNeuralCharacters rispetto a voci neuralCharacters (predefinite).

Questa proprietà è di sola lettura.
properties.concatenateResult Determina se concatenare il risultato. Questo valore bool facoltativo ("true" o "false") è "false" per impostazione predefinita.
properties.decompressOutputFiles Determina se decomprimere i file dei risultati della sintesi nel contenitore di destinazione. Questa proprietà può essere impostata solo quando la destinationContainerUrl proprietà è impostata. Questo valore bool facoltativo ("true" o "false") è "false" per impostazione predefinita.
properties.destinationContainerUrl I risultati della sintesi batch possono essere archiviati in un contenitore di Azure scrivibile. Se non si specifica un URI del contenitore con token di firma di accesso condiviso (SAS), il servizio Voce archivia i risultati in un contenitore gestito da Microsoft. La firma di accesso condiviso con criteri di accesso archiviati non è supportata. Durante l'eliminazione del processo di sintesi vengono eliminati anche i dati dei risultati.

Quando si ottiene il processo di sintesi, questa proprietà facoltativa non è inclusa nella risposta.
properties.destinationPath Percorso del prefisso in cui è possibile archiviare i risultati della sintesi batch. Se non si specifica un percorso di prefisso, il percorso del prefisso predefinito è YourSpeechResourceId/YourSynthesisId.

Questa proprietà facoltativa può essere impostata solo quando la destinationContainerUrl proprietà è impostata.
properties.durationInMilliseconds Durata dell'output audio in millisecondi.

Questa proprietà è di sola lettura.
properties.failedAudioCount Conteggio degli input di sintesi batch nell'output audio non riuscito.

Questa proprietà è di sola lettura.
properties.outputFormat Formato dell'output audio.

Per informazioni sui valori accettati, vedere i formati di output audio. Il formato di output predefinito è riff-24khz-16bit-mono-pcm.
properties.sentenceBoundaryEnabled Determina se generare dati sui limiti di frase. Questo valore bool facoltativo ("true" o "false") è "false" per impostazione predefinita.

Se vengono richiesti dati limite frase, un file corrispondente [nnnn].sentence.json viene incluso nel file ZIP dei dati dei risultati.
properties.succeededAudioCount Conteggio degli input di sintesi batch nell'output audio completato.

Questa proprietà è di sola lettura.
properties.timeToLiveInHours Durata in ore dopo la creazione del processo di sintesi, quando i risultati della sintesi verranno eliminati automaticamente. Questa impostazione facoltativa è 744 (31 giorni) per impostazione predefinita. La durata massima è di 31 giorni. La data e l'ora dell'eliminazione automatica (per i processi di sintesi con stato "Succeeded" o "Failed") è uguale alle proprietà lastActionDateTime + timeToLiveInHours.

In alternativa, è possibile chiamare il metodo delete della sintesi per rimuovere il processo in anticipo.
properties.wordBoundaryEnabled Determina se generare dati sui limiti di parola. Questo valore bool facoltativo ("true" o "false") è "false" per impostazione predefinita.

Se vengono richiesti dati limite di parola, un file corrispondente [nnnn].word.json viene incluso nel file ZIP dei dati dei risultati.
status Stato di elaborazione della sintesi batch.

Lo stato deve passare da "NotStarted" a "Running" e infine a "Succeeded" o "Failed".

Questa proprietà è di sola lettura.
synthesisConfig Impostazioni di configurazione da usare per la sintesi batch di testo normale.

Questa proprietà è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.backgroundAudio Audio in background per ogni output audio.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.backgroundAudio.fadein Durata della dissolvenza in entrata dell'audio di sottofondo in millisecondi. Il valore predefinito è 0, che equivale a nessuna dissolvenza in entrata. Valori accettati: da 0 a 10000 inclusi.

Per informazioni, vedere la tabella degli attributi in Aggiungere audio in background nella documentazione di Speech Synthesis Markup Language (SSML). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.backgroundAudio.fadeout Durata della dissolvenza in uscita dell'audio di sottofondo in millisecondi. Il valore predefinito è 0, che equivale a nessuna dissolvenza in uscita. Valori accettati: da 0 a 10000 inclusi.

Per informazioni, vedere la tabella degli attributi in Aggiungere audio in background nella documentazione di Speech Synthesis Markup Language (SSML). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.backgroundAudio.src Percorso URI del file audio di sottofondo.

Per informazioni, vedere la tabella degli attributi in Aggiungere audio in background nella documentazione di Speech Synthesis Markup Language (SSML). I valori non validi vengono ignorati.

Questa proprietà è obbligatoria quando synthesisConfig.backgroundAudio è impostata.
synthesisConfig.backgroundAudio.volume Volume del file audio di sottofondo. Valori accettati: da 0 a 100 inclusi. Il valore predefinito è 1.

Per informazioni, vedere la tabella degli attributi in Aggiungere audio in background nella documentazione di Speech Synthesis Markup Language (SSML). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.pitch Altezza dell'output audio.

Per informazioni sui valori accettati, consultare la tabella Regolare la prosodia nella documentazione del linguaggio SSML (Speech Synthesis Markup Language). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.rate Frequenza dell'output audio.

Per informazioni sui valori accettati, consultare la tabella Regolare la prosodia nella documentazione del linguaggio SSML (Speech Synthesis Markup Language). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.role Per alcune voci, è possibile regolare il ruolo di parlante. La voce può imitare un'età e un genere diversi, ma il nome della voce rimane invariato. Ad esempio, una voce maschile può alzare il tono e cambiare l'intonazione per imitare una voce femminile, ma il nome della voce non cambia. Se il ruolo è mancante o non è supportato per la voce, questo attributo viene ignorato.

Per informazioni sugli stili disponibili per le voci, vedere Stili e ruoli vocali.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.speakerProfileId ID del profilo dell'altoparlante di una voce personale.

Per informazioni sui nomi dei modelli di base voce personali disponibili, vedere Integrare la voce personale.
Per informazioni su come ottenere l'ID del profilo voce, vedere Lingua e supporto vocale.

Questa proprietà è obbligatoria quando inputKind è impostata su "PlainText".
synthesisConfig.style Per alcune voci è possibile regolare lo stile del parlato per esprimere emozioni diverse come allegria, empatia e calma. È possibile ottimizzare la voce per scenari diversi, ad esempio servizio clienti, notiziario e assistente vocale.

Per informazioni sugli stili disponibili per le voci, vedere Stili e ruoli vocali.

Questa proprietà facoltativa è applicabile solo quando synthesisConfig.style è impostata.
synthesisConfig.styleDegree Intensità dello stile del parlato. È possibile specificare uno stile più forte o più morbido per rendere il parlato più espressivo o pacato. L'intervallo dei valori accettati è compreso tra 0.01 e 2 inclusi. Il valore predefinito è 1, che corrisponde all'intensità predefinita dello stile. L'unità minima è 0.01, che comporta una leggera tendenza allo stile desiderato. Il valore 2 raddoppia l'intensità dello stile predefinito. Se il grado di stile manca o non è supportato per la voce, questo attributo viene ignorato.

Per informazioni sugli stili disponibili per le voci, vedere Stili e ruoli vocali.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
synthesisConfig.voice Voce che pronuncia l'output audio.

Per informazioni sulle voci neurali predefinite disponibili, vedere Lingue e voci supportate. Per usare una voce personalizzata, è necessario specificare un mapping valido di voce personalizzata e ID di distribuzione nella proprietà customVoices. Per usare una voce personale, è necessario specificare la synthesisConfig.speakerProfileId proprietà .

Questa proprietà è obbligatoria quando inputKind è impostata su "PlainText".
synthesisConfig.volume Volume dell'output audio.

Per informazioni sui valori accettati, consultare la tabella Regolare la prosodia nella documentazione del linguaggio SSML (Speech Synthesis Markup Language). I valori non validi vengono ignorati.

Questa proprietà facoltativa è applicabile solo quando inputKind è impostata su "PlainText".
inputKind Indica se la proprietà di testo inputs deve avere un valore di testo normale o SSML. I valori possibili senza distinzione tra maiuscole e minuscole sono "PlainText" e "SSML". Quando inputKind è impostata su "PlainText", è necessario impostare anche la proprietà della voce synthesisConfig.

Questa proprietà è obbligatoria.

Latenza di sintesi batch e procedure consigliate

Quando si usa la sintesi batch per generare la sintesi vocale sintetizzata, è importante considerare la latenza coinvolta e seguire le procedure consigliate per ottenere risultati ottimali.

Latenza nella sintesi batch

La latenza nella sintesi batch dipende da vari fattori, tra cui la complessità del testo di input, il numero di input nel batch e le funzionalità di elaborazione dell'hardware sottostante.

La latenza per la sintesi batch è la seguente (approssimativamente):

  • La latenza del 50% degli output vocali sintetizzati è compresa tra 10 e 20 secondi.

  • La latenza del 95% degli output vocali sintetizzati è compresa tra 120 secondi.

Procedure consigliate

Quando si considera la sintesi batch per l'applicazione, è consigliabile valutare se la latenza soddisfa i requisiti. Se la latenza è allineata alle prestazioni desiderate, la sintesi batch può essere una scelta adatta. Tuttavia, se la latenza non soddisfa le proprie esigenze, è possibile prendere in considerazione l'uso dell'API in tempo reale.

Codici di stato HTTP

Questa sezione descrive in dettaglio i codici di risposta HTTP e i messaggi dell'API di sintesi batch.

HTTP 200 OK

HTTP 200 OK indica che la richiesta ha avuto esito positivo.

HTTP 201 Creato

HTTP 201 Creato indica che la creazione della richiesta di sintesi batch (tramite HTTP POST) ha avuto esito positivo.

Errore HTTP 204

Un errore HTTP 204 indica che la richiesta ha avuto esito positivo, ma la risorsa non esiste. Ad esempio:

  • Si è tentato di ottenere o eliminare un processo di sintesi che non esiste.
  • Si è eliminato correttamente un processo di sintesi.

Errore HTTP 400

Ecco alcuni esempi che possono generare l'errore 400:

  • Il valore di outputFormat non è supportato o non è valido. Specificare un valore di formato valido oppure lasciare vuoto outputFormat per usare l'impostazione predefinita.
  • Il numero di input di testo richiesti ha superato il limite di 10.000.
  • Si è tentato di usare un ID di distribuzione non valido o una voce personalizzata non distribuita correttamente. Assicurarsi che la risorsa Voce abbia accesso alla voce personalizzata e che la voce personalizzata sia distribuita correttamente. È inoltre necessario assicurarsi che nella richiesta di sintesi batch il mapping di {"your-custom-voice-name": "your-deployment-ID"} sia corretto.
  • Si è tentato di usare una risorsa Voce F0, ma l'area supporta solo il piano tariffario per le risorse Voce Standard.

Errore HTTP 404

Non è possibile trovare l'entità specificata. Assicurarsi che l'ID sintesi sia corretto.

Errore HTTP 429

Ci sono troppe richieste recenti. Ogni applicazione client può inviare fino a 100 richieste per 10 secondi per ogni risorsa voce. Ridurre il numero di richieste al secondo.

Errore HTTP 500

L'errore interno del server HTTP 500 indica che la richiesta non è riuscita. Il messaggio di errore è riportato nel corpo della risposta.

Esempio di errore HTTP

Ecco una richiesta di esempio che genera un errore HTTP 400, perché la inputs proprietà è necessaria per creare un processo.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

In questo caso, le intestazioni della risposta includono HTTP/1.1 400 Bad Request.

Il corpo della risposta è simile all'esempio JSON seguente:

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

Passaggi successivi