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

Artigo
09/12/2024

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

Algumas propriedades em 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 status e os resultados da síntese. Por exemplo, a propriedade outputs.result contém o local dos arquivos de resultado de síntese em lotes com saída de áudio e logs.

Propriedades da síntese em lotes

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

Propriedade	Descrição
`createdDateTime`	A data e a hora em que o trabalho de síntese em lotes foi criado. Esta propriedade é somente para leitura.
`customVoices`	O mapa de um nome de voz personalizado e a respectiva ID de implantação. Por exemplo: `"customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}` Você pode usar o nome de voz em seu `synthesisConfig.voice` (quando o `inputKind` é definido como `"PlainText"`) ou dentro do texto SSML de `inputs` (quando o `inputKind` é definido como `"SSML"`). Essa 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 em lotes. Essa propriedade é opcional.
`id`	A ID do trabalho de síntese em lote que você passou no caminho. Essa propriedade é obrigatória no caminho.
`inputs`	O texto sem formatação ou SSML a ser sintetizado. Quando `inputKind` estiver definido como `"PlainText"`, forneça texto sem formatação, conforme mostrado aqui: `"inputs": [{"text": "The rainbow has seven colors."}]`. Quando `inputKind` estiver definido como `"SSML"`, forneça texto na SSML (Linguagem de Marcação de Sintetização de Voz), 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 desejar vários arquivos de saída de áudio. Aqui está o texto de entrada de exemplo 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 propriedade `properties.concatenateResult` for definida como `true`, cada resultado sintetizado é 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á o texto de entrada de exemplo 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 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 lotes. Essa propriedade não é incluída na resposta quando você obtém o trabalho de síntese.
`internalId`	A ID interna do trabalho de síntese em lote. Esta propriedade é somente para leitura.
`lastActionDateTime`	A data e a hora mais recentes em que o valor da propriedade `status` foi alterado. Esta propriedade é somente para leitura.
`outputs.result`	O local dos arquivos de resultado de síntese em lotes com saída de áudio e logs. Esta propriedade é somente para leitura.
`properties`	Um conjunto definido de configurações opcionais de síntese em lotes.
`properties.sizeInBytes`	O tamanho da saída de áudio em bytes. Esta propriedade é somente para leitura.
`properties.billingDetails`	O número de palavras que foram processadas e cobradas pelas vozes (predefinidas) de `customNeuralCharacters` versus `neuralCharacters`. Esta propriedade é somente para 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 de síntese devem ser descompactados no contêiner de destino. Essa propriedade somente poderá ser definida quando a propriedade `destinationContainerUrl` estiver configurada. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão.
`properties.destinationContainerUrl`	Os resultados da síntese em lotes podem ser armazenados em um contêiner gravável do Azure. Quando você não especifica um URI de contêiner com SAS (Assinaturas de Acesso Compartilhado), o Serviço de Fala armazena os resultados em um contêiner gerenciado pela Microsoft. Não há suporte para a SAS com políticas de acesso armazenadas. Quando o trabalho de síntese é excluído, o mesmo ocorre com os dados de resultado. Essa propriedade opcional não é incluída na resposta quando você obtém o trabalho de síntese.
`properties.destinationPath`	O caminho de prefixo com o qual os resultados da síntese em lotes podem ser armazenados. Se você não especificar um caminho de prefixo, o caminho do prefixo padrão será `YourSpeechResourceId/YourSynthesisId`. Essa propriedade opcional somente poderá ser definida quando a propriedade `destinationContainerUrl` estiver configurada.
`properties.durationInMilliseconds`	A duração da saída de áudio em milissegundos. Esta propriedade é somente para leitura.
`properties.failedAudioCount`	Falha na contagem de entradas de síntese em lotes para saída de áudio. Esta propriedade é somente para leitura.
`properties.outputFormat`	O formato de saída de áudio. Para obter informações sobre os valores aceitos, confira formatos de saída de áudio. O formato de saída padrão é `riff-24khz-16bit-mono-pcm`.
`properties.sentenceBoundaryEnabled`	Determina se os dados de limite de frase devem ser gerados. Esse valor opcional `bool` ("true" ou "false") é "false" por padrão. Se os dados de limite de frase tiverem sido solicitados, um arquivo correspondente `[nnnn].sentence.json` é incluído no arquivo zip de dados de resultados.
`properties.succeededAudioCount`	Falha na contagem de entradas de síntese em lotes para saída de áudio bem-sucedidas. Esta propriedade é somente para 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 excluídos automaticamente. Essa configuração opcional é `744` (31 dias) por padrão. A vida útil máxima é de 31 dias. 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`. Caso contrário, você pode chamar o método de síntese delete 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 de palavra tiverem sido solicitados, um arquivo correspondente `[nnnn].word.json` será incluído no arquivo zip de dados de resultados.
`status`	O status de processamento de síntese em lotes. O status deve progredir de "NotStarted" para "Em execução" e, por fim, para "Êxito" ou "Falha". Esta propriedade é somente para leitura.
`synthesisConfig`	As definições de configuração a serem usadas para síntese em lotes de texto sem formatação. Essa propriedade só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.backgroundAudio`	O áudio em segundo plano para cada saída de áudio. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.backgroundAudio.fadein`	A duração do início gradual do áudio de fundo em milissegundos. O valor padrão é `0`, que é o equivalente a sem fade in. Valores aceitos: `0` a `10000` inclusive. Para obter mais informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação de SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.backgroundAudio.fadeout`	A duração do final gradual do áudio de fundo em milissegundos. O valor padrão é `0`, o que equivale a nenhum fade out. Valores aceitos: `0` a `10000` inclusive. Para obter mais informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação de SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.backgroundAudio.src`	O local do URI do arquivo de áudio de fundo. Para obter mais informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação de SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade será necessária quando `synthesisConfig.backgroundAudio` estiver definido.
`synthesisConfig.backgroundAudio.volume`	Especifica o volume do arquivo de áudio de fundo. Valores aceitos: `0` a `100` inclusive. O valor padrão é `1`. Para obter mais informações, consulte a tabela de atributos em adicionar áudio em segundo plano na documentação de SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.pitch`	O tom da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela ajustar prosódia na documentação do SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.rate`	A taxa da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela ajustar prosódia na documentação do SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.role`	Para algumas vozes, você poderá ajustar a atuação de fala. A voz pode imitar uma idade e um gênero diferentes, mas o nome da voz não é alterado. Por exemplo, uma voz masculina pode aumentar o tom e alterar 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 compatível com sua voz, esse atributo será ignorado. Para obter informações sobre os estilos disponíveis por voz, confira estilos de voz e funções. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.speakerProfileId`	A ID do perfil do falante de uma voz pessoal. Para obter mais informações sobre nomes de modelos de base de voz pessoal disponíveis, consulte integrar voz pessoal. Para obter mais informações sobre como obter a ID do perfil do falante, consulte suporte a idioma e voz. Essa propriedade é necessária quando `inputKind` está configurado como `"PlainText"`.
`synthesisConfig.style`	Para algumas vozes, é possível ajustar o estilo de fala para expressar emoções diferentes como alegria, empatia e tranquilidade. Também é possível otimizar a voz para cenários diferentes, como atendimento ao cliente, noticiário e assistente de voz. Para obter informações sobre os estilos disponíveis por voz, confira estilos de voz e funções. Essa propriedade opcional somente será aplicável quando `synthesisConfig.style` estiver definido.
`synthesisConfig.styleDegree`	A intensidade do estilo de fala. Você pode especificar um estilo mais forte ou mais suave para deixar a fala mais expressiva ou suave. O intervalo de valores aceitos é: 0,01 a 2 inclusivo. O valor padrão é 1, o que significa a intensidade do estilo predefinido. A unidade mínima é 0,01, o que resulta em uma leve tendência para o estilo de destino. Um valor igual a 2 resulta no dobro da intensidade do estilo padrão. Se o grau de estilo estiver ausente ou não for compatível com sua voz, esse atributo será ignorado. Para obter informações sobre os estilos disponíveis por voz, confira estilos de voz e funções. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`synthesisConfig.voice`	A voz que fala a saída de áudio. Para obter informações sobre as vozes neurais predefinidas disponíveis, confira suporte a linguagem e voz. Para usar uma voz personalizada, você precisa especificar um mapeamento válido de ID de implantação e voz personalizada na propriedade `customVoices`. Para usar uma voz pessoal, será necessário especificar a propriedade `synthesisConfig.speakerProfileId`. Essa propriedade é necessária quando `inputKind` está configurado como `"PlainText"`.
`synthesisConfig.volume`	O volume da saída de áudio. Para obter informações sobre os valores aceitos, consulte a tabela ajustar prosódia na documentação do SSML (Linguagem de Marcação de Sintetização de Voz). Valores inválidos são ignorados. Essa propriedade opcional só é aplicável quando `inputKind` é definido como `"PlainText"`.
`inputKind`	Indica se a propriedade de texto `inputs` deve ser texto sem formatação ou SSML. Os valores possíveis que não diferenciam maiúsculas de minúsculas são "PlainText" e "SSML". Quando o `inputKind` é definido como `"PlainText"`, você também precisa definir a propriedade de voz `synthesisConfig`. 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 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 lotes (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 é 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.

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

Compartilhar via