Batch synthesis API para texto a voz

  • Artículo

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.

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 es asincrónica y no devuelve audio sintetizado en tiempo real. Los archivos de texto se envían para sintetizarse, sondean el estado y descargan la salida de audio cuando el estado indica que se ha producido correctamente. Las entradas de texto deben ser texto sin formato o texto en el Lenguaje de marcado de síntesis de voz (SSML).

El diagrama a continuación proporciona una introducción general del flujo de trabajo.

Diagrama del flujo de trabajo de Batch synthesis API.

Sugerencia

También puede usar el SDK de Voz para crear audio sintetizado de más de 10 minutos si itera el texto y lo sintetiza en fragmentos. Para obtener un ejemplo de C#, consulte GitHub.

Puede usar las siguientes operaciones de la API REST para la síntesis por lotes:

Operación Método Llamada a API REST
Creación de síntesis por lotes PUT texttospeech/batchsyntheses/YourSynthesisId
Obtención de síntesis por lotes GET texttospeech/batchsyntheses/YourSynthesisId
Enumeración de síntesis por lotes GET texttospeech/batchsyntheses
Eliminación de síntesis por lotes DELETE texttospeech/batchsyntheses/YourSynthesisId

Para obtener ejemplos de código, consulte GitHub.

Creación de síntesis por lotes

Para enviar una solicitud de síntesis por lotes, construya la ruta de acceso y el cuerpo de la solicitud HTTP PUT según las instrucciones siguientes:

  • Establezca la propiedad inputKind requerida.
  • Si la propiedad inputKind está establecida en "PlainText", debe establecer también la propiedad voice en synthesisConfig. En el ejemplo siguiente, inputKind está establecido en "SSML", de modo que no se ha establecido synthesisConfig.
  • Opcionalmente, puede establecer description, timeToLiveInHoursy 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 2 megabytes.

Establezca el YourSynthesisId obligatoria en la ruta de acceso. El YourSynthesisId debe ser único. Debe ser de 3 a 64 largos, solo contiene números, letras, guiones, guiones y puntos, comienza y termina con una letra o un número.

Realice una solicitud HTTP PUT con el URI, tal y como 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 '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

Debe recibir un cuerpo de respuesta en el formato siguiente:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

La propiedad status debe evolucionar del estado NotStarted a Running y, por último, a Succeeded o Failed. Puede llamar a la API de obtención de síntesis por lotes periódicamente hasta que el estado devuelto sea Succeeded o Failed.

Obtención de síntesis por lotes

Para obtener el estado del trabajo de síntesis por lotes, realice una solicitud HTTP GET mediante el URI, como se muestra en el ejemplo siguiente. Reemplace YourSpeechKey por la clave de recurso de Voz y YourSpeechRegion por la región del recurso de Voz.

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

Debe recibir un cuerpo de respuesta en el formato siguiente:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

En outputs.result puede descargar un archivo ZIP que contiene el audio (como 0001.wav), un resumen y los detalles de depuración. Para obtener más información, 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 maxpagesize (hasta 100) 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/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Debe recibir un cuerpo de respuesta en el formato siguiente:

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

En outputs.result puede descargar un archivo ZIP que contiene el audio (como 0001.wav), un resumen y los detalles de 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.

Eliminación de síntesis por lotes

Elimine el historial de trabajos de síntesis por lotes después de recuperar los resultados de la salida de audio. El servicio de Voz conserva el historial de síntesis por lotes un máximo de 31 días o mientras dure la propiedad timeToLiveInHours de la solicitud, lo que ocurra antes. 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.

Para eliminar un trabajo de síntesis por lotes, realice una solicitud HTTP DELETE mediante el URI, como se muestra en el ejemplo siguiente. Reemplace YourSynthesisId por el identificador 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/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-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.

Resultados de la síntesis por lotes

Después de obtener un trabajo de síntesis por lotes con un valor de status "Succeeded", puede descargar los resultados de la salida de audio. 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" > results.zip

Los resultados se encuentran en un archivo ZIP que contiene el audio (como 0001.wav), un resumen y los detalles de depuración. El prefijo numerado de cada nombre de archivo (que se muestra a continuación como [nnnn]) está en el mismo orden que las entradas de texto que se usaron al crear la síntesis por lotes.

Nota

El archivo [nnnn].debug.json contiene el identificador del resultado de la síntesis y otra información que podría ayudar a solucionar problemas. Las propiedades que contiene pueden cambiar, por lo que no debe tomar dependencias del formato 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": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

Si se solicitaron datos del límite de las oraciones ("sentenceBoundaryEnabled": true), se incluye un archivo [nnnn].sentence.json correspondiente en los resultados. Del mismo modo, si se solicitaron datos del límite de las palabras ("wordBoundaryEnabled": true), se incluye un archivo [nnnn].word.json correspondiente en los resultados.

Este es un ejemplo de un archivo de datos de palabras con el desplazamiento de audio y la duración en milisegundos:

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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 PUT) 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.
  • Ha intentado crear un trabajo de batch synthesis que superaría el límite de 300 trabajos activos. Cada recurso de Voz puede contener hasta 300 trabajos de batch synthesis que no tienen el estado "Succeeded" o "Failed".

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