API di sintesi batch per la sintesi vocale

  • Articolo

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 più di 10 minuti.

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 è asincrona e non restituisce l'audio sintetizzato in tempo reale. Si inviano file di testo da sintetizzare, eseguire il polling dello stato e scaricare l'output audio quando lo stato indica l'esito positivo. Gli input di testo devono essere testo normale o testo SSML (Speech Synthesis Markup Language).

Questo diagramma offre una panoramica generale del flusso di lavoro.

Diagramma del flusso di lavoro dell'API Batch Synthesis.

Suggerimento

È anche possibile usare Speech SDK per creare audio sintetizzato più di 10 minuti eseguendo l'iterazione sul testo e sintetizzandolo in blocchi. Per un esempio C#, vedere GitHub.

È possibile usare le operazioni API REST seguenti per la sintesi batch:

Operazione Method Chiamata API REST
Creare la sintesi batch PUT texttospeech/batchsyntheses/YourSynthesisId
Ottenere la sintesi batch GET texttospeech/batchsyntheses/YourSynthesisId
Elencare la sintesi batch GET texttospeech/batchsyntheses
Eliminare la sintesi batch DELETE texttospeech/batchsyntheses/YourSynthesisId

Per esempi di codice, vedere GitHub.

Creare la sintesi batch

Per inviare una richiesta di sintesi batch, costruire il percorso e il corpo della richiesta HTTP PUT in base alle istruzioni seguenti:

  • Impostare la proprietà obbligatoria inputKind .
  • Se la inputKind proprietà è impostata su "PlainText", è necessario impostare anche la voice proprietà in synthesisConfig. Nell'esempio seguente, inputKind è impostato su "SSML", quindi non synthesisConfig è impostato.
  • Facoltativamente, è possibile impostare le descriptionproprietà , timeToLiveInHourse altre. Per altre informazioni, vedere Proprietà di sintesi batch.

Nota

La dimensione massima del payload JSON che verrà accettata è di 2 megabyte. Ogni risorsa voce può avere fino a 300 processi di sintesi batch in esecuzione simultaneamente.

Impostare il valore richiesto YourSynthesisId nel percorso. Deve YourSynthesisId essere univoco. Deve essere lungo 3-64, contiene solo numeri, lettere, trattini, caratteri di sottolineatura e punti, inizia e termina con una lettera o un numero.

Effettuare una richiesta HTTP PUT usando l'URI, come illustrato nell'esempio seguente. Sostituire YourSpeechKey con la chiave della risorsa Voce, sostituire YourSpeechRegion con l'area della risorsa Voce e impostare le proprietà del corpo della richiesta come descritto in precedenza.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

La status proprietà deve passare da NotStarted stato, a Runninge infine a Succeeded o Failed. È possibile chiamare periodicamente l'API di sintesi batch GET fino a quando lo stato restituito non è Succeeded o Failed.

Ottenere la sintesi batch

Per ottenere lo stato del processo di sintesi batch, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente. Sostituire YourSpeechKey con la chiave della risorsa Voce e sostituire YourSpeechRegion con l'area della risorsa Voce.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

Da outputs.resultè possibile scaricare un file ZIP contenente l'audio (ad esempio 0001.wav), riepilogo e dettagli di debug. Per altre informazioni, vedere Risultati della sintesi batch.

Elencare la sintesi batch

Per elencare tutti i processi di sintesi batch per la risorsa Voce, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente. Sostituire YourSpeechKey con la chiave della risorsa Voce e sostituire YourSpeechRegion con l'area della risorsa Voce. Facoltativamente, è possibile impostare i skip parametri di query e maxpagesize (fino a 100) nell'URL. Il valore predefinito per skip è 0 e il valore predefinito per maxpagesize è 100.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

Da outputs.resultè possibile scaricare un file ZIP contenente l'audio (ad esempio 0001.wav), riepilogo e dettagli di debug. Per altre informazioni, vedere Risultati della sintesi batch.

La value proprietà nella risposta json elenca le richieste di sintesi. L'elenco è impaginato, con dimensioni massime di pagina pari a 100. La "nextLink" proprietà viene fornita in base alle esigenze per ottenere la pagina successiva dell'elenco impaginato.

Eliminare la sintesi batch

Eliminare la cronologia dei processi di sintesi batch dopo aver recuperato i risultati dell'output audio. Il servizio Di riconoscimento vocale mantiene la cronologia di sintesi batch per un massimo di 31 giorni o la durata della proprietà della richiesta timeToLiveInHours , a qualsiasi tempo si verifichi prima. La data e l'ora dell'eliminazione automatica (per i lastActionDateTime + timeToLiveInHours processi di sintesi con stato "Succeeded" o "Failed") è uguale alle proprietà .

Per eliminare un processo di sintesi batch, eseguire una richiesta HTTP DELETE usando l'URI, come illustrato nell'esempio seguente. Sostituire YourSynthesisId con l'ID di sintesi batch, sostituire YourSpeechKey con la chiave della risorsa Voce e sostituire YourSpeechRegion con l'area della risorsa Voce.

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Le intestazioni di risposta includono HTTP/1.1 204 No Content se la richiesta di eliminazione ha avuto esito positivo.

Risultati della sintesi batch

Dopo aver visualizzato un processo di sintesi batch con status "Succeeded", è possibile scaricare i risultati dell'output audio. Usare l'URL dalla outputs.result proprietà della risposta di sintesi batch get.

Per ottenere il file dei risultati della sintesi batch, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente. Sostituire YourOutputsResultUrl con l'URL dalla outputs.result proprietà della risposta di sintesi batch get. Sostituire YourSpeechKey con la chiave della risorsa Voce.

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip

I risultati si trovano in un file ZIP che contiene l'audio (ad esempio 0001.wav), riepilogo e dettagli di debug. Il prefisso numerato di ogni nome file (illustrato di seguito come [nnnn]) è nello stesso ordine degli input di testo usati durante la creazione della sintesi batch.

Nota

Il [nnnn].debug.json file contiene l'ID risultato di sintesi e altre informazioni che potrebbero contribuire alla risoluzione dei problemi. Le proprietà contenute potrebbero cambiare, quindi non è consigliabile accettare dipendenze dal formato JSON.

Il file di riepilogo contiene i risultati di sintesi per ogni input di testo. Di seguito è riportato un esempio di un file summary.json:

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

Se sono stati richiesti dati limite frase ("sentenceBoundaryEnabled": true), nei risultati viene incluso un file corrispondente [nnnn].sentence.json . Analogamente, se sono stati richiesti dati limite di parola ("wordBoundaryEnabled": true), nei risultati viene incluso un file corrispondente [nnnn].word.json .

Ecco un file di dati di word di esempio con offset audio e durata in millisecondi:

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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

La 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 Created indica che la richiesta di sintesi batch di creazione (tramite HTTP PUT) 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.
  • È stato eliminato correttamente un processo di sintesi.

Errore HTTP 400

Ecco alcuni esempi che possono generare l'errore 400:

  • l'oggetto outputFormat non è supportato o non è valido. Specificare un valore di formato valido o lasciare outputFormat vuoto 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 stata distribuita correttamente. È inoltre necessario assicurarsi che il mapping di sia corretto nella richiesta di {"your-custom-voice-name": "your-deployment-ID"} sintesi batch.
  • Si è tentato di usare una risorsa F0 Speech, ma l'area supporta solo il piano tariffario della risorsa Voce Standard .
  • Si è tentato di creare un nuovo processo di sintesi batch che supererebbe il limite di 300 processi attivi. Ogni risorsa voce può avere fino a 300 processi di sintesi batch che non hanno lo stato "Succeeded" o "Failed".

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

Errore interno del server HTTP 500 indica che la richiesta non è riuscita. Il corpo della risposta contiene il messaggio di errore.

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