API REST de conversión de voz en texto para audios de corta duración

Artículo
01/21/2024

Los casos de uso de la API REST de conversión de voz en texto para audios de corta duración son limitados. Úsese solo en los casos en los que no se pueda usar el SDK de Voz.

Antes de usar la API REST de conversión de voz en texto para audios de corta duración, tenga en cuenta las siguientes limitaciones:

Las solicitudes que usan la API de REST para audios breves y transmiten audio directamente, pueden contener hasta 60 segundos de audio. Los formatos de audio de entrada son más limitados en comparación con el SDK de Voz.
La API de REST para audios breves devuelve solo los resultados finales. No proporciona resultados parciales.
La traducción de voz no se admite a través de la API REST para audio corto. Debe usar el SDK de Voz.
La transcripción por lotes y la voz personalizada no se admiten a través de la API REST para audio corto. Siempre debe usar speech to text REST API para la transcripción por lotes y la voz personalizada.

Antes de usar la API REST de conversión de voz en texto para audios de corta duración, debe completar un intercambio de tokens como parte de la autenticación a fin de acceder al servicio. Para más información, consulte Autenticación.

Regiones y puntos de conexión

El punto de conexión de la API de REST para audios breves tiene este formato:

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Reemplace <REGION_IDENTIFIER> por el identificador que coincide con la región del recurso de Voz.

Nota:

Para los puntos de conexión de Azure Government y Microsoft Azure operado por 21Vianet, consulte este artículo sobre las nubes soberanas.

Formatos de audio

El audio se envía en el cuerpo de la solicitud HTTP POST. Debe estar en uno de los formatos de esta tabla:

Formato	Códec	Velocidad de bits	Frecuencia de muestreo
WAV	PCM	256 kbps	16 kHz, mono
OGG	OPUS	256 kbps	16 kHz, mono

Nota

Se admiten los formatos anteriores a través de la API de REST para audios breves y WebSocket en el servicio de voz. El SDK de Voz admite el formato WAV con el códec PCM así como otros formatos.

Encabezados de solicitud

En esta tabla se enumeran los encabezados obligatorios y opcionales para las solicitudes de conversión de voz en texto:

Encabezado	Descripción	Obligatorio u opcional
`Ocp-Apim-Subscription-Key`	La clave de recurso para el servicio Voz.	Se necesita este encabezado, o bien `Authorization`.
`Authorization`	Un token de autorización precedido por la palabra `Bearer`. Para más información, consulte Autenticación.	Se necesita este encabezado, o bien `Ocp-Apim-Subscription-Key`.
`Pronunciation-Assessment`	Especifica los parámetros para mostrar las puntuaciones de pronunciación en los resultados del reconocimiento. Estas puntuaciones evalúan la calidad de pronunciación de la entrada de voz, con indicadores como la precisión, la fluidez y la integridad. Este parámetro es un JSON codificado en Base64 que contiene varios parámetros detallados. Para saber cómo crear este encabezado, consulte el apartado Parámetros de evaluación de pronunciación.	Opcional
`Content-type`	Describe el formato y el códec de los datos de audio proporcionados. Los valores aceptados son: `audio/wav; codecs=audio/pcm; samplerate=16000` y `audio/ogg; codecs=opus`.	Obligatorio
`Transfer-Encoding`	Especifica que se están enviando datos de audio fragmentados en lugar de un único archivo. Use este encabezado solo si está fragmentando datos de audio.	Opcionales
`Expect`	Si usa la transferencia fragmentada, envíe `Expect: 100-continue`. El servicio voz confirma la solicitud inicial y espera más datos.	Obligatorio si se envían datos de audio fragmentados.
`Accept`	Si se proporciona, debe ser `application/json`. El servicio de voz proporciona resultados en JSON. Algunos marcos de solicitud proporcionan un valor predeterminado no compatible. Se recomienda incluir siempre `Accept`.	Opcional pero recomendable.

Parámetros de consulta

Estos parámetros podrían incluirse en la cadena de consulta de la solicitud de REST:

Nota

El parámetro de idioma debe anexarse a la dirección URL para evitar la recepción de errores HTTP 4xx. Por ejemplo, el idioma establecido en inglés de Estados Unidos con el punto de conexión del Oeste de EE. UU. es: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parámetro	Descripción	Obligatorio u opcional
`language`	Identifica el idioma hablado que se está reconociendo. Vea Idiomas admitidos.	Obligatorio
`format`	Especifica el formato del resultado. Los valores aceptados son: `simple` y `detailed`. Los resultados simples incluyen `RecognitionStatus`, `DisplayText`, `Offset` y `Duration`. Las respuestas detalladas incluyen cuatro representaciones diferentes del texto que se muestra. El valor predeterminado es `simple`.	Opcional
`profanity`	Especifica cómo controlar las palabras soeces en los resultados del reconocimiento. Los valores aceptados son: `masked`, que reemplaza las palabras soeces con asteriscos. `removed`, que quita todas las palabras soeces del resultado. `raw`, que incluye palabras soeces en el resultado. El valor predeterminado es `masked`.	Opcional
`cid`	Si usa Speech Studio para crear modelos personalizados, puede aprovechar el valor del identificador de punto de conexión de la página Implementación. Use el valor del identificador del punto de conexión como argumento del parámetro de la cadena de consulta `cid`.	Opcional

Parámetros de evaluación de pronunciación

En esta tabla se indican los parámetros obligatorios y opcionales para la evaluación de la pronunciación:

Parámetro	Descripción	Obligatorio u opcional
`ReferenceText`	Texto con el que se evalúa la pronunciación.	Obligatorio
`GradingSystem`	Sistema de puntos para la calibración de la puntuación. El sistema `FivePoint` da una puntuación de número de punto flotante entre 0 y 5, mientras que `HundredMark` da una puntuación de número de punto flotante entre 0 y 100. Predeterminado: `FivePoint`.	Opcional
`Granularity`	Granularidad de la evaluación. Los valores aceptados son: `Phoneme`, que muestra la puntuación en los niveles de texto completo, palabra y fonema. `Word`, que muestra la puntuación en los niveles de texto completo y palabra. `FullText`, que muestra la puntuación solo en el nivel de texto completo. El valor predeterminado es `Phoneme`.	Opcional
`Dimension`	Define los criterios de la salida. Los valores aceptados son: `Basic`, que muestra solo la puntuación de precisión. `Comprehensive`, que muestra puntuaciones en más dimensiones (por ejemplo, puntuación de fluidez e integridad en el nivel de texto completo y tipo de error en el nivel de palabra). Vea Propiedades de respuesta para ver las definiciones de las distintas dimensiones de puntuación y los tipos de error de palabra. El valor predeterminado es `Basic`.	Opcional
`EnableMiscue`	Habilita el cálculo de errores. Con este parámetro habilitado, las palabras pronunciadas se comparan con el texto de referencia. Se marcan con omisión o inserción en función de la comparación. Los valores aceptados son: `False` y `True`. El valor predeterminado es `False`.	Opcional
`ScenarioId`	Un GUID que indica un sistema de puntos personalizado.	Opcionales

A continuación, se muestra un JSON de ejemplo que contiene los parámetros de evaluación de pronunciación:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

En el código de ejemplo siguiente se muestra cómo compilar los parámetros de evaluación de pronunciación en el encabezado Pronunciation-Assessment:

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

Se recomienda encarecidamente la carga en streaming (transferencia fragmentada) al publicar los datos de audio, ya que puede reducir considerablemente la latencia. Consulte el código de ejemplo en varios lenguajes de programación para saber cómo habilitar el streaming.

Nota

Para obtener más información, consulte la valoración de pronunciación.

Solicitud de ejemplo

El ejemplo siguiente incluye el nombre de host y los encabezados necesarios. Es importante tener en cuenta que el servicio también espera datos de audio, que no se incluyen en este ejemplo. Como se ha mencionado anteriormente, la fragmentación es recomendable pero no obligatoria.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

Para habilitar la valoración de la pronunciación, puede agregar el encabezado siguiente. Para saber cómo crear este encabezado, consulte el apartado Parámetros de evaluación de pronunciación.

Pronunciation-Assessment: eyJSZWZlcm...

Códigos de estado HTTP

El estado HTTP de cada respuesta indica estados de corrección o error comunes.

Código de estado HTTP	Descripción	Razones posibles
100	Continue	Se acepta la solicitud inicial. Continúe con el envío del resto de los datos. (Este código se usa con transferencia fragmentada).
200	Aceptar	La solicitud fue correcta. El cuerpo de la respuesta es un objeto JSON.
400	Solicitud incorrecta	No se proporcionó el código de idioma, no se admite el idioma o el archivo de audio no es válido (por ejemplo).
401	No autorizado	Una clave de recurso o token de autorización no válido en la región especificada, o punto de conexión no válido.
403	Prohibido	Falta una clave de recurso o un token de autorización.

Respuestas de ejemplo

Esta es la respuesta típica de reconocimiento de simple:

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

Esta es la respuesta típica de reconocimiento de detailed:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

Esta es la respuesta típica de reconocimiento con evaluación de pronunciación:

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

Propiedades de respuesta

Los resultados se proporcionan como JSON. El formato simple contiene los siguientes campos de nivel superior:

Propiedad	Descripción
`RecognitionStatus`	Estado, como `Success`, para un reconocimiento correcto. Vea la tabla siguiente.
`DisplayText`	El texto reconocido después de aplicar las mayúsculas y minúsculas, los signos de puntuación, la normalización de texto inverso y el enmascaramiento de palabras soeces. Solo se presenta en caso de corrección. La normalización inversa de texto consiste en la conversión de texto hablado en formularios más cortos, como 200 para "doscientos" o "Dr.Smith" para "Doctor Smith".
`Offset`	El tiempo (en unidades de 100 nanosegundos) en el que comienza la voz reconocida en la secuencia de audio.
`Duration`	La duración (en unidades de 100 nanosegundos) de la voz reconocida en la secuencia de audio.

El campo RecognitionStatus puede contener estos valores:

Estado	Descripción
`Success`	El reconocimiento es correcto y el campo `DisplayText` está presente.
`NoMatch`	Se detectó voz en la secuencia de audio, pero no se encontraron coincidencias de palabras en el idioma de destino. Este estado suele significar que el idioma de reconocimiento es diferente del idioma en el que habla el usuario.
`InitialSilenceTimeout`	El inicio de la secuencia de audio contiene solo silencio y el servicio ha agotado el tiempo de espera de la voz.
`BabbleTimeout`	El inicio de la secuencia de audio contiene solo ruido y el servicio ha agotado el tiempo de espera de la voz.
`Error`	El servicio de reconocimiento encontró un error interno y no pudo continuar. Vuelva a intentarlo si es posible.

Nota

Si el audio consta solo de palabras soeces y el parámetro de consulta profanity está establecido en remove, el servicio no devuelve ningún resultado de voz.

El detailed formato incluye más formas de resultados reconocidos. Cuando se usa el formato detailed, se proporciona DisplayText como Display para cada resultado de la lista NBest.

El objeto de la lista NBest puede incluir:

Propiedad	Descripción
`Confidence`	La puntuación de confianza de la entrada de 0,0 (ninguna confianza) a 1,0 (plena confianza).
`Lexical`	La forma léxica del texto reconocido: palabras reales reconocidas.
`ITN`	El formato de normalización inversa de texto (ITN) o canónica del texto reconocido, con números de teléfono, números, abreviaturas ("doctor smith" a "dr smith") y otras transformaciones aplicadas.
`MaskedITN`	Formato ITN con enmascaramiento de palabras soeces aplicado, si se solicita.
`Display`	Formato de presentación del texto reconocido, con adición de signos de puntuación y mayúsculas. Este parámetro es el mismo que el que proporciona `DisplayText` cuando el formato se establece en `simple`.
`AccuracyScore`	Precisión de pronunciación de la voz. La precisión indica el grado de coincidencia de los fonemas con la pronunciación de un hablante nativo. La puntuación de precisión en los niveles de palabra y texto completo se agrega a partir de la puntuación de precisión en el nivel de fonema.
`FluencyScore`	Fluidez de la voz proporcionada. La fluidez indica el grado de coincidencia de la voz con el uso que hace un hablante nativo de los silencios entre palabras.
`CompletenessScore`	Integridad de la voz, se determina mediante el cálculo de la proporción de palabras pronunciadas para hacer referencia a la entrada de texto.
`PronScore`	Puntuación global que indica la calidad de pronunciación de la voz proporcionada. La puntuación se agrega a partir de `AccuracyScore`, `FluencyScore` y `CompletenessScore` con ponderación.
`ErrorType`	Este valor indica si se ha omitido, insertado o pronunciado incorrectamente una palabra en comparación con `ReferenceText`. Los valores posibles son `None` (que significa que no hay ningún error en esta palabra), `Omission`, `Insertion` y `Mispronunciation`.

Transferencia fragmentada

La transferencia fragmentada (Transfer-Encoding: chunked) puede ayudar a reducir la latencia de reconocimiento. Permite al servicio de voz empezar a procesar el archivo de audio mientras se transmite. La API REST para audio corto no proporciona resultados parciales o provisionales.

El siguiente ejemplo de código muestra cómo enviar audio en fragmentos. Solo el primer fragmento debe contener el encabezado del archivo de audio. request es un objeto HttpWebRequest que está conectado al punto de conexión de REST adecuado. audioFile es la ruta de acceso a un archivo de audio en disco.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 raw bytes from the input audio file.
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        requestStream.Flush();
    }
}

Authentication

Cada solicitud requiere un encabezado de autorización. Esta tabla muestra qué encabezados son compatibles con cada característica:

Encabezado de autorización compatible	Conversión de voz en texto	Texto a voz
`Ocp-Apim-Subscription-Key`	Sí	Sí
`Authorization: Bearer`	Sí	Sí

Cuando se usa el encabezado Ocp-Apim-Subscription-Key, solo se le pide que proporcione la clave de recurso. Por ejemplo:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Cuando se usa el encabezado Authorization: Bearer, se le pide que realice una solicitud al punto de conexión issueToken. En esta solicitud, va a intercambiar la clave de recurso de un token de acceso que es válido durante 10 minutos.

Obtención de un token de acceso

Para obtener un token de acceso, tiene que realizar una solicitud al punto de conexión issueToken mediante Ocp-Apim-Subscription-Key y su clave de recurso.

El punto de conexión issueToken tiene el siguiente formato:

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Reemplace <REGION_IDENTIFIER> por el identificador que coincide con la región de la suscripción.

Use los siguientes ejemplos para crear la solicitud de token de acceso.

Ejemplo de HTTP

Este ejemplo es una solicitud HTTP para obtener un token. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Si la suscripción no está en la región Oeste de EE. UU., reemplace el encabezado Host por el nombre de host de la región.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

El cuerpo de la respuesta contiene el token de acceso en formato JSON Web Token (JWT).

Ejemplo de PowerShell

En este ejemplo se muestra un script sencillo de PowerShell para obtener un token de acceso. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción. En este ejemplo la región es Oeste de EE. UU.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Ejemplo de cURL

cURL es una herramienta de la línea de comandos disponible en Linux (y en el subsistema Windows para Linux). Este comando cURL muestra cómo obtener un token de acceso. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción. En este ejemplo la región es Oeste de EE. UU.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Ejemplo de C#

Esta clase de C# muestra cómo obtener un token de acceso. Pase la clave de recurso del servicio Voz al crear una instancia de la clase. Si su suscripción no está en la región Oeste de EE. UU., cambie el valor de FetchTokenUri para que coincida con la región de su suscripción.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Ejemplo de Python

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

Uso de un token de acceso

Se debe enviar el token de acceso al servicio como encabezado Authorization: Bearer <TOKEN>. Cada token de acceso tiene una validez de 10 minutos. Puede obtener un nuevo token en cualquier momento. No obstante, para reducir el tráfico de red y la latencia, se recomienda usar el mismo token durante nueve minutos.

A continuación se muestra una solicitud HTTP de ejemplo a la API REST de conversión de voz en texto para audios de corta duración:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

API REST de conversión de voz en texto para audios de corta duración

Regiones y puntos de conexión

Formatos de audio

Encabezados de solicitud

Parámetros de consulta

Parámetros de evaluación de pronunciación

Solicitud de ejemplo

Códigos de estado HTTP

Respuestas de ejemplo

Propiedades de respuesta

Transferencia fragmentada

Authentication

Obtención de un token de acceso

Ejemplo de HTTP

Ejemplo de PowerShell

Ejemplo de cURL

Ejemplo de C#

Ejemplo de Python

Uso de un token de acceso

Pasos siguientes

Recursos adicionales