Como usar a síntese em lote para avatar de texto para fala

Artigo
09/11/2024

A API de síntese em lote para avatar de texto para fala permite a síntese assíncrona de texto em um avatar falante como um arquivo de vídeo. Editores e plataformas de conteúdo de vídeo podem utilizar essa API para criar conteúdo de vídeo avatar em um lote. Essa abordagem pode ser adequada para vários casos de uso, como materiais de treinamento, apresentações ou anúncios.

O vídeo do avatar sintético será gerado de forma assíncrona depois que o sistema receber entrada de texto. A saída de vídeo gerada pode ser baixada em síntese de modo batch. Você envia texto para síntese, pesquisa para o status de síntese e baixa a saída de vídeo quando o status indica sucesso. Os formatos de entrada de texto devem ser texto simples ou texto SSML (Speech Synthesis Markup Language).

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

Para executar a síntese em lote, você pode usar as seguintes operações da API REST.

Operação	Método	Chamada à API REST
Criar síntese em lote	PUT	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Obter síntese em lote	GET	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Listar síntese de lotes	GET	avatar/batchsyntheses/?api-version=2024-08-01
Excluir síntese em lote	DELETE	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

Você pode consultar os exemplos de código no GitHub.

Criar uma solicitação de síntese em lote

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 de onde você pode baixar um arquivo de vídeo contendo o vídeo do avatar. No , você pode acessar o resumo e os detalhes de outputs.summarydepuração.

Para enviar uma solicitação de síntese em lote, construa o corpo da solicitação HTTP POST seguindo estas instruções:

Defina a propriedade necessária inputKind .
Se a inputKind propriedade estiver definida como PlainText, você também deverá defini-la voice no synthesisConfig. No exemplo abaixo, o inputKind é definido como SSML, portanto, o speechSynthesis não está definido.
Defina a propriedade necessária SynthesisId . Escolha um exclusivo SynthesisId para o mesmo recurso de fala. Pode SynthesisId ser uma sequência de 3 a 64 caracteres, incluindo letras, números, '-' ou '_', com a condição de que deve começar e terminar com uma letra ou número.
Defina o necessário talkingAvatarCharacter e talkingAvatarStyle as propriedades. Você pode encontrar personagens e estilos de avatar suportados aqui.
Opcionalmente, você pode definir o videoFormat, backgroundColore outras propriedades. Para obter mais informações, consulte Propriedades de síntese em lote.

Nota

O tamanho máximo de carga JSON aceito é de 500 kilobytes.

Cada recurso de fala pode ter até 200 trabalhos de síntese em lote sendo executados simultaneamente.

A duração máxima para o vídeo de saída é atualmente de 20 minutos, com potenciais aumentos no futuro.

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

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML",
    "inputs": [
        {
         "content": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"
        }
    ],
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting"
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/my-job-01?api-version=2024-08-01"

Deverá receber um corpo de resposta no seguinte formato:

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "NotStarted",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:08.9487012Z",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    }
}

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

Obter síntese em lote

Para recuperar o status de um trabalho de síntese em lote, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir.

Substitua YourSynthesisId pelo ID de síntese em lote, YourSpeechKey pela chave de recurso Fala e YourSpeechRegion pela região do recurso Fala.

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

Deverá receber um corpo de resposta no seguinte formato:

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "Succeeded",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:12.5698769",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 344460,
        "durationInMilliseconds": 2520,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
            "neuralCharacters": 29,
            "talkingAvatarDurationSeconds": 2
        }
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    },
    "outputs": {
        "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
        "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
    }
}

A partir do outputs.result campo, você pode baixar um arquivo de vídeo contendo o vídeo avatar. O outputs.summary campo permite que você baixe o resumo e depurar detalhes. Para obter mais informações sobre os resultados da síntese em lote, consulte os resultados da síntese em lote.

Listar síntese de lotes

Para listar todos os trabalhos de síntese em lote para seu recurso de fala, 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 YourSpeechRegion pela sua região de recurso de Fala. Opcionalmente, você pode definir os parâmetros de consulta e top (tamanho da skip página) na URL. O valor padrão para skip é 0 e o valor padrão para maxpagesize é 100.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses?skip=0&maxpagesize=2&api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Você recebe um corpo de resposta no seguinte formato:

{
    "value": [
        {
            "id": "my-job-02",
            "internalId": "14c25fcf-3cb6-4f46-8810-ecad06d956df",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:52:23.9054709Z",
            "lastActionDateTime": "2024-03-06T07:52:29.3416944",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 502676,
                "durationInMilliseconds": 2950,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 32,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "casual-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "h264",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        },
        {
            "id": "my-job-01",
            "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:34:08.9487009Z",
            "lastActionDateTime": "2024-03-06T07:34:12.5698769",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 344460,
                "durationInMilliseconds": 2520,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 29,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "graceful-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "hevc",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        }
    ],
    "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/?api-version=2024-08-01&skip=2&maxpagesize=2"
}

A partir do , você pode baixar um arquivo de outputs.resultvídeo contendo o vídeo do avatar. No , você pode acessar o resumo e os detalhes de outputs.summarydepuração. Para obter mais informações, consulte os resultados da síntese em lote.

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

Obter arquivo de resultados de síntese em lote

Depois de obter um trabalho de síntese em lote com status "Succeeded", você pode baixar os resultados de saída de vídeo. Use a URL da outputs.result propriedade da resposta get batch synthesis .

Para obter o arquivo de resultados de síntese em lote, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir. Substitua YourOutputsResultUrl pela URL da outputs.result propriedade da resposta get batch synthesis . Substitua YourSpeechKey pela chave de recurso de fala.

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

Para obter o arquivo de resumo de síntese em lote, faça uma solicitação HTTP GET usando o URI, conforme mostrado no exemplo a seguir. Substitua YourOutputsResultUrl pela URL da outputs.summary propriedade da resposta get batch synthesis . Substitua YourSpeechKey pela chave de recurso de fala.

curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json

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

{
  "jobID": "5a25b929-1358-4e81-a036-33000e788c46",
  "status": "Succeeded",
  "results": [
    {
      "texts": [
        "<speak version='1.0' xml:lang='en-US'><voice name='en-US-AvaMultilingualNeural'>The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "videoFileName": "244a87c294b94ddeb3dbaccee8ffa7eb/5a25b929-1358-4e81-a036-33000e788c46/0001.mp4",
      "TalkingAvatarCharacter": "lisa",
      "TalkingAvatarStyle": "graceful-sitting"
    }
  ]
}

Excluir síntese em lote

Depois de recuperar os resultados da saída de áudio e não precisar mais do histórico de trabalhos de síntese em lote, você pode excluí-lo. O serviço de Fala retém cada histórico de síntese por até 31 dias ou a duração especificada pela propriedade da timeToLiveInHours solicitação, o que ocorrer primeiro. A data e a hora da exclusão automática, para trabalhos de síntese com um status de "Sucedido" ou "Reprovado" é calculada como a soma das lastActionDateTime propriedades e timeToLive .

Para excluir um trabalho de síntese em lote, faça uma solicitação HTTP DELETE usando o seguinte formato de URI. Substitua YourSynthesisId pelo ID de síntese em lote, YourSpeechKey pela chave de recurso Fala e YourSpeechRegion pela região do recurso Fala.

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-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 foi bem-sucedida.

Partilhar via

Como usar a síntese em lote para avatar de texto para fala

Criar uma solicitação de síntese em lote

Obter síntese em lote

Listar síntese de lotes

Obter arquivo de resultados de síntese em lote

Excluir síntese em lote

Próximos passos

Comentários

Recursos adicionais