API REST de fala para texto para áudio curto

Os casos de uso da API REST de fala para texto para áudio curto são limitados. Use-o somente nos casos em que você não pode usar o SDK de fala.

Antes de usar a API REST de fala para texto para áudio curto, considere as seguintes limitações:

• As solicitações que usam a API REST para áudio curto e transmitem áudio diretamente não podem conter mais de 60 segundos de áudio. Os formatos de entrada de áudio são mais limitados em comparação com o Speech SDK.
• A API REST para áudio curto retorna apenas os resultados finais. Não fornece resultados parciais.
• A tradução de voz não é suportada através da API REST para áudio curto. Você precisa usar o SDK de fala.
• A transcrição em lote e a fala personalizada não são suportadas pela API REST para áudio curto. Você deve sempre usar a API REST de fala para texto para transcrição em lote e fala personalizada.

Antes de usar a API REST de fala para texto para áudio curto, entenda que você precisa concluir uma troca de token como parte da autenticação para acessar o serviço. Para obter mais informações, veja Autenticação.

Regiões e parâmetros de avaliação

O ponto de extremidade para a API REST para áudio curto tem este formato:

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

Substitua <REGION_IDENTIFIER> pelo identificador que corresponde à região do recurso de fala.

Formatos de áudio

O áudio é enviado no corpo da solicitação HTTP POST . Deve estar em um dos formatos desta tabela:

Cabeçalhos do pedido

Esta tabela lista cabeçalhos obrigatórios e opcionais para solicitações de fala para texto:

Parâmetros de consultas

Esses parâmetros podem ser incluídos na cadeia de caracteres de consulta da solicitação REST.

Parâmetros de avaliação da pronúncia

Esta tabela lista os parâmetros obrigatórios e opcionais para a avaliação da pronúncia:

Aqui está um exemplo de JSON que contém os parâmetros de avaliação de pronúncia:

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

O código de exemplo a seguir mostra como criar os parâmetros de avaliação de pronúncia no Pronunciation-Assessment cabeçalho:

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

Recomendamos vivamente o carregamento por streaming (transferência em partes) enquanto publica os dados de áudio, o que pode reduzir significativamente a latência. Para saber como habilitar o streaming, consulte o código de exemplo em várias linguagens de programação.

Pedido de amostra

O exemplo a seguir inclui o nome do host e os cabeçalhos necessários. É importante notar que o serviço também espera dados de áudio, que não estão incluídos neste exemplo. Como mencionado anteriormente, o chunking é recomendado, mas não obrigatório.

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 a avaliação de pronúncia, você pode adicionar o seguinte cabeçalho. Para saber como criar esse cabeçalho, consulte Parâmetros de avaliação de pronúncia.

Pronunciation-Assessment: eyJSZWZlcm...

Códigos de estado HTTP

O código de status HTTP para cada resposta indica sucesso ou erros comuns.

Exemplos de respostas

Aqui está uma resposta típica para simple reconhecimento:

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

Aqui está uma resposta típica para detailed reconhecimento:

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

Aqui está uma resposta típica para reconhecimento com avaliação de pronúncia:

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

Propriedades da resposta

Os resultados são fornecidos como JSON. O simple formato inclui os seguintes campos de nível superior:

O RecognitionStatus campo pode conter estes valores:

O detailed formato inclui mais formas de resultados reconhecidos. Quando você estiver usando o detailed formato, DisplayText é fornecido como Display para cada resultado na NBest lista.

O objeto na NBest lista pode incluir:

Transferência chunked

A transferência fragmentada (Transfer-Encoding: chunked) pode ajudar a reduzir a latência de reconhecimento. Ele permite que o serviço de fala comece a processar o arquivo de áudio enquanto ele é transmitido. A API REST para áudio curto não fornece resultados parciais ou provisórios.

O exemplo de código a seguir mostra como enviar áudio em partes. Somente a primeira parte deve conter o cabeçalho do arquivo de áudio. request é um HttpWebRequest objeto conectado ao ponto de extremidade REST apropriado. audioFile é o caminho para um arquivo de áudio no 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();
    }
}

Autenticação

Cada solicitação requer um cabeçalho de autorização. Esta tabela ilustra quais cabeçalhos são suportados para cada recurso:

Quando você estiver usando o Ocp-Apim-Subscription-Key cabeçalho, somente sua chave de recurso deve ser fornecida. Por exemplo:

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

Quando estiver usando o Authorization: Bearer cabeçalho, você precisa fazer uma solicitação para o issueToken ponto de extremidade. Nessa solicitação, você troca sua chave de recurso por um token de acesso válido por 10 minutos.

Outra opção é usar a autenticação Microsoft Entra que também usa o Authorization: Bearer cabeçalho, mas com um token emitido via ID do Microsoft Entra. Consulte Usar a autenticação do Microsoft Entra.

Como obter um token de acesso

Para obter um token de acesso, você precisa fazer uma solicitação ao issueToken ponto de extremidade usando Ocp-Apim-Subscription-Key e sua chave de recurso.

O issueToken ponto de extremidade tem este formato:

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

Substitua <REGION_IDENTIFIER> pelo identificador que corresponde à região da sua assinatura.

Use os exemplos a seguir para criar sua solicitação de token de acesso.

Exemplo HTTP

Este exemplo é uma solicitação HTTP simples para obter um token. Substitua YOUR_SUBSCRIPTION_KEY pela chave de recurso do serviço de Fala. Se a sua subscrição não estiver na região Oeste dos EUA, substitua o Host cabeçalho pelo nome de anfitrião da sua região.

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

O corpo da resposta contém o token de acesso no formato JSON Web Token (JWT).

Exemplo do PowerShell

Este exemplo é um script simples do PowerShell para obter um token de acesso. Substitua YOUR_SUBSCRIPTION_KEY pela chave de recurso do serviço de Fala. Certifique-se de usar o ponto de extremidade correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido como Oeste dos EUA.

$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

Exemplo de cURL

cURL é uma ferramenta de linha de comando disponível no Linux (e no Subsistema Windows para Linux). Este comando cURL ilustra como obter um token de acesso. Substitua YOUR_SUBSCRIPTION_KEY pela chave de recurso do serviço de Fala. Certifique-se de usar o ponto de extremidade correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido como Oeste dos EUA.

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"

Exemplo C#

Esta classe C# ilustra como obter um token de acesso. Passe sua chave de recurso para o serviço de Fala quando você instanciar a classe. Se a sua subscrição não estiver na região Oeste dos EUA, altere o valor de para corresponder à região da FetchTokenUri sua subscrição.

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();
        }
    }
}

Exemplo 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)

Como usar um token de acesso

O token de acesso deve ser enviado para o serviço como cabeçalho Authorization: Bearer <TOKEN> . Cada token de acesso é válido por 10 minutos. Você pode obter um novo token a qualquer momento, mas para minimizar o tráfego e a latência da rede, recomendamos usar o mesmo token por nove minutos.

Aqui está um exemplo de solicitação HTTP para a API REST de fala para texto para áudio curto:

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

Utilize a autenticação do Microsoft Entra

Para usar a autenticação do Microsoft Entra com a API REST de fala para texto para áudio curto, você precisa criar um token de acesso. As etapas para obter o token de acesso que consiste em ID de recurso e token de acesso do Microsoft Entra são as mesmas que ao usar o SDK de fala. Siga as etapas aqui Usar a autenticação do Microsoft Entra

Depois que o ID do recurso e o token de acesso do Microsoft Entra foram obtidos, o token de acesso real pode ser construído seguindo este formato:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Você precisa incluir o prefixo "aad#" e o separador "#" (hash) entre o ID do recurso e o token de acesso.

Aqui está um exemplo de solicitação HTTP para a API REST de fala para texto para áudio curto:

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 saber mais sobre os tokens de acesso do Microsoft Entra, incluindo o tempo de vida do token, visite Tokens do Access na plataforma de identidade da Microsoft.

Próximos passos

• Personalizar modelos de fala
• Familiarize-se com a transcrição em lote