Propriedades de síntese em lote para conversão de texto em fala

Artigo
10/16/2024

Importante

A API de síntese em lote está geralmente disponível. A API Long Audio será desativada em 1º de abril de 2027. Para obter mais informações, consulte Migrar para API de síntese em lote.

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 lote pode criar áudio sintetizado por mais de 10 minutos.

Algumas propriedades no formato JSON são necessárias quando você cria um novo trabalho de síntese em lote. Outras propriedades são opcionais. A resposta de síntese em lote inclui outras propriedades para fornecer informações sobre o estado da síntese e resultados. Por exemplo, a outputs.result propriedade contém o local dos arquivos de resultado de síntese em lote com saída de áudio e logs.

Propriedades de síntese em lote

As propriedades de síntese em lote são descritas na tabela a seguir.

Property	Description
`createdDateTime`	A data e a hora em que o trabalho de síntese em lote foi criado. Esta propriedade é somente leitura.
`customVoices`	O mapa de um nome de voz personalizado e sua ID de implantação. Por exemplo: `"customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}` Você pode usar o nome da voz em seu `synthesisConfig.voice` (quando o `inputKind` está definido como `"PlainText"`) ou no texto SSML de `inputs` (quando o `inputKind` está definido como `"SSML"`). Esta propriedade é necessária para usar uma voz personalizada. Se você tentar usar uma voz personalizada que não está definida aqui, o serviço retornará um erro.
`description`	A descrição da síntese do lote. Esta propriedade é opcional.
`id`	O ID do trabalho de síntese em lote que você passou no caminho. Esta propriedade é necessária no caminho.
`inputs`	O texto simples ou SSML a ser sintetizado. Quando estiver `inputKind` definido como `"PlainText"`, forneça texto sem formatação como mostrado aqui: `"inputs": [{"text": "The rainbow has seven colors."}]`. Quando estiver `inputKind` definido como `"SSML"`, forneça texto na SSML (Speech Synthesis Markup Language), conforme mostrado aqui: `"inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}]`. Inclua até 1.000 objetos de texto se quiser vários arquivos de saída de áudio. Aqui está um exemplo de texto de entrada que deve ser sintetizado em dois arquivos de saída de áudio: `"inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]`. No entanto, se a `properties.concatenateResult` propriedade estiver definida como `true`, cada resultado sintetizado será gravado no mesmo arquivo de saída de áudio. Você não precisa de entradas de texto separadas para novos parágrafos. Em qualquer uma das entradas de texto (até 1.000), você pode especificar novos parágrafos usando a cadeia de caracteres "\r\n" (nova linha). Aqui está um exemplo de texto de entrada com dois parágrafos que devem ser sintetizados para o mesmo arquivo de saída de áudio: `"inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]` Não há limites de parágrafo, mas o tamanho máximo da carga útil JSON (incluindo todas as entradas de texto e outras propriedades) é de 2 megabytes. Essa propriedade é necessária quando você cria um novo trabalho de síntese em lote. Essa propriedade não é incluída na resposta quando você recebe o trabalho de síntese.
`internalId`	O ID do trabalho de síntese de lote interno. Esta propriedade é somente leitura.
`lastActionDateTime`	A data e hora mais recentes em que o valor da `status` propriedade foi alterado. Esta propriedade é somente leitura.
`outputs.result`	A localização dos arquivos de resultado de síntese em lote com saída de áudio e logs. Esta propriedade é somente leitura.
`properties`	Um conjunto definido de definições de configuração de síntese em lote opcionais.
`properties.sizeInBytes`	O tamanho da saída de áudio em bytes. Esta propriedade é somente leitura.
`properties.billingDetails`	O número de palavras que foram processadas e faturadas por `customNeuralCharacters` vozes versus `neuralCharacters` vozes (pré-construídas). Esta propriedade é somente leitura.
`properties.concatenateResult`	Determina se o resultado deve ser concatenado. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão.
`properties.decompressOutputFiles`	Determina se os arquivos de resultado da síntese devem ser descompactados no contêiner de destino. Esta propriedade só pode ser definida quando a `destinationContainerUrl` propriedade está definida. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão.
`properties.destinationContainerUrl`	Os resultados da síntese em lote podem ser armazenados em um contêiner gravável do Azure. Se você não especificar um URI de contêiner com token SAS (assinaturas de acesso compartilhado), o serviço de Fala armazenará os resultados em um contêiner gerenciado pela Microsoft. Não há suporte para SAS com políticas de acesso armazenado. Quando o trabalho de síntese é excluído, os dados do resultado também são excluídos. Essa propriedade opcional não é incluída na resposta quando você recebe o trabalho de síntese.
`properties.destinationPath`	O caminho do prefixo com o qual os resultados da síntese em lote podem ser armazenados. Se você não especificar um caminho de prefixo, o caminho de prefixo padrão será `YourSpeechResourceId/YourSynthesisId`. Esta propriedade opcional só pode ser definida quando a `destinationContainerUrl` propriedade é definida.
`properties.durationInMilliseconds`	A duração da saída de áudio em milissegundos. Esta propriedade é somente leitura.
`properties.failedAudioCount`	A contagem de entradas de síntese em lote para saída de áudio falhou. Esta propriedade é somente leitura.
`properties.outputFormat`	O formato de saída de áudio. Para obter informações sobre os valores aceitos, consulte Formatos de saída de áudio. O formato de saída predefinido é `riff-24khz-16bit-mono-pcm`.
`properties.sentenceBoundaryEnabled`	Determina se os dados de limite de sentença devem ser gerados. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão. Se os dados de limite de frase forem solicitados, um arquivo correspondente `[nnnn].sentence.json` será incluído no arquivo ZIP de dados de resultados.
`properties.succeededAudioCount`	A contagem de entradas de síntese em lote para saída de áudio foi bem-sucedida. Esta propriedade é somente leitura.
`properties.timeToLiveInHours`	Uma duração em horas após a criação do trabalho de síntese, quando os resultados da síntese serão automaticamente excluídos. Essa configuração opcional é `744` (31 dias) por padrão. O tempo máximo de vida é de 31 dias. A data e a hora da exclusão automática (para trabalhos de síntese com um status de "Aprovado" ou "Reprovado") são iguais às `lastActionDateTime` + `timeToLiveInHours` propriedades. Caso contrário, você pode chamar o método de síntese de exclusão para remover o trabalho mais cedo.
`properties.wordBoundaryEnabled`	Determina se os dados de limite de palavra devem ser gerados. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão. Se os dados de limite do Word forem solicitados, um arquivo correspondente `[nnnn].word.json` será incluído no arquivo ZIP de dados de resultados.
`status`	O status de processamento da síntese em lote. O status deve progredir de "NotStarted" para "Running" e, finalmente, para "Succeeded" ou "Failed". Esta propriedade é somente leitura.
`synthesisConfig`	As definições de configuração a serem usadas para síntese em lote de texto sem formatação. Esta propriedade só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.backgroundAudio`	O áudio de fundo para cada saída de áudio. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.backgroundAudio.fadein`	A duração do fade-in de áudio em segundo plano é de milissegundos. O valor padrão é `0`, que é o equivalente a no fade in. Valores aceites: `0` a `10000` inclusivo. Para obter informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.backgroundAudio.fadeout`	A duração do fade-out de áudio em segundo plano em milissegundos. O valor padrão é `0`, que é o equivalente a no fade out. Valores aceites: `0` a `10000` inclusivo. Para obter informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.backgroundAudio.src`	O local do URI do arquivo de áudio em segundo plano. Para obter informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade é necessária quando `synthesisConfig.backgroundAudio` é definida.
`synthesisConfig.backgroundAudio.volume`	O volume do arquivo de áudio de fundo. Valores aceites: `0` a `100` inclusivo. O valor predefinido é `1`. Para obter informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.pitch`	O tom da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela de ajuste de prosódia na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.rate`	A taxa da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela de ajuste de prosódia na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.role`	Para algumas vozes, você pode ajustar a encenação falante. A voz pode imitar uma idade e sexo diferentes, mas o nome da voz não é alterado. Por exemplo, uma voz masculina pode elevar o tom e mudar a entonação para imitar uma voz feminina, mas o nome da voz não é alterado. Se a função estiver ausente ou não for suportada para sua voz, esse atributo será ignorado. Para obter informações sobre os estilos disponíveis por voz, consulte Estilos e funções de voz. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.speakerProfileId`	O ID do perfil do orador de uma voz pessoal. Para obter informações sobre nomes de modelos de base de voz pessoal disponíveis, consulte integrar voz pessoal. Para obter informações sobre como obter o ID do perfil do orador, consulte Suporte de idioma e voz. Esta propriedade é necessária quando `inputKind` é definida como `"PlainText"`.
`synthesisConfig.style`	Para algumas vozes, você pode ajustar o estilo de fala para expressar diferentes emoções, como alegria, empatia e calma. Você pode otimizar a voz para diferentes cenários, como atendimento ao cliente, noticiário e assistente de voz. Para obter informações sobre os estilos disponíveis por voz, consulte Estilos e funções de voz. Esta propriedade opcional só é aplicável quando `synthesisConfig.style` é definida.
`synthesisConfig.styleDegree`	A intensidade do estilo de falar. Você pode especificar um estilo mais forte ou suave para tornar o discurso mais expressivo ou moderado. O intervalo de valores aceites é: 0,01 a 2 inclusive. O valor padrão é 1, o que significa a intensidade de estilo predefinida. A unidade mínima é 0,01, o que resulta numa ligeira tendência para o estilo alvo. Um valor de 2 resulta em uma duplicação da intensidade de estilo padrão. Se o grau de estilo estiver ausente ou não for suportado para sua voz, esse atributo será ignorado. Para obter informações sobre os estilos disponíveis por voz, consulte Estilos e funções de voz. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`synthesisConfig.voice`	A voz que fala a saída de áudio. Para obter informações sobre as vozes neurais pré-construídas disponíveis, consulte Suporte de idioma e voz. Para usar uma voz personalizada, você deve especificar um mapeamento de voz e ID de implantação personalizado válido na `customVoices` propriedade. Para usar uma voz pessoal, você precisa especificar a `synthesisConfig.speakerProfileId` propriedade. Esta propriedade é necessária quando `inputKind` é definida como `"PlainText"`.
`synthesisConfig.volume`	O volume da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela de ajuste de prosódia na documentação SSML (Speech Synthesis Markup Language). Os valores inválidos são ignorados. Esta propriedade opcional só é aplicável quando `inputKind` está definida como `"PlainText"`.
`inputKind`	Indica se a `inputs` propriedade text deve ser texto sem formatação ou SSML. Os possíveis valores que não diferenciam maiúsculas de minúsculas são "PlainText" e "SSML". Quando o `inputKind` estiver definido como `"PlainText"`, você também deve definir a `synthesisConfig` propriedade voice. Esta propriedade é necessária.

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 alcançar os melhores resultados.

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 as capacidades de processamento do hardware subjacente.

A latência para a síntese em lote é a seguinte (aproximadamente):

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

Melhores práticas

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 pode ser uma escolha adequada. No entanto, se a latência não atender às suas necessidades, você pode considerar o uso de API em tempo real.

Códigos de estado HTTP

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

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 síntese de lote de criação (via HTTP POST) 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 não é suportado ou é inválido. Forneça um valor de formato válido ou deixe outputFormat em branco para usar a configuração padrão.
O número de entradas 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 deve garantir que o mapeamento de está correto em sua solicitação de síntese de {"your-custom-voice-name": "your-deployment-ID"} lote.
Você tentou usar um recurso de Fala F0 , mas a região oferece suporte apenas à camada de preço de recurso de Fala Padrão .

Erro HTTP 404

A entidade especificada não pode ser encontrada. Confirme se o ID da sintetização está correto.

Erro HTTP 429

Há demasiados pedidos recentes. Cada aplicativo cliente pode 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

HTTP 500 Internal Server Error 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 inputs propriedade é 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 é semelhante ao seguinte exemplo JSON:

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

Partilhar via