Rozhraní API pro dávkovou syntézu textu na řeč
Rozhraní API pro syntézu služby Batch může syntetizovat velký objem textového vstupu (dlouhý a krátký) asynchronně. Vydavatelé a platformy zvukového obsahu můžou v dávce vytvářet dlouhý zvukový obsah. Například: zvukové knihy, články o novinkách a dokumenty. Rozhraní API pro syntézu dávek může vytvořit syntetizovaný zvuk delší než 10 minut.
Důležité
Rozhraní API pro syntézu služby Batch je obecně dostupné. Rozhraní API Long Audio bude vyřazeno 1. dubna 2027. Další informace naleznete v tématu Migrace do rozhraní API pro syntézu dávek.
Rozhraní API pro syntézu dávek je asynchronní a nevrací syntetizovaný zvuk v reálném čase. Odešlete textové soubory, které se mají syntetizovat, dotazovat se na stav a stáhnout zvukový výstup, když stav indikuje úspěch. Textové vstupy musí být prostý text nebo text jazyka SSML (Speech Synthesis Markup Language).
Tento diagram poskytuje základní přehled pracovního postupu.
Tip
Sadu Speech SDK můžete také použít k vytvoření syntetizovaného zvuku déle než 10 minut iterací textu a jeho syntetizací v blocích dat. Příklad jazyka C# najdete na GitHubu.
K dávkové syntéze můžete použít následující operace rozhraní REST API:
| Operace | metoda | Volání rozhraní REST API |
|---|---|---|
| Vytvoření dávkové syntézy | PUT |
texttospeech/batchsyntheses/YourSynthesisId |
| Získání dávkové syntézy | GET |
texttospeech/batchsyntheses/YourSynthesisId |
| Výpis dávkové syntézy | GET |
texttospeech/batchsyntheses |
| Odstranění dávkové syntézy | DELETE |
texttospeech/batchsyntheses/YourSynthesisId |
Ukázky kódu najdete na GitHubu.
Vytvoření dávkové syntézy
Chcete-li odeslat dávkový souhrnný požadavek, vytvořte cestu a text požadavku HTTP PUT podle následujících pokynů:
- Nastavte požadovanou
inputKindvlastnost. inputKindPokud je vlastnost nastavena na "PlainText", pak musíte také nastavitvoicevlastnost v .synthesisConfigV následujícím příkladuinputKindje nastavená na SSML, takžesynthesisConfignení nastavená.- Volitelně můžete nastavit
descriptionvlastnosti ,timeToLiveInHoursa další vlastnosti. Další informace naleznete v tématu dávkové syntézy vlastností.
Poznámka:
Maximální velikost datové části JSON, která bude přijata, je 2 megabajty. Každý prostředek služby Speech může mít až 300 dávkových syntézy úloh, které běží souběžně.
Nastavte požadovanou YourSynthesisId cestu. Musí YourSynthesisId být jedinečný. Musí mít délku 3 až 64, obsahuje pouze číslice, písmena, pomlčky, podtržítka a tečky, začíná a končí písmenem nebo číslicí.
Vytvořte požadavek HTTP PUT pomocí identifikátoru URI, jak je znázorněno v následujícím příkladu. Nahraďte YourSpeechKey klíčem prostředku služby Speech, nahraďte YourSpeechRegion oblastí prostředků služby Speech a nastavte vlastnosti textu požadavku, jak jsme popsali dříve.
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"
Měl by se zobrazit text odpovědi v následujícím formátu:
{
"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
}
}
Vlastnost status by měla probíhat od NotStarted stavu do Runninga nakonec do Succeeded nebo Failed. Rozhraní API dávkové syntézy GET můžete volat pravidelně, dokud vrácený stav není Succeeded nebo Failed.
Získání dávkové syntézy
Pokud chcete získat stav dávkové úlohy syntézy, vytvořte požadavek HTTP GET pomocí identifikátoru URI, jak je znázorněno v následujícím příkladu. Nahraďte YourSpeechKey klíčem prostředku služby Speech a nahraďte YourSpeechRegion oblastí prostředků služby Speech.
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Měl by se zobrazit text odpovědi v následujícím formátu:
{
"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"
}
}
Můžete outputs.resultsi stáhnout soubor ZIP, který obsahuje zvuk (například 0001.wav), souhrn a podrobnosti ladění. Další informace najdete v tématu dávkové syntézy výsledků.
Výpis dávkové syntézy
Pokud chcete vypsat všechny dávkové úlohy syntézy prostředku služby Speech, vytvořte požadavek HTTP GET pomocí identifikátoru URI, jak je znázorněno v následujícím příkladu. Nahraďte YourSpeechKey klíčem prostředku služby Speech a nahraďte YourSpeechRegion oblastí prostředků služby Speech. Volitelně můžete v adrese URL nastavit skip parametry dotazu a maxpagesize (až 100). Výchozí hodnota je skip 0 a výchozí hodnota je 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"
Měl by se zobrazit text odpovědi v následujícím formátu:
{
"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"
}
Můžete outputs.resultsi stáhnout soubor ZIP, který obsahuje zvuk (například 0001.wav), souhrn a podrobnosti ladění. Další informace najdete v tématu dávkové syntézy výsledků.
Vlastnost value v odpovědi JSON obsahuje vaše žádosti o syntézu. Seznam je stránkovaný s maximální velikostí stránky 100. Vlastnost "nextLink" je poskytována podle potřeby k získání další stránky stránkovaného seznamu.
Odstranění dávkové syntézy
Po načtení výsledků zvukového výstupu odstraňte historii dávkové syntézy úloh. Služba Speech uchovává historii dávkové syntézy po dobu až 31 dnů nebo dobu trvání vlastnosti požadavku timeToLiveInHours , podle toho, co nastane dříve. Datum a čas automatického odstranění (pro úlohy syntézy se stavem Úspěch nebo Selhání) se rovná vlastnostem lastActionDateTime + timeToLiveInHours .
Pokud chcete odstranit dávkovou úlohu syntézy, vytvořte požadavek HTTP DELETE pomocí identifikátoru URI, jak je znázorněno v následujícím příkladu. Nahraďte YourSynthesisId id dávkové syntézy, nahraďte YourSpeechKey klíčem prostředku služby Speech a nahraďte YourSpeechRegion oblastí prostředků služby Speech.
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Hlavičky odpovědi zahrnují HTTP/1.1 204 No Content , pokud požadavek na odstranění proběhl úspěšně.
Výsledky dávkové syntézy
Jakmile získáte dávkovou úlohu syntézy s status výsledkem "Úspěch", můžete si stáhnout výsledky zvukového výstupu. Použijte adresu URL z outputs.result vlastnosti získání dávkové syntézy odpovědi.
Pokud chcete získat soubor výsledků syntézy dávek, vytvořte požadavek HTTP GET pomocí identifikátoru URI, jak je znázorněno v následujícím příkladu. Nahraďte YourOutputsResultUrl adresou URL z outputs.result vlastnosti získání dávkové syntézy odpovědi. Nahraďte YourSpeechKey klíčem prostředku služby Speech.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip
Výsledky jsou v souboru ZIP, který obsahuje zvuk (například 0001.wav), souhrn a podrobnosti ladění. Číslované předpony každého názvu souboru (zobrazeného níže jako [nnnn]) je ve stejném pořadí jako textové vstupy použité při vytváření dávkové syntézy.
Poznámka:
Soubor [nnnn].debug.json obsahuje ID výsledku syntézy a další informace, které vám můžou pomoct s řešením potíží. Vlastnosti, které obsahuje, se můžou změnit, takže byste neměli brát žádné závislosti ve formátu JSON.
Souhrnný soubor obsahuje souhrnné výsledky pro každý textový vstup. Tady je ukázkový summary.json soubor:
{
"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"
}
}
]
}
Pokud byla požadována data hranic věty ("sentenceBoundaryEnabled": true), bude do výsledků zahrnut odpovídající [nnnn].sentence.json soubor. Podobně platí, že pokud byla požadována data hranic slova ("wordBoundaryEnabled": true), bude do výsledků zahrnut odpovídající [nnnn].word.json soubor.
Tady je příklad datového souboru slova s posunem zvuku i dobou trvání v milisekundách:
[
{
"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
}
]
Latence syntézy dávek a osvědčené postupy
Při použití dávkové syntézy pro generování syntetizované řeči je důležité zvážit latenci a dodržovat osvědčené postupy pro dosažení optimálních výsledků.
Latence v dávkové syntéze
Latence dávkové syntézy závisí na různých faktorech, včetně složitosti vstupního textu, počtu vstupů v dávce a schopností zpracování základního hardwaru.
Latence dávkové syntézy je následující (přibližně):
Latence 50 % syntetizovaných výstupů řeči je během 10 až 20 sekund.
Latence 95 % syntetizovaných výstupů řeči je do 120 sekund.
Osvědčené postupy
Při zvažování dávkové syntézy pro vaši aplikaci se doporučuje posoudit, jestli latence splňuje vaše požadavky. Pokud latence odpovídá požadovanému výkonu, může být dávková syntéza vhodná volba. Pokud ale latence nevyhovuje vašim potřebám, můžete zvážit použití rozhraní API v reálném čase.
Stavové kódy HTTP
Tato část podrobně popisuje kódy odpovědí HTTP a zprávy z rozhraní API pro syntézu dávek.
HTTP 200 OK
HTTP 200 OK označuje, že požadavek byl úspěšný.
Vytvořeno HTTP 201
Http 201 Created označuje, že vytvoření dávkové syntézy požadavku (přes HTTP PUT) bylo úspěšné.
Chyba HTTP 204
Chyba HTTP 204 značí, že požadavek byl úspěšný, ale prostředek neexistuje. Příklad:
- Pokusili jste se získat nebo odstranit souhrnnou úlohu, která neexistuje.
- Úspěšně jste odstranili úlohu syntézy.
Chyba HTTP 400
Tady jsou příklady, které můžou vést k chybě 400:
- Nepodporovaná
outputFormatnebo neplatná. Zadejte platnou hodnotu formátu nebo nechteoutputFormatprázdnou, aby bylo možné použít výchozí nastavení. - Počet požadovaných textových vstupů překročil limit 10 000.
- Pokusili jste se použít neplatné ID nasazení nebo vlastní hlas, který se úspěšně nenasadil. Ujistěte se, že prostředek služby Speech má přístup k vlastnímu hlasu a že je vlastní hlas úspěšně nasazený. Musíte také zajistit správnost mapování
{"your-custom-voice-name": "your-deployment-ID"}v dávkové syntéze požadavku. - Pokusili jste se použít prostředek F0 Speech, ale tato oblast podporuje pouze cenovou úroveň prostředků Služby Speech úrovně Standard .
- Pokusili jste se vytvořit novou dávkovou úlohu syntézy, která by překročila limit 300 aktivních úloh. Každý prostředek služby Speech může mít až 300 dávkových úloh syntézy, které nemají stav Úspěch nebo Selhání.
Chyba HTTP 404
Zadaná entita nebyla nalezena. Ujistěte se, že je ID syntézy správné.
Chyba HTTP 429
Existuje příliš mnoho nedávných požadavků. Každá klientská aplikace může odesílat až 100 požadavků za 10 sekund pro každý prostředek služby Speech. Snižte počet požadavků za sekundu.
Chyba HTTP 500
Vnitřní chyba serveru HTTP 500 značí, že požadavek selhal. Text odpovědi obsahuje chybovou zprávu.
Příklad chyby HTTP
Tady je příklad požadavku, který má za následek chybu HTTP 400, protože inputs vlastnost je nutná k vytvoření úlohy.
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"
V tomto případě hlavičky odpovědi zahrnují HTTP/1.1 400 Bad Request.
Text odpovědi se podobá následujícímu příkladu JSON:
{
"error": {
"code": "BadRequest",
"message": "The inputs is required."
}
}