Rozhraní API pro dávkovou syntézu textu na řeč

Článek
10/16/2024

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.

Diagram pracovního postupu rozhraní API pro syntézu služby Batch

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 inputKind vlastnost.
inputKind Pokud je vlastnost nastavena na "PlainText", pak musíte také nastavit voice vlastnost v .synthesisConfig V následujícím příkladu inputKind je nastavená na SSML, takže synthesisConfig není nastavená.
Volitelně můžete nastavit descriptionvlastnosti , timeToLiveInHoursa další vlastnosti. Další informace naleznete v tématu dávkové syntézy vlastností.

Poznámka:

Maximální přijatá velikost datové části JSON je 2 megabajty.

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 dávkové syntézy odpovědi GET .

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 dávkové syntézy odpovědi GET . 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 dávková syntéza vytvoření požadavku (přes HTTP PUT) byla ú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á outputFormat nebo neplatná. Zadejte platnou hodnotu formátu nebo nechte outputFormat prá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 .

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

Sdílet prostřednictvím

Rozhraní API pro dávkovou syntézu textu na řeč

Vytvoření dávkové syntézy

Získání dávkové syntézy

Výpis dávkové syntézy

Odstranění dávkové syntézy

Výsledky dávkové syntézy

Latence syntézy dávek a osvědčené postupy

Latence v dávkové syntéze

Osvědčené postupy

Stavové kódy HTTP

HTTP 200 OK

Vytvořeno HTTP 201

Chyba HTTP 204

Chyba HTTP 400

Chyba HTTP 404

Chyba HTTP 429

Chyba HTTP 500

Příklad chyby HTTP

Další kroky

Váš názor

Další materiály