Compartir vía


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

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
Authorization: Bearer

Cuando se usa el encabezado , solo se debe proporcionar la Ocp-Apim-Subscription-Key clave de recurso. Por ejemplo:

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

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

Otra opción consiste en usar la autenticación de Microsoft Entra que también usa el Authorization: Bearer encabezado, pero con un token emitido a través de Microsoft Entra ID. Consulte Uso de la autenticación de Microsoft Entra.

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...

Uso de la autenticación de Microsoft Entra

Para usar la autenticación de Microsoft Entra con speech to text REST API para audio corto, debe crear un token de acceso. Los pasos para obtener el token de acceso que consta del identificador de recurso y el token de acceso de Microsoft Entra son los mismos que cuando se usa el SDK de Voz. Siga los pasos que se indican aquí : Uso de la autenticación de Microsoft Entra

  • Crear un recurso de voz.
  • Configurar el recurso de voz para la autenticación de Microsoft Entra
  • Obtener un token de acceso de Microsoft Entra
  • Obtención del identificador de recurso de Voz

Después de obtener el identificador de recurso y el token de acceso de Microsoft Entra, el token de acceso real se puede construir siguiendo este formato:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Debe incluir el prefijo "aad#" y el separador "#" (hash) entre el identificador de recurso y el token de acceso.

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...

Para obtener más información sobre los tokens de acceso de Microsoft Entra, incluyendo la duración del token, visite Tokens de acceso en la Plataforma de identidad de Microsoft.

Pasos siguientes