Uso de la síntesis por lotes para el avatar de texto a voz
La API de síntesis por lotes para el avatar de texto a voz permite la síntesis asincrónica de texto en un avatar de conversación como un archivo de vídeo. Los publicadores y las plataformas de contenido de vídeo pueden usar esta API para crear contenido de vídeo de avatar en un lote. Ese enfoque puede ser adecuado para varios casos de uso, como materiales de entrenamiento, presentaciones o anuncios.
El vídeo del avatar sintético se generará de forma asincrónica después de que el sistema reciba la entrada de texto. La salida de vídeo generada se puede descargar en el modo de síntesis por lotes. Envíe texto para síntesis, sondee el estado de la síntesis y descargue la salida del vídeo cuando el estado indique que se ha realizado correctamente. Los formatos de las entradas de texto deben ser texto sin formato o texto en Lenguaje de marcado de síntesis de voz (SSML).
El diagrama a continuación proporciona una introducción general del flujo de trabajo.
Puede usar las siguientes operaciones de la API de REST para la síntesis por lotes.
| Operación | Método | Llamada a API REST |
|---|---|---|
| Creación de síntesis por lotes | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| Obtención de síntesis por lotes | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| Enumeración de síntesis por lotes | GET | avatar/batchsyntheses/?api-version=2024-08-01 |
| Eliminación de síntesis por lotes | Delete | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
Puede consultar los ejemplos de código en GitHub.
Creación de una solicitud de síntesis por lotes
Algunas propiedades en formato JSON son necesarias cuando se crea un nuevo trabajo de síntesis por lotes. Las demás propiedades son opcionales. La respuesta de síntesis por lotes incluye otras propiedades para proporcionar información sobre el estado y los resultados de la síntesis. Por ejemplo, la propiedad outputs.result contiene la ubicación de , donde puede descargar un archivo de vídeo que contiene el vídeo del avatar. Desde outputs.summary, puede acceder a los detalles de resumen y depuración.
Para enviar una solicitud de síntesis por lotes, construya el cuerpo de la solicitud HTTP POST según las instrucciones siguientes:
- Establezca la propiedad
inputKindrequerida. - Si la propiedad
inputKindestá establecida enPlainText, también debe establecer la propiedadvoiceen elsynthesisConfig. En el ejemplo siguiente,inputKindestá establecido enSSML, de modo que no se ha establecidospeechSynthesis. - Establezca la propiedad
SynthesisIdrequerida. Elija unSynthesisIdúnico para el mismo recurso de voz. ElSynthesisIdpuede ser una cadena de 3 a 64 caracteres, incluidas letras, números, "-" o "_", con la condición de que debe comenzar y terminar con una letra o un número. - Establezca las propiedades
talkingAvatarCharacterytalkingAvatarStylenecesarias. Aquí puede encontrar los caracteres y estilos de avatar admitidos. - Opcionalmente, puede establecer
videoFormat,backgroundColory otras propiedades. Para obtener más información, consulte Propiedades de la síntesis por lotes.
Nota:
El tamaño máximo de carga JSON que se aceptará es de 500 kilobytes.
Cada recurso de Voz puede tener hasta 200 trabajos de síntesis por lotes ejecutándose simultáneamente.
La longitud máxima del vídeo de salida es actualmente de 20 minutos, con posibles aumentos en el futuro.
Para realizar una solicitud HTTP PUT, use el formato URI que se muestra en el ejemplo siguiente. Reemplace YourSpeechKey por la clave de recurso de Voz, YourSpeechRegion por la región del recurso de Voz y establezca las propiedades del cuerpo de la solicitud como se ha descrito anteriormente.
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"
Debe recibir un cuerpo de respuesta en el formato siguiente:
{
"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
}
}
La propiedad status debe evolucionar del estado NotStarted a Running y, por último, a Succeeded o Failed. Puede llamar a la API de síntesis por lotes GET periódicamente hasta que el estado devuelto sea Succeeded o Failed.
Obtención de síntesis por lotes
Para obtener el estado de un trabajo de síntesis por lotes, realice una solicitud HTTP GET mediante el URI, como se muestra en el ejemplo siguiente.
Reemplace YourSynthesisId por el id. de la síntesis por lotes, YourSpeechKey por la clave del recurso de Voz y YourSpeechRegion por la región del recurso de Voz.
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Debe recibir un cuerpo de respuesta en el formato siguiente:
{
"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"
}
}
Desde el campo outputs.result puede descargar un archivo de vídeo que contiene el vídeo del avatar. El campo outputs.summary permite descargar los detalles de resumen y depuración. Para más información sobre los resultados de la síntesis por lotes, consulte resultados de la síntesis por lotes.
Enumeración de síntesis por lotes
Para enumerar todos los trabajos de síntesis por lotes para el recurso de Voz, realice una solicitud HTTP GET mediante el URI, como se muestra en el ejemplo siguiente.
Reemplace YourSpeechKey por la clave del recurso de Voz y YourSpeechRegion por la región del recurso de Voz. Opcionalmente, puede establecer los parámetros de consulta skip y top (tamaño de página) en la dirección URL. El valor predeterminado de skip es 0 y el valor predeterminado de maxpagesize es 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"
Debe recibir un cuerpo de respuesta en el formato siguiente:
{
"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"
}
Desde outputs.result, puede descargar un archivo de vídeo que contiene el vídeo de avatar. Desde outputs.summary, puede acceder a los detalles de resumen y depuración. Para obtener más información, consulte Resultados de la síntesis por lotes.
La propiedad value de la respuesta JSON enumera las solicitudes de síntesis. La lista está paginada, con un tamaño de página máximo de 100. La propiedad nextLink se proporciona según sea necesario para obtener la página siguiente de la lista paginada.
Obtención del archivo de resultados de síntesis por lotes
Después de obtener un trabajo de síntesis por lotes con un status de "Correcto", puede descargar los resultados de la salida de vídeo. Use la dirección URL de la propiedad outputs.result de la respuesta de obtención de síntesis por lotes.
Para obtener el archivo de resultados de la síntesis por lotes, realice una solicitud HTTP GET mediante el URI, como se muestra en el ejemplo siguiente. Reemplace YourOutputsResultUrl por la dirección URL de la propiedad outputs.result de la respuesta de obtención de síntesis por lotes. Reemplace YourSpeechKey por su clave de recurso de Voz.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > output.mp4
Para obtener el archivo de resumen de la síntesis por lotes, realice una solicitud HTTP GET mediante el URI, como se muestra en el ejemplo siguiente. Reemplace YourOutputsResultUrl por la dirección URL de la propiedad outputs.summary de la respuesta de obtención de síntesis por lotes. Reemplace YourSpeechKey por su clave de recurso de Voz.
curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json
El archivo de resumen contiene los resultados de la síntesis de cada entrada de texto. Este es un archivo summary.json de ejemplo:
{
"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"
}
]
}
Eliminación de síntesis por lotes
Después de recuperar los resultados de salida de audio y no necesitar más el historial de trabajos de síntesis por lotes, puede eliminarlos. El servicio de Voz conserva cada historial de síntesis durante un máximo de 31 días o la duración especificada por la propiedad timeToLiveInHours de la solicitud, lo que ocurra antes. La fecha y hora de eliminación automática para los trabajos de síntesis con el estado "Correcto" o "Error" se calcula como la suma de las propiedades lastActionDateTime y timeToLive.
Para eliminar un trabajo de síntesis por lotes, realice una solicitud HTTP DELETE con el siguiente formato de URI. Reemplace YourSynthesisId por el id. de la síntesis por lotes, YourSpeechKey por la clave del recurso de Voz y YourSpeechRegion por la región del recurso de Voz.
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Los encabezados de respuesta incluyen HTTP/1.1 204 No Content si la solicitud de eliminación se realizó correctamente.