Batchsynthese-API voor tekst-naar-spraak

  • Artikel

De Batch-synthese-API kan asynchroon een grote hoeveelheid tekstinvoer (lang en kort) synthetiseren. Uitgevers en platforms voor audio-inhoud kunnen lange audio-inhoud in een batch maken. Bijvoorbeeld: audioboeken, nieuwsartikelen en documenten. De batchsynthese-API kan gesynthetiseerde audio langer dan 10 minuten maken.

Belangrijk

De Batch-synthese-API is algemeen beschikbaar. De Long Audio-API wordt op 1 april 2027 buiten gebruik gesteld. Zie Migreren naar batchsynthese-API voor meer informatie.

De batchsynthese-API is asynchroon en retourneert geen gesynthetiseerde audio in realtime. U verzendt tekstbestanden die moeten worden gesynthetiseerd, peilt naar de status en downloadt de audio-uitvoer wanneer de status aangeeft dat de status is geslaagd. De tekstinvoer moet tekst zonder opmaak of SSML-tekst (Speech Synthesis Markup Language) zijn.

Dit diagram biedt een algemeen overzicht van de werkstroom.

Diagram van de batchsynthese-API-werkstroom.

Tip

U kunt de Speech SDK ook gebruiken om gesynthetiseerde audio langer dan 10 minuten te maken door de tekst te herhalen en te synthetiseren in segmenten. Zie GitHub voor een C#-voorbeeld.

U kunt de volgende REST API-bewerkingen gebruiken voor batchsynthese:

Bewerking Methode REST API-aanroep
Batchsynthese maken PUT texttospeech/batchsyntheses/YourSynthesisId
Batchsynthese ophalen GET texttospeech/batchsyntheses/YourSynthesisId
Batchsynthese vermelden GET texttospeech/batchsyntheses
Batchsynthese verwijderen DELETE texttospeech/batchsyntheses/YourSynthesisId

Zie GitHub voor codevoorbeelden.

Batchsynthese maken

Als u een batchsyntheseaanvraag wilt verzenden, maakt u het HTTP PUT-aanvraagpad en de hoofdtekst volgens de volgende instructies:

  • Stel de vereiste inputKind eigenschap in.
  • Als de inputKind eigenschap is ingesteld op 'PlainText', moet u ook de voice eigenschap instellen in de synthesisConfig. In het onderstaande voorbeeld is de inputKind set ingesteld op 'SSML', dus het synthesisConfig is niet ingesteld.
  • U kunt desgewenst de description, timeToLiveInHoursen andere eigenschappen instellen. Zie de eigenschappen van batchsynthese voor meer informatie.

Notitie

De maximale grootte van de JSON-nettolading die wordt geaccepteerd, is 2 megabytes.

Stel het vereiste YourSynthesisId pad in. De YourSynthesisId moet uniek zijn. Het moet 3-64 lang zijn, bevat alleen cijfers, letters, afbreekstreepjes, onderstrepingstekens en punten, begint en eindigt met een letter of cijfer.

Maak een HTTP PUT-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang door YourSpeechKey de spraakresourcesleutel, vervang deze door YourSpeechRegion uw spraakresourceregio en stel de eigenschappen van de aanvraagbody in zoals eerder beschreven.

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"

U ontvangt een antwoordtekst in de volgende indeling:

{
  "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
  }
}

De status eigenschap moet van NotStarted status naar Running, en ten slotte naar Succeeded of Failed. U kunt de GET batchsynthese-API periodiek aanroepen totdat de geretourneerde status is Succeeded of Failed.

Batchsynthese ophalen

Als u de status van de batchsynthesetaak wilt ophalen, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang YourSpeechKey door uw Spraak-resourcesleutel en vervang deze door YourSpeechRegion uw spraakresourceregio.

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

U ontvangt een antwoordtekst in de volgende indeling:

{
  "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"
  }
}

Hier outputs.resultkunt u een ZIP-bestand met de audio (zoals 0001.wav), samenvatting en foutopsporingsgegevens downloaden. Zie batchsyntheseresultaten voor meer informatie.

Batchsynthese vermelden

Als u alle batchsynthesetaken voor de Spraak-resource wilt weergeven, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang door YourSpeechKey uw Spraak-resourcesleutel en vervang deze door YourSpeechRegion de spraakresourceregio. U kunt desgewenst de skip en maxpagesize (maximaal 100) queryparameters instellen in de URL. De standaardwaarde is skip 0 en de standaardwaarde is 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"

U ontvangt een antwoordtekst in de volgende indeling:

{
  "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"
}

Hier outputs.resultkunt u een ZIP-bestand met de audio (zoals 0001.wav), samenvatting en foutopsporingsgegevens downloaden. Zie batchsyntheseresultaten voor meer informatie.

De value eigenschap in het json-antwoord bevat uw syntheseaanvragen. De lijst is gepagineerd, met een maximale paginagrootte van 100. De "nextLink" eigenschap wordt indien nodig opgegeven om de volgende pagina van de gepagineerde lijst op te halen.

Batchsynthese verwijderen

Verwijder de geschiedenis van de batchsynthesetaak nadat u de resultaten van de audio-uitvoer hebt opgehaald. De Speech-service bewaart de geschiedenis van batchsynthese tot 31 dagen, of de duur van de aanvraageigenschap timeToLiveInHours , afhankelijk van wat eerder komt. De datum en tijd van automatische verwijdering (voor synthesetaken met de status Geslaagd of Mislukt) is gelijk aan de lastActionDateTime + timeToLiveInHours eigenschappen.

Als u een batchsynthesetaak wilt verwijderen, maakt u een HTTP DELETE-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang door YourSynthesisId uw batchsynthese-id, vervang deze door YourSpeechKey uw Spraak-resourcesleutel en vervang deze door YourSpeechRegion uw Spraak-resourceregio.

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

De antwoordheaders bevatten HTTP/1.1 204 No Content als de verwijderaanvraag is geslaagd.

Batchsyntheseresultaten

Nadat u een batchsynthesetaak met status Geslaagd hebt ontvangen, kunt u de resultaten van de audio-uitvoer downloaden. Gebruik de URL uit de outputs.result eigenschap van het antwoord voor batchsynthese ophalen.

Als u het batchsyntheseresultatenbestand wilt ophalen, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang YourOutputsResultUrl door de URL uit de outputs.result eigenschap van het antwoord voor batchsynthese ophalen. Vervang door YourSpeechKey uw Spraak-resourcesleutel.

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

De resultaten bevinden zich in een ZIP-bestand dat de audio (zoals 0001.wav), samenvatting en foutopsporingsgegevens bevat. Het genummerde voorvoegsel van elke bestandsnaam (hieronder weergegeven als [nnnn]) bevindt zich in dezelfde volgorde als de tekstinvoer die u hebt gebruikt bij het maken van de batchsynthese.

Notitie

Het [nnnn].debug.json bestand bevat de syntheseresultaat-id en andere informatie die kan helpen bij het oplossen van problemen. De eigenschappen die het bevat, kunnen worden gewijzigd, dus u moet geen afhankelijkheden nemen van de JSON-indeling.

Het samenvattingsbestand bevat de syntheseresultaten voor elke tekstinvoer. Hier volgt een voorbeeldbestand 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"
      }
    }
  ]
}

Als zinnengrensgegevens zijn aangevraagd ("sentenceBoundaryEnabled": true), wordt er een bijbehorend [nnnn].sentence.json bestand in de resultaten opgenomen. Als er woordgrensgegevens zijn aangevraagd ("wordBoundaryEnabled": true), wordt er ook een bijbehorend [nnnn].word.json bestand in de resultaten opgenomen.

Hier volgt een voorbeeld van een word-gegevensbestand met zowel audio-offset als duur in milliseconden:

[
  {
    "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
  }
]

Latentie en best practices voor batchsynthese

Wanneer u batchsynthese gebruikt voor het genereren van gesynthetiseerde spraak, is het belangrijk om rekening te houden met de latentie die betrokken is en best practices te volgen voor het bereiken van optimale resultaten.

Latentie in batchsynthese

De latentie in batchsynthese is afhankelijk van verschillende factoren, waaronder de complexiteit van de invoertekst, het aantal invoerinvoer in de batch en de verwerkingsmogelijkheden van de onderliggende hardware.

De latentie voor batchsynthese is als volgt (ongeveer):

  • De latentie van 50% van de gesynthetiseerde spraakuitvoer is binnen 10-20 seconden.

  • De latentie van 95% van de gesynthetiseerde spraakuitvoer is binnen 120 seconden.

Aanbevolen procedures

Wanneer u batchsynthese voor uw toepassing overweegt, is het raadzaam om te beoordelen of de latentie voldoet aan uw vereisten. Als de latentie overeenkomt met de gewenste prestaties, kan batchsynthese een geschikte keuze zijn. Als de latentie echter niet aan uw behoeften voldoet, kunt u overwegen om realtime-API te gebruiken.

HTTP-statuscode

In de sectie worden de HTTP-antwoordcodes en -berichten van de batchsynthese-API beschreven.

HTTP 200 OK

HTTP 200 OK geeft aan dat de aanvraag is geslaagd.

HTTP 201 gemaakt

HTTP 201 Created geeft aan dat de aanvraag voor batchsynthese (via HTTP PUT) is gemaakt.

HTTP 204-fout

Een HTTP 204-fout geeft aan dat de aanvraag is geslaagd, maar dat de resource niet bestaat. Voorbeeld:

  • U hebt geprobeerd een synthesetaak te verkrijgen of te verwijderen die niet bestaat.
  • U hebt een synthesetaak verwijderd.

HTTP 400-fout

Hier volgen voorbeelden die kunnen leiden tot de 400-fout:

  • De outputFormat naam wordt niet ondersteund of is ongeldig. Geef een geldige notatiewaarde op of laat outputFormat leeg om de standaardinstelling te gebruiken.
  • Het aantal aangevraagde tekstinvoeren heeft de limiet van 10.000 overschreden.
  • U hebt geprobeerd een ongeldige implementatie-id of een aangepaste spraak te gebruiken die niet is geïmplementeerd. Zorg ervoor dat de Spraak-resource toegang heeft tot de aangepaste spraak en dat de aangepaste spraak is geïmplementeerd. U moet er ook voor zorgen dat de toewijzing {"your-custom-voice-name": "your-deployment-ID"} juist is in uw batchsyntheseaanvraag.
  • U hebt geprobeerd een F0 Speech-resource te gebruiken, maar de regio ondersteunt alleen de prijscategorie Standard Speech-resources.
  • U hebt geprobeerd een nieuwe batchsynthesetaak te maken die de limiet van 300 actieve taken overschrijdt. Elke spraakresource kan maximaal 300 batchsynthesetaken bevatten die geen status 'Geslaagd' of 'Mislukt' hebben.

HTTP 404-fout

De opgegeven entiteit kan niet worden gevonden. Zorg ervoor dat de synthese-id juist is.

HTTP 429-fout

Er zijn te veel recente aanvragen. Elke clienttoepassing kan maximaal 100 aanvragen per 10 seconden verzenden voor elke Speech-resource. Verminder het aantal aanvragen per seconde.

HTTP 500-fout

HTTP 500 Interne serverfout geeft aan dat de aanvraag is mislukt. De hoofdtekst van het antwoord bevat het foutbericht.

Voorbeeld van HTTP-fout

Hier volgt een voorbeeld van een aanvraag die resulteert in een HTTP 400-fout, omdat de inputs eigenschap is vereist om een taak te maken.

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 dit geval bevatten HTTP/1.1 400 Bad Requestde antwoordheaders .

De hoofdtekst van het antwoord lijkt op het volgende JSON-voorbeeld:

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

Volgende stappen