Partilhar via


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.

Nota

Para o Azure Government e o Microsoft Azure operados por pontos de extremidade 21Vianet, consulte este artigo sobre nuvens soberanas.

Formatos de áudio

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

Formato Codec Taxa de bits Taxa de amostragem
WAV PCM 256 kbps 16 kHz, mono
OGG OPUS 256 kbps 16 kHz, mono

Nota

Os formatos anteriores são suportados através da API REST para áudio curto e WebSocket no serviço de Voz. O Speech SDK suporta o formato WAV com codec PCM, bem como outros formatos.

Cabeçalhos do pedido

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

Cabeçalho Description Obrigatório ou opcional
Ocp-Apim-Subscription-Key A sua chave de recurso para o serviço de Voz. Este cabeçalho ou Authorization é obrigatório.
Authorization Um token de autorização precedido pela palavra Bearer. Para obter mais informações, veja Autenticação. Este cabeçalho ou Ocp-Apim-Subscription-Key é obrigatório.
Pronunciation-Assessment Especifica os parâmetros para mostrar pontuações de pronúncia nos resultados de reconhecimento. Esses escores avaliam a qualidade da pronúncia da entrada de fala, com indicadores como precisão, fluência e completude.

Este parâmetro é um JSON codificado em Base64 que contém vários parâmetros detalhados. Para saber como criar esse cabeçalho, consulte Parâmetros de avaliação de pronúncia.
Opcional
Content-type Descreve o formato e o codec dos dados de áudio fornecidos. Os valores aceites são audio/wav; codecs=audio/pcm; samplerate=16000 e audio/ogg; codecs=opus. Necessá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 você estiver usando a transferência em partes, envie Expect: 100-continue. O serviço de Fala reconhece o pedido inicial e aguarda mais dados. Necessário se você estiver enviando dados de áudio em partes.
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 incluir Acceptsempre. Opcional, mas recomendado.

Parâmetros de consultas

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

Nota

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

Parâmetro Description Obrigatório ou opcional
language Identifica a língua falada que está sendo reconhecida. Consulte Idiomas suportados. Necessário
format Especifica o formato do resultado. Os valores aceites 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 predefinição é simple. Opcional
profanity Especifica como lidar com palavrões em resultados de reconhecimento. Os valores aceites são:

masked, que substitui palavrões por asteriscos.
removed, que retira todos os palavrões do resultado.
raw, o que inclui palavrões no resultado.

A predefinição é masked.
Opcional
cid Ao usar o Speech Studio para criar modelos personalizados, você pode aproveitar o valor do ID do ponto de extremidade na página Implantação . Use o valor Endpoint ID como argumento para o parâmetro de cadeia de caracteres de cid consulta. Opcional

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:

Parâmetro Description Obrigatório ou opcional
ReferenceText O texto contra o qual a pronúncia é avaliada. Necessário
GradingSystem O sistema de pontos para calibração da pontuação. O FivePoint sistema dá uma pontuação de 0-5 pontos flutuantes, e HundredMark dá uma pontuação de 0-100 pontos flutuantes. Padrão: FivePoint. Opcional
Granularity A granularidade da avaliação. Os valores aceites são:

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

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

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

Para ver definições de diferentes dimensões de pontuação e tipos de erro de palavras, consulte Propriedades de resposta. A predefinição é Basic.
Opcional
EnableMiscue Permite o cálculo incorreto. Com este parâmetro ativado, as palavras pronunciadas são comparadas com o texto de referência. Eles são marcados com omissão ou inserção com base na comparação. Os valores aceites são False e True. A predefinição é False. Opcional
ScenarioId Um GUID que indica um sistema de pontos personalizado. Opcional

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.

Nota

Para obter mais informações, consulte Avaliação de pronúncia.

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.

Código de estado de HTTP Description Motivos possíveis
100 Continuar O pedido inicial é aceite. Prossiga com o envio do restante dos dados. (Este código é usado com transferência em partes.)
200 OK O pedido foi bem-sucedido. O corpo da resposta é um objeto JSON.
400 Solicitação inválida O código do idioma não foi fornecido, o idioma não é suportado ou o arquivo de áudio é inválido (por exemplo).
401 Não autorizado 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 token de autorização está faltando.

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:

Property Description
RecognitionStatus Status, como Success para reconhecimento bem-sucedido. Veja a tabela seguinte.
DisplayText O texto reconhecido após maiúsculas, pontuação, normalização de texto inverso e mascaramento de palavrões. Presente apenas no sucesso. A normalização do texto inverso é a conversão do texto falado para formas mais curtas, como 200 para "duzentos" ou "Dr. Smith" para "doutor ferreiro".
Offset O tempo (em unidades de 100 nanossegundos) em que 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 RecognitionStatus campo pode conter estes valores:

Status Description
Success O reconhecimento foi bem-sucedido, e o DisplayText campo está presente.
NoMatch A fala foi detetada no fluxo de áudio, mas nenhuma palavra do idioma de destino foi correspondida. 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 expirou enquanto aguardava a fala.
BabbleTimeout O início do fluxo de áudio continha apenas ruído, e o serviço atingiu o tempo limite enquanto aguardava a fala.
Error O serviço de reconhecimento encontrou um erro interno e não pôde continuar. Tente novamente, se possível.

Nota

Se o áudio consistir apenas em palavrões e o profanity parâmetro de consulta 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ê estiver usando o detailed formato, DisplayText é fornecido como Display para cada resultado na NBest lista.

O objeto na NBest lista pode incluir:

Property Description
Confidence A pontuação de confiança da entrada, de 0,0 (sem confiança) a 1,0 (confiança total).
Lexical A forma lexical do texto reconhecido: as palavras reais reconhecidas.
ITN A forma normalizada de texto inverso (ITN) ou canônica do texto reconhecido, com números de telefone, números, abreviaturas ("doctor smith" para "dr smith") e outras transformações aplicadas.
MaskedITN O formulário ITN com mascaramento de palavrões aplicado, se solicitado.
Display A forma de exibição do texto reconhecido, com pontuação e maiúsculas adicionadas. Este parâmetro é o mesmo que DisplayText fornece quando o formato é definido como simple.
AccuracyScore Precisão da pronúncia da fala. A precisão indica quão próximos os fonemas correspondem à pronúncia de um falante nativo. A pontuação de precisão nos níveis de palavra e texto completo é agregada a partir da pontuação de precisão no nível de fonema.
FluencyScore Fluência da fala fornecida. A fluência indica o quão próximo o discurso corresponde ao uso de intervalos silenciosos entre palavras por um falante nativo.
CompletenessScore Completude da fala, determinada pelo cálculo da proporção de palavras pronunciadas para entrada de texto de referência.
PronScore Pontuação geral que indica a qualidade da pronúncia da fala fornecida. Esta pontuação é agregada de AccuracyScore, FluencyScoree CompletenessScore com peso.
ErrorType Valor que indica se uma palavra é omitida, inserida ou mal pronunciada, em comparação com ReferenceText. Os valores possíveis são (significando que não há None erro nesta palavra), Omission, Insertion, e Mispronunciation.

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:

Cabeçalho de autorização suportado Voz em texto Conversão de texto em voz
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'

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

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

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