Compartir a través de

Propiedades de síntesis por lotes para texto a voz

  • Artículo

Importante

Batch synthesis API está disponible con carácter general. Long Audio API se retirará el 1 de abril de 2027. Para obtener más información, consulte Migración a Batch synthesis API.

Batch synthesis API puede sintetizar de forma asincrónica un gran volumen de entrada de texto (largo y corto). Los publicadores y las plataformas de contenido de audio pueden crear contenido de audio de larga duración en un lote. Por ejemplo: audiolibros, artículos de noticias y documentos. Batch synthesis API puede crear audio sintetizado de más de 10 minutos.

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 los archivos de resultados de síntesis por lotes con salida de audio y registros.

Propiedades de la síntesis por lotes

Las propiedades de la síntesis por lotes se describen en la tabla siguiente.

Propiedad Descripción
createdDateTime Fecha y hora en que se creó el trabajo de síntesis por lotes.

Esta propiedad es de solo lectura.
customVoices Asignación de un nombre de voz personalizado y su identificador de implementación.

Por ejemplo: "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}

Puede usar el nombre de voz en synthesisConfig.voice (cuando inputKind está establecido en "PlainText") o dentro del texto SSML de inputs (cuando inputKind está establecido en "SSML").

Esta propiedad es necesaria para usar una voz personalizada. Si intenta usar una voz personalizada que no está definida aquí, el servicio devuelve un error.
description Descripción de la síntesis por lotes.

Esta propiedad es opcional.
id Identificador del trabajo de batch synthesis que ha pasado en la ruta de acceso.

Esta propiedad es obligatoria en la ruta de acceso.
inputs Texto sin formato o SSML que se va a sintetizar.

Cuando inputKind está establecido en "PlainText", proporcione texto sin formato como se muestra aquí: "inputs": [{"text": "The rainbow has seven colors."}]. Cuando inputKind está establecido en "SSML", proporcione texto en el Lenguaje de marcado de síntesis de voz (SSML) como se muestra aquí: "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>"}].

Incluya hasta 1000 objetos de texto si quiere obtener varios archivos de salida de audio. Este es un ejemplo de texto de entrada que se debe sintetizar en dos archivos de salida de audio: "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]. Por otro lado, si la propiedad properties.concatenateResult está establecida en true, cada resultado sintetizado se escribirá en el mismo archivo de salida de audio.

No necesita entradas de texto independientes para los nuevos párrafos. Dentro de cualquiera de las entradas de texto (hasta 1000), puede especificar nuevos párrafos mediante la cadena "\r\n" (nueva línea). Este es un ejemplo de texto de entrada con dos párrafos que se deben sintetizar en el mismo archivo de salida de audio: "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}].

No hay límites de párrafos, pero el tamaño máximo de carga JSON (incluidas todas las entradas de texto y otras propiedades) es de 2 megabytes.

Esta propiedad es necesaria cuando se crea un trabajo de síntesis por lotes. Esta propiedad no se incluye en la respuesta cuando se obtiene el trabajo de síntesis.
internalId Identificador del trabajo de batch synthesis interno.

Esta propiedad es de solo lectura.
lastActionDateTime Fecha y hora más recientes en que cambió el valor de la propiedad status.

Esta propiedad es de sólo lectura.
outputs.result Ubicación de los archivos de resultados de síntesis por lotes con salida de audio y registros.

Esta propiedad es de sólo lectura.
properties Conjunto definido de valores de configuración opcionales de la síntesis por lotes.
properties.sizeInBytes Tamaño de la salida de audio en bytes.

Esta propiedad es de sólo lectura.
properties.billingDetails Número de palabras procesadas y facturadas por voces customNeuralCharacters frente a neuralCharacters (predefinidas).

Esta propiedad es de sólo lectura.
properties.concatenateResult Determina si se va a concatenar el resultado. Este valor bool opcional ("true" o "false") es "false" de forma predeterminada.
properties.decompressOutputFiles Determina si se descomprimen los archivos de resultados de síntesis en el contenedor de destino. Esta propiedad solo se puede establecer cuando se establece la propiedad destinationContainerUrl. Este valor bool opcional ("true" o "false") es "false" de forma predeterminada.
properties.destinationContainerUrl Los resultados de síntesis por lotes se pueden almacenar en un contenedor de Azure que permita la escritura. Si no se especifica ningún URI de contenedor con un token de firmas de acceso compartido (SAS), el servicio de Voz almacena los resultados en un contenedor administrado por Microsoft. No se admite SAS con directivas de acceso almacenadas. Cuando se elimina el trabajo de síntesis, también se eliminan los datos del resultado.

Esta propiedad opcional no se incluye en la respuesta cuando se obtiene el trabajo de síntesis.
properties.destinationPath Ruta de acceso de prefijo donde se pueden almacenar los resultados de batch synthesis. Si no especifica una ruta de acceso de prefijo, la ruta de acceso de prefijo predeterminada es YourSpeechResourceId/YourSynthesisId.

Esta propiedad opcional solo se puede establecer cuando se establece la propiedad destinationContainerUrl.
properties.durationInMilliseconds Duración de la salida de audio en milisegundos.

Esta propiedad es de sólo lectura.
properties.failedAudioCount Error en el recuento de entradas de síntesis por lotes en la salida de audio.

Esta propiedad es de solo lectura.
properties.outputFormat Formato de la salida de audio.

Para obtener información sobre los valores aceptados, consulte los formatos de salida de audio. El formato de salida predeterminado es riff-24khz-16bit-mono-pcm.
properties.sentenceBoundaryEnabled Determina si se van a generar datos del límite de las oraciones. Este valor bool opcional ("true" o "false") es "false" de forma predeterminada.

Si se solicitan datos del límite de las oraciones, se incluirá un archivo [nnnn].sentence.json correspondiente en el archivo ZIP con los datos de los resultados.
properties.succeededAudioCount El recuento de entradas de síntesis por lotes en la salida de audio se ha realizado correctamente.

Esta propiedad es de solo lectura.
properties.timeToLiveInHours Duración en horas tras crear el trabajo de síntesis, cuando los resultados de la síntesis se eliminarán automáticamente. Esta configuración opcional es 744 (31 días) de forma predeterminada. El período de vida máximo es de 31 días. La fecha y hora de eliminación automática (para trabajos de síntesis con el estado "Succeeded" o "Failed") es igual a las propiedades lastActionDateTime + timeToLiveInHours.

Otra opción es llamar al método de eliminación de la síntesis para quitar el trabajo antes.
properties.wordBoundaryEnabled Determina si se van a generar datos del límite de las palabras. Este valor bool opcional ("true" o "false") es "false" de forma predeterminada.

Si se solicitan datos del límite de palabra, se incluirá un archivo [nnnn].word.json correspondiente en el archivo ZIP con los datos de los resultados.
status Estado de procesamiento de la síntesis por lotes.

El estado debe evolucionar de "NotStarted" a "Running" y, por último, a "Succeeded" o "Failed".

Esta propiedad es de sólo lectura.
synthesisConfig Valores de configuración que se usarán para la síntesis por lotes de texto sin formato.

Esta propiedad solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.backgroundAudio Audio de fondo para cada salida de audio.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.backgroundAudio.fadein La duración de la intensificación de entrada del audio de fondo en milisegundos. El valor predeterminado es 0, que equivale a ningún fundido de entrada. Valores aceptados: de 0 a 10000, ambos inclusive.

Para obtener información, consulte la tabla de atributos en agregar audio de fondo en la documentación del lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.backgroundAudio.fadeout Especifica la duración del fundido de salida del audio de fondo en milisegundos. El valor predeterminado es 0, que equivale a que no hay desvanecimiento. Valores aceptados: de 0 a 10000, ambos inclusive.

Para obtener información, consulte la tabla de atributos en agregar audio de fondo en la documentación del lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.backgroundAudio.src Ubicación del URI del archivo de audio en segundo plano.

Para obtener información, consulte la tabla de atributos en agregar audio de fondo en la documentación del lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad se usa cuando se establece synthesisConfig.backgroundAudio.
synthesisConfig.backgroundAudio.volume El volumen del archivo de audio de fondo. Valores aceptados: de 0 a 100, ambos inclusive. El valor predeterminado es 1.

Para obtener información, consulte la tabla de atributos en agregar audio de fondo en la documentación del lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.pitch Tono de la salida de audio.

Para obtener información sobre los valores aceptados, consulte la tabla Ajuste de la prosodia en la documentación del Lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.rate Velocidad de la salida de audio.

Para obtener información sobre los valores aceptados, consulte la tabla Ajuste de la prosodia en la documentación del Lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.role Para algunas voces, puede ajustar el juego de roles del habla. La voz puede imitar una edad y sexo diferentes, pero el nombre de la voz no cambia. Por ejemplo, una voz masculina puede subir el tono y cambiar la entonación para que parezca femenina, pero el nombre de la voz cambia. Si falta el rol o la voz no lo admite, este atributo se omite.

Para obtener información sobre los estilos disponibles para cada voz, consulte Estilos y roles de voz.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.speakerProfileId Identificador del perfil del hablante de una voz personal.

Para obtener información sobre los nombres de modelos base de voz personales disponibles, consulte integración de voz personal.
Para obtener información sobre cómo obtener el identificador del perfil de hablante, consulte compatibilidad con idiomas y voz.

Esta propiedad se usa cuando inputKind se establece en "PlainText".
synthesisConfig.style Para algunas voces, puede ajustar el estilo de habla para expresar emociones diferentes, como alegría, empatía y tranquilidad. Puede optimizar la voz para distintos escenarios, como el servicio de atención al cliente, las noticias y el asistente de voz.

Para obtener información sobre los estilos disponibles para cada voz, consulte Estilos y roles de voz.

Esta propiedad opcional solo es aplicable cuando se establece synthesisConfig.style.
synthesisConfig.styleDegree La intensidad del estilo de voz. Puede especificar un estilo más seguro o más suave para que la voz sea más expresiva o moderada. El intervalo de valores aceptados es: de 0,01 a 2 incluidos. El valor predeterminado es 1, que señala la intensidad de estilo predefinida. La unidad mínima es 0,01, cuyo resultado una ligera tendencia hacia el estilo de destino. Un valor de 2, como resultado, duplica la intensidad de estilo predeterminada. Si falta el grado de estilo o no se admite para la voz, este atributo se omite.

Para obtener información sobre los estilos disponibles para cada voz, consulte Estilos y roles de voz.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
synthesisConfig.voice Voz que emite la salida de audio.

Para obtener información sobre las voces neuronales predefinidas disponibles, consulte Compatibilidad con idiomas y voces . Para usar una voz personalizada, debe especificar una asignación válida de identificador de implementación y voz personalizada en la propiedad customVoices. Para usar una voz personal, debe especificar la propiedad synthesisConfig.speakerProfileId.

Esta propiedad se usa cuando inputKind se establece en "PlainText".
synthesisConfig.volume Volumen de la salida de audio.

Para obtener información sobre los valores aceptados, consulte la tabla Ajuste de la prosodia en la documentación del Lenguaje de marcado de síntesis de voz (SSML). Se omiten los valores no válidos.

Esta propiedad opcional solo es aplicable cuando inputKind está establecido en "PlainText".
inputKind Indica si la propiedad de texto inputs debe ser texto sin formato o SSML. Los valores posibles que no distinguen mayúsculas de minúsculas son "PlainText" y "SSML". Cuando inputKind está establecido en "PlainText", también se debe establecer la propiedad de voz synthesisConfig.

Esta propiedad es obligatoria.

Latencia y procedimientos recomendados de síntesis por lotes

Al usar la síntesis por lotes para generar voz sintetizada, es importante tener en cuenta la latencia implicada y seguir los procedimientos recomendados para lograr resultados óptimos.

Latencia en la síntesis por lotes

La latencia en la síntesis por lotes depende de varios factores, incluida la complejidad del texto de entrada, el número de entradas en el lote y las funcionalidades de procesamiento del hardware subyacente.

La latencia para la síntesis por lotes es la siguiente (aproximadamente):

  • La latencia del 50 % de las salidas de voz sintetizadas es de 10 a 20 segundos.

  • La latencia del 95 % de las salidas de voz sintetizadas es de 120 segundos.

procedimientos recomendados

Al considerar la síntesis por lotes de la aplicación, se recomienda evaluar si la latencia cumple sus requisitos. Si la latencia se alinea con el rendimiento deseado, la síntesis por lotes puede ser una opción adecuada. Sin embargo, si la latencia no satisface sus necesidades, es posible que considere la posibilidad de usar la API en tiempo real.

Códigos de estado HTTP

En esta sección se detallan los mensajes y códigos de respuesta HTTP de Batch synthesis API.

HTTP 200 OK

HTTP 200 OK indica que la solicitud se ha realizado correctamente.

HTTP 201 Created

HTTP 201 Created indica que la solicitud de creación de síntesis por lotes (a través de HTTP POST) se ha realizado correctamente.

Error HTTP 204

Un error HTTP 204 indica que la solicitud se ha realizado correctamente, pero el recurso no existe. Por ejemplo:

  • Ha intentado obtener o eliminar un trabajo de síntesis que no existe.
  • Ha eliminado correctamente un trabajo de síntesis.

Error HTTP 400

Estos son ejemplos que pueden dar lugar al error 400:

  • outputFormat es compatible o no es válido. Proporcione un valor de formato válido o deje outputFormat vacío para usar la configuración predeterminada.
  • El número de entradas de texto solicitadas ha superado el límite de 10 000.
  • Ha intentado usar un identificador de implementación no válido o una voz personalizada que no se ha implementado correctamente. Asegúrese de que el recurso de Voz tiene acceso a la voz personalizada y de que esta se ha implementado correctamente. También debe asegurarse de que la asignación de {"your-custom-voice-name": "your-deployment-ID"} es correcta en la solicitud de síntesis por lotes.
  • Ha intentado usar un recurso de Voz F0, pero la región solo admite el plan de tarifa de recursos de Voz Estándar.

Error HTTP 404

No se encuentra la entidad especificada. Asegúrese de que el id. de síntesis sea correcto.

Error HTTP 429

Hay demasiadas solicitudes recientes. Cada aplicación cliente puede enviar hasta 100 solicitudes cada diez segundos para cada recurso de Voz. Reduzca el número de solicitudes por segundo.

Error HTTP 500

El error interno del servidor HTTP 500 indica que se ha producido un error en la solicitud. El cuerpo de la respuesta contiene el mensaje de error.

Ejemplo de error HTTP

Esta es una solicitud de ejemplo que produce un error HTTP 400, ya que la propiedad inputs es necesaria para crear un trabajo.

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"

En este caso, los encabezados de respuesta incluirán HTTP/1.1 400 Bad Request.

El cuerpo de la respuesta es similar al ejemplo JSON siguiente:

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

Pasos siguientes