Speech-to-text REST APISpeech-to-text REST API

Como alternativa al SDK de Voz, el servicio de voz le permite convertir voz a texto mediante una API REST.As an alternative to the Speech SDK, the Speech service allows you to convert speech-to-text using a REST API. Cada punto de conexión accesible se asocia con una región.Each accessible endpoint is associated with a region. La aplicación requiere una clave de suscripción para el punto de conexión que se va a usar.Your application requires a subscription key for the endpoint you plan to use. La API REST es muy limitada y solo se debe usar en aquellos casos en que no pueda utilizarse Speech SDK.The REST API is very limited, and it should only be used in cases were the Speech SDK cannot.

Antes de usar la API REST de conversión de voz en texto, tenga en cuenta lo siguiente:Before using the speech-to-text REST API, consider the following:

  • Las solicitudes que usan la API REST y transmiten audio directamente solo pueden contener hasta 60 segundos de audio.Requests that use the REST API and transmit audio directly can only contain up to 60 seconds of audio.
  • La API REST de voz a texto solo devuelve resultados finales.The speech-to-text REST API only returns final results. No se proporcionan resultados parciales.Partial results are not provided.

Si el envío de un audio más grande es necesario para la aplicación, considere la posibilidad de usar el SDK de Voz o una API REST basada en archivos, como la transcripción por lotes.If sending longer audio is a requirement for your application, consider using the Speech SDK or a file-based REST API, like batch transcription.

Sugerencia

Consulte la documentación de Azure Government para conocer los puntos de conexión de la nube de administración pública (FairFax).See the Azure government documentation for government cloud (FairFax) endpoints.

AuthenticationAuthentication

Cada solicitud requiere un encabezado de autorización.Each request requires an authorization header. Esta tabla muestra qué encabezados son compatibles con cada servicio:This table illustrates which headers are supported for each service:

Encabezados de autorización compatiblesSupported authorization headers Voz a textoSpeech-to-text Texto a vozText-to-speech
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Yes NoNo
Autorización: PortadorAuthorization: Bearer Yes Yes

Cuando se usa el encabezado Ocp-Apim-Subscription-Key, solo se le pide que proporcione la clave de suscripción.When using the Ocp-Apim-Subscription-Key header, you're only required to provide your subscription key. Por ejemplo:For example:

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

Cuando se usa el encabezado Authorization: Bearer, se le pide que haga una solicitud al punto de conexión issueToken.When using the Authorization: Bearer header, you're required to make a request to the issueToken endpoint. En esta solicitud, va a intercambiar la clave de suscripción de un token de acceso que es válido durante 10 minutos.In this request, you exchange your subscription key for an access token that's valid for 10 minutes. En las secciones siguientes obtendrá información sobre cómo obtener un token y usar un token.In the next few sections you'll learn how to get a token, and use a token.

Obtención de un token de accesoHow to get an access token

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 suscripción.To get an access token, you'll need to make a request to the issueToken endpoint using the Ocp-Apim-Subscription-Key and your subscription key.

El punto de conexión issueToken tiene el siguiente formato:The issueToken endpoint has this format:

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

Reemplace <REGION_IDENTIFIER> por el identificador que coincida con la región de la suscripción en la siguiente tabla:Replace <REGION_IDENTIFIER> with the identifier matching the region of your subscription from this table:

GeographyGeography RegionRegion Identificador de regiónRegion identifier
AméricaAmericas Centro de EE. UU.Central US centralus
AméricaAmericas Este de EE. UU.East US eastus
AméricaAmericas Este de EE. UU. 2East US 2 eastus2
AméricaAmericas Centro-Norte de EE. UUNorth Central US northcentralus
AméricaAmericas Centro-sur de EE. UU.South Central US southcentralus
AméricaAmericas Centro-Oeste de EE. UU.West Central US westcentralus
AméricaAmericas Oeste de EE. UU.West US westus
AméricaAmericas Oeste de EE. UU. 2West US 2 westus2
AméricaAmericas Centro de CanadáCanada Central canadacentral
AméricaAmericas Sur de BrasilBrazil South brazilsouth
Asia PacíficoAsia Pacific Este de AsiaEast Asia eastasia
Asia PacíficoAsia Pacific Sudeste de AsiaSoutheast Asia southeastasia
Asia PacíficoAsia Pacific Este de AustraliaAustralia East australiaeast
Asia PacíficoAsia Pacific Centro de la IndiaCentral India centralindia
Asia PacíficoAsia Pacific Japón OrientalJapan East japaneast
Asia PacíficoAsia Pacific Japón OccidentalJapan West japanwest
Asia PacíficoAsia Pacific Centro de Corea del SurKorea Central koreacentral
EuropaEurope Norte de EuropaNorth Europe northeurope
EuropaEurope Oeste de EuropaWest Europe westeurope
EuropaEurope Centro de FranciaFrance Central francecentral
EuropaEurope Sur de Reino Unido 2UK South uksouth

Use estos ejemplos para crear la solicitud de token de acceso.Use these samples to create your access token request.

Ejemplo de HTTPHTTP sample

Este ejemplo es una solicitud HTTP para obtener un token.This example is a simple HTTP request to get a token. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de suscripción del servicio Voz.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. 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.If your subscription isn't in the West US region, replace the Host header with your region's host name.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: westus.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).The body of the response contains the access token in JSON Web Token (JWT) format.

Ejemplo de PowerShellPowerShell sample

En este ejemplo se muestra un script sencillo de PowerShell para obtener un token de acceso.This example is a simple PowerShell script to get an access token. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de suscripción del servicio Voz.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción.Make sure to use the correct endpoint for the region that matches your subscription. En este ejemplo la región es Oeste de EE. UU.This example is currently set to West US.

$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://westus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Ejemplo de cURLcURL sample

cURL es una herramienta de la línea de comandos disponible en Linux (y en el subsistema Windows para Linux).cURL is a command-line tool available in Linux (and in the Windows Subsystem for Linux). Este comando cURL muestra cómo obtener un token de acceso.This cURL command illustrates how to get an access token. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de suscripción del servicio Voz.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción.Make sure to use the correct endpoint for the region that matches your subscription. En este ejemplo la región es Oeste de EE. UU.This example is currently set to West US.

curl -v -X POST \
 "https://westus.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#C# sample

Esta clase de C# muestra cómo obtener un token de acceso.This C# class illustrates how to get an access token. Pase la clave de suscripción del servicio Voz al crear una instancia de la clase.Pass your Speech Service subscription key when you instantiate the class. 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.If your subscription isn't in the West US region, change the value of FetchTokenUri to match the region for your subscription.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://westus.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 PythonPython sample

# 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://westus.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 accesoHow to use an access token

Se debe enviar el token de acceso al servicio como encabezado Authorization: Bearer <TOKEN>.The access token should be sent to the service as the Authorization: Bearer <TOKEN> header. Cada token de acceso tiene una validez de 10 minutos.Each access token is valid for 10 minutes. 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.You can get a new token at any time, however, to minimize network traffic and latency, we recommend using the same token for nine minutes.

Este es un ejemplo de solicitud HTTP a la API REST de texto a voz:Here's a sample HTTP request to the text-to-speech REST API:

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

Regiones y puntos de conexiónRegions and endpoints

El punto de conexión de la API REST tiene este formato:The endpoint for the REST API has this format:

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

Reemplace <REGION_IDENTIFIER> por el identificador que coincida con la región de la suscripción en la siguiente tabla:Replace <REGION_IDENTIFIER> with the identifier matching the region of your subscription from this table:

GeographyGeography RegionRegion Identificador de regiónRegion identifier
AméricaAmericas Centro de EE. UU.Central US centralus
AméricaAmericas Este de EE. UU.East US eastus
AméricaAmericas Este de EE. UU. 2East US 2 eastus2
AméricaAmericas Centro-Norte de EE. UUNorth Central US northcentralus
AméricaAmericas Centro-sur de EE. UU.South Central US southcentralus
AméricaAmericas Centro-Oeste de EE. UU.West Central US westcentralus
AméricaAmericas Oeste de EE. UU.West US westus
AméricaAmericas Oeste de EE. UU. 2West US 2 westus2
AméricaAmericas Centro de CanadáCanada Central canadacentral
AméricaAmericas Sur de BrasilBrazil South brazilsouth
Asia PacíficoAsia Pacific Este de AsiaEast Asia eastasia
Asia PacíficoAsia Pacific Sudeste de AsiaSoutheast Asia southeastasia
Asia PacíficoAsia Pacific Este de AustraliaAustralia East australiaeast
Asia PacíficoAsia Pacific Centro de la IndiaCentral India centralindia
Asia PacíficoAsia Pacific Japón OrientalJapan East japaneast
Asia PacíficoAsia Pacific Japón OccidentalJapan West japanwest
Asia PacíficoAsia Pacific Centro de Corea del SurKorea Central koreacentral
EuropaEurope Norte de EuropaNorth Europe northeurope
EuropaEurope Oeste de EuropaWest Europe westeurope
EuropaEurope Centro de FranciaFrance Central francecentral
EuropaEurope Sur de Reino Unido 2UK South uksouth

Nota

El parámetro de idioma debe anexarse a la dirección URL para evitar la recepción de errores HTTP 4xx.The language parameter must be appended to the URL to avoid receiving an 4xx HTTP error. Por ejemplo, el idioma definido a 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.For example, the language set to US English using the West US endpoint is: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parámetros de consultaQuery parameters

Estos parámetros podrían incluirse en la cadena de consulta de la solicitud de REST.These parameters may be included in the query string of the REST request.

ParámetroParameter DescripciónDescription Obligatorio u opcionalRequired / Optional
language Identifica el idioma hablado que se está reconociendo.Identifies the spoken language that is being recognized. Vea Idiomas admitidos.See Supported languages. ObligatorioRequired
format Especifica el formato del resultado.Specifies the result format. Los valores aceptados son: simple y detailed.Accepted values are simple and detailed. Los resultados simples incluyen RecognitionStatus, DisplayText, Offset y Duration.Simple results include RecognitionStatus, DisplayText, Offset, and Duration. Las respuestas detalladas incluyen cuatro representaciones diferentes del texto que se muestra.Detailed responses include four different representations of display text. El valor predeterminado es simple.The default setting is simple. OpcionalOptional
profanity Especifica cómo controlar las palabras soeces en los resultados del reconocimiento.Specifies how to handle profanity in recognition results. Los valores aceptados son masked, que reemplaza las palabras soeces con asteriscos, removed, que quita todas las palabras soeces del resultado o raw que incluye la palabra soez en el resultado.Accepted values are masked, which replaces profanity with asterisks, removed, which removes all profanity from the result, or raw, which includes the profanity in the result. El valor predeterminado es masked.The default setting is masked. OpcionalOptional
cid Si se usa el portal del Custom Speech para crear modelos personalizados, puede usar modelos personalizados a través de su identificador de punto de conexión, que se encuentra en la página Implementación.When using the Custom Speech portal to create custom models, you can use custom models via their Endpoint ID found on the Deployment page. Use el identificador del punto de conexión como argumento del parámetro de la cadena de consulta cid.Use the Endpoint ID as the argument to the cid query string parameter. OpcionalOptional

Encabezados de solicitudRequest headers

Esta tabla enumera los encabezados obligatorios y opcionales para las solicitudes de voz a texto.This table lists required and optional headers for speech-to-text requests.

EncabezadoHeader DescripciónDescription Obligatorio u opcionalRequired / Optional
Ocp-Apim-Subscription-Key Clave de suscripción del servicio de voz.Your Speech service subscription key. Se necesita este encabezado, o bien Authorization.Either this header or Authorization is required.
Authorization Un token de autorización precedido por la palabra Bearer.An authorization token preceded by the word Bearer. Para más información, consulte Autenticación.For more information, see Authentication. Se necesita este encabezado, o bien Ocp-Apim-Subscription-Key.Either this header or Ocp-Apim-Subscription-Key is required.
Pronunciation-Assessment Especificar los parámetros para mostrar puntuaciones de pronunciación en los resultados de reconocimiento, que evalúan la calidad de la pronunciación de la entrada de voz, con indicadores de precisión, fluidez, integridad, etc. Este parámetro es un JSON codificado en Base64 que contiene varios parámetros detallados.Specifies the parameters for showing pronunciation scores in recognition results, which assess the pronunciation quality of speech input, with indicators of accuracy, fluency, completeness, etc. This parameter is a base64 encoded json containing multiple detailed parameters. Para saber cómo crear este encabezado, consulte el apartado Parámetros de evaluación de pronunciación.See Pronunciation assessment parameters for how to build this header. OpcionalOptional
Content-type Describe el formato y el códec de los datos de audio proporcionados.Describes the format and codec of the provided audio data. Los valores aceptados son: audio/wav; codecs=audio/pcm; samplerate=16000 y audio/ogg; codecs=opus.Accepted values are audio/wav; codecs=audio/pcm; samplerate=16000 and audio/ogg; codecs=opus. ObligatorioRequired
Transfer-Encoding Especifica que se están enviando datos de audio fragmentados en lugar de un único archivo.Specifies that chunked audio data is being sent, rather than a single file. Use este encabezado solo si hay fragmentación de los datos de audio.Only use this header if chunking audio data. OpcionalOptional
Expect Si usa la transferencia fragmentada, envíe Expect: 100-continue.If using chunked transfer, send Expect: 100-continue. El servicio de voz confirma la solicitud inicial y espera datos adicionales.The Speech service acknowledges the initial request and awaits additional data. Obligatorio si se envían datos de audio fragmentados.Required if sending chunked audio data.
Accept Si se proporciona, debe ser application/json.If provided, it must be application/json. El servicio de voz proporciona resultados en JSON.The Speech service provides results in JSON. Algunos marcos de solicitud proporcionan un valor predeterminado no compatible.Some request frameworks provide an incompatible default value. Se recomienda incluir siempre Accept.It is good practice to always include Accept. Opcional pero recomendable.Optional, but recommended.

Formatos de audioAudio formats

El audio se envía en el cuerpo de la solicitud HTTP POST.Audio is sent in the body of the HTTP POST request. Debe estar en uno de los formatos de esta tabla:It must be in one of the formats in this table:

FormatoFormat CódecCodec Velocidad de bitsBit rate Velocidad de muestreoSample Rate
WAVWAV PCMPCM 256 kbps256 kbps 16 kHz, mono16 kHz, mono
OGGOGG OPUSOPUS 256 kbps256 kpbs 16 kHz, mono16 kHz, mono

Nota

Se admiten los formatos anteriores a través de la API REST y WebSocket en el servicio de voz.The above formats are supported through REST API and WebSocket in the Speech service. Actualmente, el SDK de Voz admite el formato WAV con el códec PCM así como otros formatos.The Speech SDK currently supports the WAV format with PCM codec as well as other formats.

Parámetros de evaluación de pronunciaciónPronunciation assessment parameters

En esta tabla se indican los parámetros obligatorios y opcionales para la evaluación de la pronunciación.This table lists required and optional parameters for pronunciation assessment.

ParámetroParameter DescripciónDescription Obligatorio u opcionalRequired / Optional
ReferenceTextReferenceText Texto con el que se va a evaluar la pronunciación.The text that the pronunciation will be evaluated against. ObligatorioRequired
GradingSystemGradingSystem Sistema de puntos para la calibración de la puntuación.The point system for score calibration. Los valores aceptados son: FivePoint y HundredMark.Accepted values are FivePoint and HundredMark. El valor predeterminado es FivePoint.The default setting is FivePoint. OpcionalOptional
GranularidadGranularity Granularidad de la evaluación.The evaluation granularity. Los valores aceptados son Phoneme, que muestra la puntuación en el nivel de todo el texto, la palabra y el fonema, Word, que muestra la puntuación en el nivel de todo el texto y la palabra, FullText, que muestra la puntuación solo en el nivel de todo el texto.Accepted values are Phoneme, which shows the score on the full text, word and phoneme level, Word, which shows the score on the full text and word level, FullText, which shows the score on the full text level only. El valor predeterminado es Phoneme.The default setting is Phoneme. OpcionalOptional
DimensiónDimension Define los criterios de la salida.Defines the output criteria. Los valores aceptados son Basic, que solo muestra la puntuación de precisión, Comprehensive muestra puntuaciones de más dimensiones (por ejemplo, puntuación de fluidez y puntuación de integridad en el nivel de todo el texto, tipo de error en el nivel de la palabra).Accepted values are Basic, which shows the accuracy score only, Comprehensive shows scores on more dimensions (e.g. fluency score and completeness score on the full text level, error type on word level). Leer Parámetros de respuesta para ver las definiciones de las distintas dimensiones de puntuación y los tipos de error de palabra.Check Response parameters to see definitions of different score dimensions and word error types. El valor predeterminado es Basic.The default setting is Basic. OpcionalOptional
EnableMiscueEnableMiscue Habilita el cálculo de errores.Enables miscue calculation. Con esta opción habilitada, las palabras pronunciadas se comparan con el texto de referencia y se marcan con omisión/inserción en función de la comparación.With this enabled, the pronounced words will be compared to the reference text, and will be marked with omission/insertion based on the comparison. Los valores aceptados son: False y True.Accepted values are False and True. El valor predeterminado es False.The default setting is False. OpcionalOptional
ScenarioIdScenarioId GUID que indica un sistema de puntos personalizado.A GUID indicating a customized point system. OpcionalOptional

A continuación se muestra un JSON de ejemplo que contiene los parámetros de evaluación de pronunciación:Below is an example JSON containing the pronunciation assessment parameters:

{
  "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:The following sample code shows how to build the pronunciation assessment parameters into the Pronunciation-Assessment header:

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 (fragmentada) al publicar los datos de audio, ya que puede reducir considerablemente la latencia.We strongly recommend streaming (chunked) uploading while posting the audio data, which can significantly reduce the latency. Consulte el código de ejemplo en diferentes lenguajes de programación para saber cómo habilitar el streaming.See sample code in different programming languages for how to enable streaming.

Nota

La característica de valoración de la pronunciación solo está disponible actualmente en las regiones westus, eastasia y centralindia.The pronunciation assessment feature is currently only available on westus, eastasia and centralindia regions. Y actualmente esta característica solo está disponible en el idioma en-US.And this feature is currently only available on en-US language.

Solicitud de ejemploSample request

El ejemplo siguiente incluye el nombre de host y los encabezados necesarios.The sample below includes the hostname and required headers. Es importante tener en cuenta que el servicio también espera datos de audio, que no están incluidos en este ejemplo.It's important to note that the service also expects audio data, which is not included in this sample. Como se ha mencionado anteriormente, la fragmentación es recomendable pero no obligatoria.As mentioned earlier, chunking is recommended, however, not required.

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_SUBSCRIPTION_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.To enable pronunciation assessment, you can add below header. Para saber cómo crear este encabezado, consulte el apartado Parámetros de evaluación de pronunciación.See Pronunciation assessment parameters for how to build this header.

Pronunciation-Assessment: eyJSZWZlcm...

Códigos de estado HTTPHTTP status codes

El estado HTTP de cada respuesta indica estados de corrección o error comunes.The HTTP status code for each response indicates success or common errors.

Código de estado HTTPHTTP status code DescripciónDescription Posible motivoPossible reason
100 ContinuarContinue Se ha aceptado la solicitud inicial.The initial request has been accepted. Continúe con el envío del resto de los datos.Proceed with sending the rest of the data. (Se usa con la transferencia fragmentada)(Used with chunked transfer)
200 AceptarOK La solicitud es correcta; el cuerpo de la respuesta es un objeto JSON.The request was successful; the response body is a JSON object.
400 Solicitud incorrectaBad request Código de idioma no proporcionado, idioma no compatible; archivo de audio no válido, etc.Language code not provided, not a supported language, invalid audio file, etc.
401 No autorizadoUnauthorized Clave de suscripción o token de autorización no válido en la región especificada, o punto de conexión no válido.Subscription key or authorization token is invalid in the specified region, or invalid endpoint.
403 ProhibidoForbidden Falta la clave de suscripción o el token de autorización.Missing subscription key or authorization token.

Transferencia fragmentadaChunked transfer

La transferencia fragmentada (Transfer-Encoding: chunked) puede ayudar a reducir la latencia de reconocimiento.Chunked transfer (Transfer-Encoding: chunked) can help reduce recognition latency. Permite al servicio de voz empezar a procesar el archivo de audio mientras se transmite.It allows the Speech service to begin processing the audio file while it is transmitted. La API de REST no proporciona resultados parciales ni provisionales.The REST API does not provide partial or interim results.

Este ejemplo de código muestra cómo enviar audio en fragmentos.This code sample shows how to send audio in chunks. Solo el primer fragmento debe contener el encabezado del archivo de audio.Only the first chunk should contain the audio file's header. request es un objeto HttpWebRequest conectado al punto de conexión de REST adecuado.request is an HttpWebRequest object connected to the appropriate REST endpoint. audioFile es la ruta de acceso a un archivo de audio en disco.audioFile is the path to an audio file on disk.

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_SUBSCRIPTION_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1024 byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1024 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();
    }
}

Parámetros de respuestaResponse parameters

Los resultados se proporcionan como JSON.Results are provided as JSON. El formato simple incluye los siguientes campos de nivel superior.The simple format includes these top-level fields.

ParámetroParameter DescripciónDescription
RecognitionStatus Estado, como Success, para un reconocimiento correcto.Status, such as Success for successful recognition. Vea la tabla siguiente.See next table.
DisplayText Texto reconocido tras mayúsculas, puntuación, normalización inversa de texto (conversión de texto hablado en formularios más cortos, como 200 para "doscientos" o "Dr. Smith" para "doctor smith") y enmascaramiento de palabras soeces.The recognized text after capitalization, punctuation, inverse text normalization (conversion of spoken text to shorter forms, such as 200 for "two hundred" or "Dr. Smith" for "doctor smith"), and profanity masking. Solo se presenta en caso de corrección.Present only on success.
Offset El tiempo (en unidades de 100 nanosegundos) en el que comienza la voz reconocida en la secuencia de audio.The time (in 100-nanosecond units) at which the recognized speech begins in the audio stream.
Duration La duración (en unidades de 100 nanosegundos) de la voz reconocida en la secuencia de audio.The duration (in 100-nanosecond units) of the recognized speech in the audio stream.

El campo RecognitionStatus puede contener estos valores:The RecognitionStatus field may contain these values:

StatusStatus DescripciónDescription
Success El reconocimiento es correcto y el campo DisplayText está presente.The recognition was successful and the DisplayText field is present.
NoMatch Se detectó voz en la secuencia de audio, pero no se encontraron coincidencias de palabras en el idioma de destino.Speech was detected in the audio stream, but no words from the target language were matched. Normalmente significa que el idioma de reconocimiento es un idioma distinto al que habla el usuario.Usually means the recognition language is a different language from the one the user is speaking.
InitialSilenceTimeout El inicio de la secuencia de audio contiene solo silencio y el servicio ha agotado el tiempo de espera de la voz.The start of the audio stream contained only silence, and the service timed out waiting for speech.
BabbleTimeout El inicio de la secuencia de audio contiene solo ruido y el servicio ha agotado el tiempo de espera de la voz.The start of the audio stream contained only noise, and the service timed out waiting for speech.
Error El servicio de reconocimiento ha detectado un error interno y no ha podido continuar.The recognition service encountered an internal error and could not continue. Vuelva a intentarlo si es posible.Try again if possible.

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.If the audio consists only of profanity, and the profanity query parameter is set to remove, the service does not return a speech result.

El formato de detailed incluye formas adicionales de resultados reconocidos.The detailed format includes additional forms of recognized results. Cuando se usa el formato detailed, se proporciona DisplayText como Display para cada resultado de la lista NBest.When using the detailed format, DisplayText is provided as Display for each result in the NBest list.

El objeto de la lista NBest puede incluir:The object in the NBest list can include:

ParámetroParameter DescripciónDescription
Confidence La puntuación de confianza de la entrada de 0,0 (ninguna confianza) a 1,0 (plena confianza)The confidence score of the entry from 0.0 (no confidence) to 1.0 (full confidence)
Lexical La forma léxica del texto reconocido: palabras reales reconocidas.The lexical form of the recognized text: the actual words recognized.
ITN El formato de normalización inversa de texto ("canónica") del texto reconocido, con números de teléfono, números, abreviaturas ("doctor smith" a "dr smith") y otras transformaciones aplicadas.The inverse-text-normalized ("canonical") form of the recognized text, with phone numbers, numbers, abbreviations ("doctor smith" to "dr smith"), and other transformations applied.
MaskedITN Formato ITN con enmascaramiento de palabras soeces aplicado, si se solicita.The ITN form with profanity masking applied, if requested.
Display Formato de presentación del texto reconocido, con adición de signos de puntuación y mayúsculas.The display form of the recognized text, with punctuation and capitalization added. Este parámetro es el mismo que DisplayText que se proporcionó cuando el formato se estableció en simple.This parameter is the same as DisplayText provided when format is set to simple.
AccuracyScore Precisión de pronunciación de la voz.Pronunciation accuracy of the speech. La precisión indica el grado de coincidencia de los fonemas con la pronunciación de un hablante nativo.Accuracy indicates how closely the phonemes match a native speaker's pronunciation. La puntuación de precisión del nivel de texto completo y de las palabras individuales se agrega a partir de la puntuación de precisión del nivel de fonema.Word and full text level accuracy score is aggregated from phoneme level accuracy score.
FluencyScore Fluidez del fragmento hablado en cuestión.Fluency of the given speech. La fluidez indica el grado de coincidencia de la voz con el uso que hace un hablante nativo de los silencios entre palabras.Fluency indicates how closely the speech matches a native speaker's use of silent breaks between words.
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.Completeness of the speech, determined by calculating the ratio of pronounced words to reference text input.
PronScore Puntuación global que indica la calidad de la pronunciación del fragmento hablado en cuestión.Overall score indicating the pronunciation quality of the given speech. Se agrega a partir de AccuracyScore, FluencyScore y CompletenessScore con ponderación.This is aggregated from AccuracyScore, FluencyScore and CompletenessScore with weight.
ErrorType Este valor indica si se ha omitido, se ha insertado o se ha pronunciado incorrectamente una palabra en comparación con ReferenceText.This value indicates whether a word is omitted, inserted or badly pronounced, compared to ReferenceText. Los valores posibles son None (que significa que no hay ningún error en esta palabra), Omission, Insertion y Mispronunciation.Possible values are None (meaning no error on this word), Omission, Insertion and Mispronunciation.

Respuestas de ejemploSample responses

La siguiente es una respuesta típica de reconocimiento de simple:A typical response for simple recognition:

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

La siguiente es una respuesta típica de reconocimiento de detailed:A typical response for detailed recognition:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "remind me to buy five pencils",
        "ITN" : "remind me to buy 5 pencils",
        "MaskedITN" : "remind me to buy 5 pencils",
        "Display" : "Remind me to buy 5 pencils.",
      }
  ]
}

La siguiente es una respuesta típica de reconocimiento con evaluación de pronunciación:A typical response for recognition with pronunciation assessment:

{
  "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
            }
        ]
      }
  ]
}

Pasos siguientesNext steps