Используйте REST API для преобразования речи в текст для коротких аудиозаписей.

Используйте REST API преобразования речи в текст для короткого звука только когда вы не можете использовать SDK для распознавания речи или API быстрого транскрибирования.

Прежде чем использовать REST API преобразования речи в текст для короткого звука, рассмотрите следующие ограничения:

• Запросы, использующие REST API для короткого звука и передачи звука, могут содержать не более 60 секунд звука. Для оценки произношения продолжительность звука не должна превышать 30 секунд. Входные форматы звука являются более ограниченными по сравнению с пакетом SDK службы "Речь".
• REST API для короткого звука возвращает только окончательные результаты. Он не предоставляет частичные результаты.
• Перевод речи не поддерживается через REST API для короткого звука. Необходимо использовать Speech SDK.
• Пакетное транскрибирование и настраиваемая речь не поддерживаются через REST API для короткого звука. Для пакетного транскрибирования и пользовательской речи всегда следует использовать REST API преобразования речи в текст.

Прежде чем использовать REST API распознавания речи для коротких аудиофайлов, необходимо выполнить обмен токенами в рамках аутентификации для доступа к службе. Дополнительные сведения см. в разделе "Проверка подлинности".

Регионы и конечные точки

Конечная точка REST API для короткого звука имеет следующий формат:

https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1

Замените YourResourceName именем вашего ресурса Speech.

Форматы звука

Звук отправляется в тексте HTTP-запроса POST . Он должен находиться в одном из форматов в этой таблице:

Заголовки запросов

В этой таблице перечислены обязательные и необязательные заголовки для преобразования речи в текстовые запросы:

Параметры запроса

Эти параметры могут быть включены в строку запроса REST- запроса.

Параметры оценки произношения

В этой таблице перечислены обязательные и необязательные параметры для оценки произношения:

Ниже приведен пример JSON, содержащий параметры оценки произношения:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "Word",
  "Dimension": "Comprehensive",
  "EnableProsodyAssessment": "True"
}

В следующем примере кода показано, как создать параметры оценки произношения в заголовке Pronunciation-Assessment :

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

Настоятельно рекомендуется передавать потоковую передачу (фрагментированную передачу) во время публикации звуковых данных, что может значительно снизить задержку. См. пример кода на различных языках программирования, чтобы узнать, как включить потоковую передачу.

Пример запроса

В следующем примере содержатся имя узла и обязательные заголовки. Важно отметить, что служба также ожидает звуковые данные, которые не включены в этот пример. Как упоминалось ранее, использование чанкинга рекомендуется, но не является обязательным.

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: YourResourceName.cognitiveservices.azure.com
Transfer-Encoding: chunked
Expect: 100-continue

Чтобы включить оценку произношения, можно добавить следующий заголовок. Сведения о создании этого заголовка см. в разделе "Параметры оценки произношения".

Pronunciation-Assessment: eyJSZWZlcm...

Коды состояния HTTP

Код состояния HTTP для каждого ответа указывает на успешность или распространенные ошибки.

Примеры ответов

Ниже приведен типичный ответ на simple распознавание:

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

Ниже приведен типичный ответ на 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"
    }
  ]
}

Ниже приведен типичный ответ на распознавание с помощью оценки произношения:

{
  "RecognitionStatus": "Success",
  "Offset": 700000,
  "Duration": 8400000,
  "DisplayText": "Good morning.",
  "SNR": 38.76819,
  "NBest": [
    {
      "Confidence": 0.98503506,
      "Lexical": "good morning",
      "ITN": "good morning",
      "MaskedITN": "good morning",
      "Display": "Good morning.",
      "AccuracyScore": 100.0,
      "FluencyScore": 100.0,
      "ProsodyScore": 87.8,
      "CompletenessScore": 100.0,
      "PronScore": 95.1,
      "Words": [
        {
          "Word": "good",
          "Offset": 700000,
          "Duration": 2600000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        },
        {
          "Word": "morning",
          "Offset": 3400000,
          "Duration": 5700000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "UnexpectedBreak": {
                  "Confidence": 3.5294118e-08
                },
                "MissingBreak": {
                  "Confidence": 1.0
                },
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Свойства ответа

Результаты предоставляются в формате JSON. Формат simple включает следующие поля верхнего уровня:

Поле RecognitionStatus может содержать следующие значения:

Формат detailed содержит больше форм распознанных результатов. При использовании формата detailed, DisplayText предоставляется как Display для каждого результата в списке NBest.

Объект в списке NBest может включать:

Фрагментированные передачи

Фрагментированные передачи (Transfer-Encoding: chunked) могут помочь уменьшить задержку распознавания. Она позволяет службе "Речь" начать обработку звукового файла во время передачи. REST API для короткого звука не предоставляет частичные или промежуточные результаты.

В следующем примере кода показано, как отправлять звук в блоках. Только первый блок должен содержать заголовок звукового файла. request — это объект, подключенный HttpWebRequest к соответствующей конечной точке REST. audioFile — это путь к звуковому файлу на диске.

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

Проверки подлинности

Для каждого запроса требуется заголовок авторизации. В этой таблице показано, какие заголовки поддерживаются для каждой функции:

При использовании заголовка Ocp-Apim-Subscription-Key необходимо указать только ключ ресурса. Например:

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

Если вы используете поток токена-носителя STS с Authorization: Bearer, сначала отправьте запрос к конечной точке issueToken. В этом запросе вы обменяете ключ ресурса на токен доступа, действительный в течение 10 минут.

Другим вариантом является использование аутентификации Microsoft Entra, при которой также применяется заголовок Authorization: Bearer, но с токеном, выданным через Microsoft Entra ID. См. раздел Use Microsoft Entra authentication.

Как получить токен доступа STS

Чтобы получить токен доступа STS, выполните запрос к конечной точке issueToken, используя Ocp-Apim-Subscription-Key и ключ ресурса.

Конечная issueToken точка имеет следующий формат:

https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken

Замените YourResourceName именем вашего ресурса Speech.

Используйте следующие примеры, чтобы создать запрос токена доступа.

Пример HTTP

Этот пример — простой HTTP-запрос для получения токена. Замените YourSpeechResourceKey ключом ресурса для службы "Речь". Замените YourResourceName именем вашего ресурса Speech.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Текст ответа содержит маркер доступа в формате веб-маркера JSON (JWT).

Пример PowerShell

В этом примере используется простой скрипт PowerShell для получения токена доступа. Замените YourSpeechResourceKey ключом ресурса для службы "Речь". Замените YourResourceName именем вашего ресурса Speech.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YourSpeechResourceKey'
}

$OAuthToken = Invoke-RestMethod -Method POST `
    -Uri https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken `
    -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Пример cURL

cURL — это средство командной строки, доступное в Linux (и в подсистема Windows для Linux). Эта команда cURL иллюстрирует получение токена доступа. Замените YourSpeechResourceKey ключом ресурса для службы "Речь". Замените YourResourceName именем вашего ресурса Speech.

curl -v -X POST \
 "https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey"

Пример C#

Этот класс C# демонстрирует, как получить токен доступа. Передайте ключ ресурса для службы Speech при создании экземпляра класса. Замените YourResourceName именем вашего ресурса Speech.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://YourResourceName.cognitiveservices.azure.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();
        }
    }
}

пример 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://YourResourceName.cognitiveservices.azure.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)

Как использовать токен доступа

Маркер доступа должен быть отправлен в службу в качестве заголовка Authorization: Bearer <TOKEN> . Каждый маркер доступа действителен в течение 10 минут. Вы можете получить новый маркер в любое время, но чтобы свести к минимуму сетевой трафик и задержку, рекомендуется использовать один и тот же маркер в течение девяти минут.

Ниже приведен пример HTTP-запроса к API преобразования речи в текст REST API для короткого звука:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Используйте аутентификацию Microsoft Entra

Чтобы использовать проверку подлинности Microsoft Entra с помощью REST API преобразования речи в текст для короткого звука, необходимо создать маркер доступа. Действия по получению токена доступа, состоящего из идентификатора ресурса и токена доступа Microsoft Entra, такие же, как при использовании пакета SDK службы Speech. Выполните действия, описанные здесь Use Microsoft Entra authentication

После получения идентификатора ресурса и маркера доступа Microsoft Entra фактический маркер доступа можно создать в следующем формате:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Необходимо включить префикс "aad#" и разделитель "#" (хэш) между идентификатором ресурса и маркером доступа.

Ниже приведен пример HTTP-запроса к API преобразования речи в текст REST API для короткого звука:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Дополнительные сведения о токенах доступа Microsoft Entra, включая срок их действия, см. в разделе Токены доступа в платформе идентификации Microsoft.

Связанное содержимое

• API быстрого транскрибирования
• Настройка моделей речи
• Ознакомьтесь с пакетной транскрипцией