Propriedades de síntese em lote para text to speech

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.

Propriedade	Descrição
`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 a sua ID de implementaçã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 "path".
`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": [{"content": "The rainbow has seven colors."}]`. Quando estiver `inputKind` definido como `"SSML"`, forneça texto na SSML (Speech Synthesis Markup Language), conforme mostrado aqui: `"inputs": [{"content": "<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": [{"content": "synthesize this to a file"},{"content": "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": [{"content": "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.
`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 resultados de síntese em batch, 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` (voz personalizada) versus `neuralCharacters` (voz padrão). 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 num contentor Azure gravável. Se não especificar um URI de contentor com token shared access signatures (SAS), o serviço de voz armazena os resultados num contentor gerido pela Microsoft. SAS com políticas de acesso armazenadas não é suportado. 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 prefixo para armazenar os resultados da síntese em lote. Se nenhum caminho de prefixo for fornecido, um caminho gerado pelo sistema será usado. Esta propriedade é opcional e só pode ser definida quando a `destinationContainerUrl` propriedade é especificada.
`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 devem ser gerados dados sobre limites de sentença. 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 conclusão do trabalho de síntese, quando os resultados da síntese serão automaticamente excluídos. Essa configuração opcional é `168` (7 dias) por padrão. O tempo máximo de vida é `744` (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`	Decide 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 estado de processamento da síntese em lote. O status deve progredir de "Em execução" para "Bem-sucedido" ou "Reprovado". 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 de 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 do áudio de fundo 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 de 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, pode-se ajustar o papel de fala. 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 modelo base de 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. Pode otimizar a voz para diferentes cenários como customer service, noticiário e assistente vocal. 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 emite a saída de áudio. Para obter informações sobre as vozes padrão disponíveis, consulte Suporte de idioma e voz. Para usar uma voz personalizada, deve especificar um mapeamento válido da voz personalizada e do ID de implantação na propriedade `customVoices`. 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 propriedade `inputs` deverá ser texto simples ou SSML. Os possíveis valores que não diferenciam maiúsculas de minúsculas são "PlainText" e "SSML". Quando o `inputKind` é definido como `"PlainText"`, deve também 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 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 o pedido para criar uma síntese por lote (via HTTP POST) foi bem-sucedido.

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ê apagou com sucesso uma tarefa 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. Certifique-se de que o recurso de Voz tem acesso à voz personalizada e que a voz personalizada é implementada com sucesso. Você também deve garantir que o mapeamento de {"your-custom-voice-name": "your-deployment-ID"} está correto no seu pedido de síntese em lote.
Você tentou usar um recurso de Fala F0, mas a região apenas suporta o nível 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."
  }
}

Próximos passos

Comentários

Esta página foi útil?

Last updated on 2026-02-25