API de síntese em Lote para conversão de texto em fala

Artigo
04/12/2024

A API de síntese em Lote pode sintetizar um grande volume de entrada de texto (longo e curto) de forma assíncrona. Editores e plataformas de conteúdo de áudio podem criar conteúdo de áudio longo em um lote. Por exemplo: audiolivros, artigos de notícias e documentos. A API de síntese em lotes pode criar áudio sintetizado maior do que dez minutos.

Importante

A API de síntese em Lote está disponível para o público geral. A API de Áudio Longo será desativada em 1º de abril de 2027. Para obter mais informações, confira Migrar para a API de síntese em lotes.

A API de áudio longo é assíncrona e não retorna áudio sintetizado em tempo real. Você envia arquivos de texto a serem sintetizados, sonda o status e baixa a saída de áudio quando o status indica êxito. As entradas de texto precisam ser texto sem formatação ou texto SSML (Linguagem de Marcação de Sintetização de Voz).

Este diagrama mostra uma visão geral de alto nível do fluxo de trabalho.

Diagrama do fluxo de trabalho da API de síntese em lotes.

Dica

Você também pode usar o SDK de Fala para criar áudio sintetizado por mais de 10 minutos iterando sobre o texto e sintetizando-o em trechos. Para obter um exemplo de C#, consulte o GitHub.

Você pode usar as seguintes operações de API REST para síntese em lotes:

Operação	Método	Chamada da API REST
Criar síntese em lote	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
Obter síntese em lote	`GET`	texttospeech/batchsyntheses/YourSynthesisId
Listar síntese em lote	`GET`	texttospeech/batchsyntheses
Excluir síntese em lote	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

Para obter exemplos de código, consulte GitHub.

Criar síntese em lotes

Para enviar uma solicitação de síntese em lote, construa o caminho e o corpo da solicitação HTTP PUT de acordo com as seguintes instruções:

Defina a propriedade inputKind obrigatória.
Se a propriedade inputKind estiver definida como "PlainText", você também precisará definir a propriedade voice no synthesisConfig. No exemplo abaixo, o inputKind está definido como "SSML", portanto, o synthesisConfig não está definido.
Opcionalmente, você pode definir as propriedades description, timeToLiveInHours e outras. Para obter mais informações, confira as propriedades de síntese em lotes.

Observação

O tamanho máximo de conteúdo JSON que será aceito é de 2 megabytes. Cada recurso de Fala poderá ter até 300 trabalhos de síntese em lote executados simultaneamente.

Defina o caminho YourSynthesisId necessário. O YourSynthesisId deve ser exclusivo. Deve ter de 3 a 64 caracteres, conter apenas números, letras, hifens, sublinhados e pontos, começar e terminar com uma letra ou um número.

Faça uma solicitação HTTP PUT usando o URI, conforme mostrado no exemplo a seguir. Substitua YourSpeechKey pela chave de recurso de Fala, YourSpeechRegion pela região do recurso de Fala e defina as propriedades do corpo da solicitação, conforme descrito anteriormente.

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"

Você deve receber um corpo de resposta no seguinte formato:

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

A propriedade status deve mudar do status NotStarted para Running e, por fim, para Succeeded ou Failed. Você pode chamar a API de síntese em lotes GET periodicamente até que o status retornado seja Succeeded ou Failed.

Obter síntese em lotes

Para obter o status do trabalho de síntese em lotes, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir. Substitua YourSpeechKey pela sua chave de recurso de fala e substitua YourSpeechRegion pela sua região de recurso de fala.

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

Você deve receber um corpo de resposta no seguinte formato:

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

No outputs.result, você pode baixar um arquivo ZIP que contém o áudio (como 0001.wav), um resumo e os detalhes de depuração. Para obter mais informações, confira os resultados da síntese em lotes.

Listar síntese em lotes

Para listar todos os trabalhos de síntese em lote para o recurso de Fala, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir. Substitua YourSpeechKey pela sua chave do recurso de Fala e substitua YourSpeechRegion pela sua região do recurso de Fala. Opcionalmente, você poderá definir os parâmetros de consulta skipe maxpagesize (até 100) na URL. O valor padrão de skip é 0 e o valor padrão de 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"

Você deve receber um corpo de resposta no seguinte formato:

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

A propriedade value na resposta json lista suas solicitações de síntese. A lista é paginada, com um tamanho máximo de página de 100. A propriedade "nextLink" é fornecida conforme necessário para obter a próxima página da lista paginada.

Excluir síntese em lotes

Exclua o histórico de trabalhos de síntese em lotes depois de recuperar os resultados da saída de áudio. O serviço de Fala manterá cada histórico de síntese por até 31 dias ou pela duração da propriedade timeToLiveInHours da solicitação, o que ocorrer antes. A data e a hora da exclusão automática (para trabalhos de síntese com um status de "Êxito" ou "Falha") é igual às propriedades lastActionDateTime + timeToLiveInHours.

Para excluir um trabalho de síntese em lotes, faça uma solicitação HTTP DELETE usando o URI, conforme mostrado no exemplo a seguir. Substitua YourSynthesisId por sua ID de síntese em lotes, substitua YourSpeechKey pela sua chave de recurso de Fala e substitua YourSpeechRegion pela sua região de recurso de Fala.

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

Os cabeçalhos de resposta incluem HTTP/1.1 204 No Content se a solicitação de exclusão tiver sido bem-sucedida.

Resultados da síntese em lotes

Depois de obter um trabalho de síntese em lotes com status igual a "Êxito", você poderá baixar os resultados de saída de áudio. Use a URL da propriedade outputs.result da resposta obter síntese em lotes.

Para obter o status do trabalho de síntese em lotes, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir. Substitua YourOutputsResultUrl pela URL da propriedade outputs.result da resposta obter síntese em lotes. Substitua YourSpeechKey pela chave do recurso de Fala.

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

Os resultados estão em um arquivo ZIP que contém o áudio (como 0001.wav), um resumo e os detalhes de depuração. O prefixo numerado de cada nome de arquivo (mostrado abaixo como [nnnn]) está na mesma ordem que as entradas de texto usadas quando você criou a síntese em lotes.

Observação

O arquivo [nnnn].debug.json contém a ID do resultado da síntese e outras informações que podem ajudar na solução de problemas. As propriedades que ele contém podem ser alteradas, portanto, você não deve assumir nenhuma dependência no formato JSON.

O arquivo de resumo contém os resultados da síntese para cada entrada de texto. Veja um arquivo summary.json de exemplo:

{
  "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 os dados de limite de frases tiverem sido solicitados ("sentenceBoundaryEnabled": true), um arquivo [nnnn].sentence.json correspondente será incluído nos resultados. Da mesma forma, se os dados de limite de palavras tiverem sido solicitados ("wordBoundaryEnabled": true), um arquivo [nnnn].word.json correspondente será incluído nos resultados.

Aqui está um exemplo de arquivo de dados de palavra com deslocamento de áudio e duração em milissegundos:

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

Latência de síntese em lote e práticas recomendadas

Ao usar a síntese em lote para gerar fala sintetizada, é importante considerar a latência envolvida e seguir as melhores práticas para obter resultados ideais.

Latência na síntese em lote

A latência na síntese em lote depende de vários fatores, incluindo a complexidade do texto de entrada, o número de entradas no lote e os recursos de processamento do hardware subjacente.

A latência da síntese em lotes é a seguinte (aproximadamente):

A latência de 50% das saídas de fala sintetizadas está dentro de 10 a 20 segundos.
A latência de 95% das saídas de fala sintetizadas está dentro de 120 segundos.

Práticas recomendadas

Ao considerar a síntese em lote para seu aplicativo, é recomendável avaliar se a latência atende aos seus requisitos. Se a latência estiver alinhada com o desempenho desejado, a síntese em lote poderá ser uma opção adequada. No entanto, se a latência não atender às suas necessidades, você poderá pensar em usar a API em tempo real.

Códigos de status HTTP

A seção detalha os códigos de resposta HTTP e as mensagens da API de síntese em lotes.

HTTP 200 – OK

"HTTP 200 – OK" indica que a solicitação foi bem-sucedida.

HTTP 201 – Criado

HTTP 201 Criado indica que a solicitação de criação de síntese em lote (via HTTP PUT) foi bem-sucedida.

Erro HTTP 204

Um erro HTTP 204 indica que a solicitação foi bem-sucedida, mas o recurso não existe. Por exemplo:

Você tentou obter ou excluir um trabalho de síntese que não existe.
Você excluiu com êxito um trabalho de síntese.

Erro HTTP 400

Aqui estão exemplos que podem resultar no erro 400:

O outputFormat é incompatível ou inválido. Forneça um valor de formato válido ou deixe outputFormat vazio para usar a configuração padrão.
O número de entradas de mensagem de texto solicitadas excedeu o limite de 10.000.
Você tentou usar uma ID de implantação inválida ou uma voz personalizada que não foi implantada com êxito. Verifique se o recurso de Fala tem acesso à voz personalizada e se a voz personalizada foi implantada com êxito. Você também precisa garantir que o mapeamento de {"your-custom-voice-name": "your-deployment-ID"} esteja correto em sua solicitação de síntese em lotes.
Você tentou usar um recurso de Fala F0, mas a região dá suporte apenas ao tipo de preço do recurso de Fala Standard.
Você tentou criar um novo trabalho de síntese em lote que excederia o limite de 300 trabalhos ativos. Cada recurso de Fala poderá ter até 300 trabalhos de síntese em lote que não têm um status de "Êxito" ou "Falha".

Erro HTTP 404

Não foi possível encontrar a entidade especificada. Verifique se a ID de síntese está correta.

Erro HTTP 429

Há um número excessivo de solicitações recentes. Cada aplicativo cliente poderá enviar até 100 solicitações por 10 segundos para cada recurso de Fala. Reduza o número de solicitações por segundo.

Erro HTTP 500

O erro de servidor interno HTTP 500 indica que a solicitação falhou. O corpo da resposta contém a mensagem de erro.

Exemplo de erro HTTP

Aqui está um exemplo de solicitação que resulta em um erro HTTP 400, porque a propriedade inputs é necessária para criar um trabalho.

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"

Nesse caso, os cabeçalhos de resposta incluem HTTP/1.1 400 Bad Request.

O corpo da resposta se parece com o seguinte exemplo de JSON:

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

API de síntese em Lote para conversão de texto em fala

Criar síntese em lotes

Obter síntese em lotes

Listar síntese em lotes

Excluir síntese em lotes

Resultados da síntese em lotes

Latência de síntese em lote e práticas recomendadas

Latência na síntese em lote

Práticas recomendadas

Códigos de status HTTP

HTTP 200 – OK

HTTP 201 – Criado

Erro HTTP 204

Erro HTTP 400

Erro HTTP 404

Erro HTTP 429

Erro HTTP 500

Exemplo de erro HTTP

Próximas etapas

Recursos adicionais