API REST de Conversão de fala em texto para áudio curto

Os casos de uso para a API REST de conversão de fala em texto para áudio curto são limitados. Use-os somente quando não puder usar o SDK de Fala.

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

  • As solicitações que usam a API REST para áudio curto e transmitem o áudio diretamente não podem conter mais de 60 segundos de áudio. Os formatos de áudio de entrada são mais limitados em comparação com o SDK de Fala.
  • A API REST para áudio curto retorna apenas os resultados finais. Ele não fornece resultados parciais.
  • Não há suporte para a tradução de fala por meio da API REST para áudio curto. Utilize o SDK de Fala.
  • Não há suporte para transcrição em lote e fala personalizada por meio da API REST para áudio curto. Você sempre deve usar a API REST de conversão de fala em texto para transcrição em lote e fala personalizada.

Antes de usar a API REST de conversão de fala em texto, saiba que você precisa concluir uma troca de token como parte da autenticação para acessar o serviço. Para obter mais informações, consulte Autenticação.

Regiões e endpoints

O ponto de extremidade da 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 seu recurso de Fala.

Observação

Para os pontos de extremidade do Azure Government e do Microsoft Azure operado pela 21Vianet, consulte esse artigo sobre nuvens soberanas.

Formatos de áudio

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

Formatar Codec Taxa de bits Taxa de amostragem
WAV PCM 256 Kbps 16 kHz, mono
OGG OPUS 256 Kbps 16 kHz, mono

Observação

Os formatos anteriores são compatíveis por meio da API REST para áudio curto e do WebSocket no serviço de Fala. O SDK de Fala dá suporte ao formato WAV com o codec PCM, bem como a outros formatos.

Cabeçalhos da solicitação

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

parâmetro Descrição Obrigatório ou opcional
Ocp-Apim-Subscription-Key Sua chave de recurso para o serviço de Fala. Esse cabeçalho ou Authorization é obrigatório.
Authorization Um token de autorização precedido pela palavra Bearer. Para obter mais informações, consulte Autenticação. Esse cabeçalho ou Ocp-Apim-Subscription-Key é obrigatório.
Pronunciation-Assessment Especifica os parâmetros usados para mostrar as pontuações de pronúncia nos resultados do reconhecimento. Essas pontuações avaliam a qualidade de pronúncia da entrada de fala, com indicadores como precisão, fluência e integridade.

Esse parâmetro é um JSON codificado em Base64 que contém vários parâmetros detalhados. Para saber como criar esse cabeçalho, confira Parâmetros da avaliação de pronúncia.
Opcional
Content-type Descreve o formato e o codec dos dados de áudio fornecidos. Os valores aceitos são audio/wav; codecs=audio/pcm; samplerate=16000 e audio/ogg; codecs=opus. Obrigatório
Transfer-Encoding Especifica que os dados de áudio em partes estão sendo enviados, em vez de um único arquivo. Use esse cabeçalho somente se estiver fragmentando dados de áudio. Opcional
Expect Se estiver usando uma transferência em partes, envie Expect: 100-continue. O serviço de Fala confirma a solicitação inicial e aguarda mais dados. Necessário se você estiver enviando dados de áudio em bloco.
Accept Se fornecido, deve ser application/json. O serviço de Fala fornece resultados em JSON. Algumas estruturas de solicitação fornecem um valor padrão incompatível. É uma boa prática sempre incluir Accept. Opcional, mas recomendado.

Parâmetros de consulta

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

Observação

Você precisa acrescentar o parâmetro de linguagem à URL para evitar o recebimento de um erro HTTP 4xx. Por exemplo, o idioma definido como inglês americano por meio do ponto de extremidade do Oeste dos EUA é: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parâmetro Descrição Obrigatório ou opcional
language Identifica o idioma falado que está sendo reconhecido. Confira os Idiomas compatíveis. Obrigatório
format Especifica o formato do resultado. Os valores aceitos são simple e detailed. Resultados simples incluem RecognitionStatus, DisplayText, Offset e Duration. As respostas detalhadas incluem quatro representações diferentes do texto de exibição. A configuração padrão é simple. Opcional
profanity Especifica como lidar com palavrões em resultados de reconhecimento. Os valores aceitos são:

masked, que substitui um conteúdo ofensivo por asteriscos.
removed, que remove todo o conteúdo ofensivo do resultado.
raw, que inclui o conteúdo ofensivo no resultado.

A configuração padrão é masked.
Opcional
cid Ao usar o Speech Studio para criar modelos personalizados, você pode aproveitar o valor da Endpoint IDa partir da página Implantação. Use o valor da ID do Ponto de Extremidade como o argumento para o parâmetro de cadeia de consulta cid. Opcional

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

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

Parâmetro Descrição Obrigatório ou opcional
ReferenceText O texto com relação ao qual a pronúncia será avaliada. Obrigatório
GradingSystem O sistema de pontos para calibragem da pontuação. O sistema FivePoint fornece uma pontuação de ponto flutuante de 0 a 5 e HundredMark fornece uma pontuação de ponto flutuante de 0 a 100. Padrão: FivePoint. Opcional
Granularity A granularidade da avaliação. Os valores aceitos são:

Phoneme, que mostra a pontuação nos níveis de texto completo, de palavra e de fonema.
Word, que mostra a pontuação nos níveis de texto completo e de palavra.
FullText, que mostra a pontuação somente no nível de texto completo.

A configuração padrão é Phoneme.
Opcional
Dimension Define os critérios de saída. Os valores aceitos são:

Basic, que mostra apenas a pontuação de precisão.
Comprehensive, que mostra as pontuações em mais dimensões (por exemplo, pontuação de fluência e pontuação de integridade no nível de texto completo e tipo de erro no nível de palavra).

Para ver as definições de diferentes dimensões de pontuação e os tipos de erro de palavra, confira Propriedades de resposta. A configuração padrão é Basic.
Opcional
EnableMiscue Habilita o cálculo de desvio. Com este parâmetro ativado, as palavras pronunciadas são comparadas ao texto de referência. Eles são marcados com omissão ou inserção com base na comparação. Os valores aceitos são False e True. A configuração padrão é False. Opcional
ScenarioId Um GUID que indica um sistema de ponto personalizado. Opcional

Veja o 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 seguinte código de exemplo mostra como incluir os parâmetros de avaliação de pronúncia no cabeçalho Pronunciation-Assessment:

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

Recomendamos expressamente o upload por streaming (transferência por partes) enquanto você está postando os dados de áudio, que pode reduzir significativamente a latência. Para saber como habilitar o streaming, confira o código de exemplo em várias linguagens de programação.

Observação

Para saber mais, confira Avaliação de pronúncia.

Solicitação de exemplo

O exemplo a seguir inclui o nome do host e os cabeçalhos necessários. É importante observar que o serviço também espera dados de áudio, que não estão incluídos neste exemplo. Como já mencionamos, a divisão em partes é recomendada, mas não é necessária.

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, adicione o cabeçalho a seguir. Para saber como criar esse cabeçalho, confira Parâmetros da avaliação de pronúncia.

Pronunciation-Assessment: eyJSZWZlcm...

Códigos de status HTTP

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

Código de status HTTP Descrição Possíveis motivos
100 Continuar O pedido inicial é aceito. Continue enviando o restante dos dados. (Esse código é usado com a transferência em partes.)
200 OK A solicitação foi bem-sucedida. O corpo da resposta é um objeto JSON.
400 Solicitação incorreta O código de idioma não foi fornecido, o idioma não tem suporte ou o arquivo de áudio é inválido (por exemplo).
401 Não Autorizado Há uma chave de recurso ou um token de autorização inválido na região especificada, ou um ponto de extremidade inválido.
403 Proibido Uma chave de recurso ou um token de autorização está ausente.

Respostas de exemplo

Veja uma resposta típica de reconhecimento de simple:

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

Veja uma resposta típica de reconhecimento 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"
    }
  ]
}

Veja uma resposta típica de 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 de resposta

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

Propriedade Descrição
RecognitionStatus Status, como Success para reconhecimento bem-sucedido. Confira a tabela a seguir.
DisplayText O texto reconhecido após o uso de maiúsculas, a pontuação, a normalização de texto inverso e o mascaramento de conteúdo ofensivo. Apresentar somente em caso de êxito. A normalização de texto inverso é a conversão do texto falado em formas mais curtas, como 200 para "duzentos" ou "Dr. Rodrigues" para "Doutor Rodrigues".
Offset O tempo (em unidades de 100 nanossegundos) no qual a fala reconhecida começa no fluxo de áudio.
Duration A duração (em unidades de 100 nanossegundos) da fala reconhecida no fluxo de áudio.

O campo RecognitionStatus pode conter estes valores:

Status Descrição
Success O reconhecimento foi bem-sucedido, e o campo DisplayText está presente.
NoMatch A fala foi detectada no fluxo de áudio, mas nenhuma palavra do idioma de destino foi combinada. Esse status geralmente significa que o idioma de reconhecimento é diferente do idioma que o usuário está falando.
InitialSilenceTimeout O início do fluxo de áudio continha apenas silêncio, e o serviço atingiu o tempo limite aguardando a fala.
BabbleTimeout O início do fluxo de áudio continha apenas ruído, e o serviço atingiu o tempo limite aguardando a fala.
Error O serviço de reconhecimento encontrou um erro interno e não pôde continuar. Tente novamente, se possível.

Observação

Se o áudio consistir apenas em conteúdo ofensivo e o parâmetro de consulta profanity estiver definido como remove, o serviço não retornará um resultado de fala.

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

O objeto NBest na lista pode incluir:

Propriedade Descrição
Confidence A pontuação de confiança da entrada de 0,0 (nenhuma confiança) a 1,0 (confiança total).
Lexical O formato lexical do texto reconhecido: as palavras reais reconhecidas.
ITN O ITN (texto inverso normalizado) ou a forma canônica do texto reconhecido, com números de telefone, números, abreviações ("Doutor Rodrigues" para "Dr. Rodrigues") e outras transformações aplicadas.
MaskedITN O formato ITN com mascaramento de conteúdo ofensivo aplicado se solicitado.
Display O formato de exibição do texto reconhecido, com a pontuação e uso de maiúsculas adicionados. Esse parâmetro é o mesmo fornecido pelo DisplayText quando o formato é definido como simple.
AccuracyScore Precisão da pronúncia da fala. A precisão indica o quanto os fonemas correspondem à pronúncia de um locutor nativo. A pontuação de precisão nos níveis de palavra e de texto completo é agregada com base na pontuação de precisão no nível de fonema.
FluencyScore Fluência da fala fornecida. A fluência indica o quanto a fala corresponde ao uso que um locutor nativo faria de pausas silenciosas entre as palavras.
CompletenessScore Integridade da fala, determinada pelo cálculo da proporção de palavras pronunciadas em relação à entrada de texto.
PronScore Pontuação geral que indica a qualidade da pronúncia da fala fornecida. Essa pontuação é agregada com base em AccuracyScore, FluencyScore e CompletenessScore com peso.
ErrorType Valor que indica se uma palavra é omitida, inserida ou pronunciada incorretamente, em comparação com ReferenceText. Os valores possíveis são None (ou seja, nenhum erro na palavra), Omission, Insertion e Mispronunciation.

Transferência em partes

A transferência em partes (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 o áudio em partes. Apenas o primeiro bloco deve conter o cabeçalho do arquivo de áudio. request é um objeto HttpWebRequest que está conectado ao ponto de extremidade REST apropriado. audioFile é o caminho para um arquivo de áudio em 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 precisa de um cabeçalho de autorização. Esta tabela ilustra os cabeçalhos compatíveis em cada recurso:

Cabeçalho de autorização compatível Conversão de fala em texto Texto em fala
Ocp-Apim-Subscription-Key Sim Sim
Authorization: Bearer Sim Sim

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'

Ao usar o Authorization: Bearer cabeçalho, você precisa fazer uma solicitação ao issueToken ponto de extremidade. Nesta solicitação, você troca sua chave de recurso por um token de acesso válido por dez minutos.

Outra opção é usar a autenticação do Microsoft Entra que também usa o cabeçalho, mas com um token emitido por meio da Authorization: Bearer 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 ponto de extremidade issueToken usando a Ocp-Apim-Subscription-Key e sua chave de recurso.

O ponto de extremidade issueToken apresenta o seguinte 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 de HTTP

Este exemplo é uma solicitação HTTP simples para obter um token. Substitua YOUR_SUBSCRIPTION_KEY pela sua chave de recurso para o serviço de Fala. Se sua assinatura não se encontra na região Oeste dos EUA, substitua o cabeçalho Host pelo nome de host 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 sua chave de recurso para o serviço de Fala. Certifique-se de usar o endpoint correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido para o 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 no Linux (e no Subsistema do Windows para Linux). Este comando cURL ilustra como obter um token de acesso. Substitua YOUR_SUBSCRIPTION_KEY pela sua chave de recurso para o serviço de Fala. Certifique-se de usar o endpoint correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido para o 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 de C#

Esta classe C# ilustra como obter um token de acesso. Transmita sua chave de recurso para o serviço de Fala quando você criar uma instância da classe. Se a sua assinatura não estiver na região Oeste dos EUA, altere o valor de FetchTokenUri para que corresponda à região da sua assinatura.

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 o cabeçalho Authorization: Bearer <TOKEN>. Cada token de acesso é válido por 10 minutos. É possível obter um novo token a qualquer momento, mas para minimizar o tráfego de rede e a latência, recomendamos usar o mesmo token por nove minutos.

Aqui está um exemplo de solicitação HTTP para a API REST de conversão de fala em 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...

Use 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 na ID do Recurso e no 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

  • Criar um recurso de Fala
  • Configurar o recurso de Fala para autenticação do Microsoft Entra
  • Obter um token de acesso do Microsoft Entra
  • Obter a ID do recurso de Fala

Depois que a ID do recurso e o token de acesso do Microsoft Entra forem obtidos, o token de acesso real poderá 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 a ID do recurso e o token de acesso.

Aqui está um exemplo de solicitação HTTP para a API REST de conversão de fala em 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óximas etapas