Преобразование речи в REST API для короткого звука

Статья
09/23/2024

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

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

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

Прежде чем использовать REST API преобразования речи в текст для короткого звука, необходимо выполнить обмен маркерами в рамках проверки подлинности для доступа к службе. Дополнительные сведения см. в разделе Authenticate to the Speech API (Аутентификация в API речи).

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

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

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

Замените <REGION_IDENTIFIER> идентификатором, который соответствует региону ресурса "Речь".

Примечание.

Сведения об Azure для государственных организаций и Microsoft Azure, управляемых конечными точками 21Vianet, см. в этой статье о национальных облаках.

Форматы аудио

Аудио отправляется в тексте HTTP-запроса POST. Аудиопоток должен иметь один из форматов, приведенных в следующей таблице:

Формат	Кодек	Скорость	Частота выборки
WAV	PCM	256 Кбит/с	16 кГц, моно
OGG	OPUS	256 Кбит/с	16 кГц, моно

Примечание.

Предыдущие форматы поддерживаются REST API для коротких звуковых файлов и WebSocket в службе "Речь". Пакет SDK для службы "Речь" поддерживает формат WAV с кодеком PCM, а также другие форматы.

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

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

Верхний колонтитул	Description	Обязательно или необязательно
`Ocp-Apim-Subscription-Key`	Ключ ресурса для службы "Речь".	Обязательный, если не предоставлен заголовок `Authorization`.
`Authorization`	Маркеру авторизации предшествует слово `Bearer`. Дополнительные сведения см. в разделе Authenticate to the Speech API (Аутентификация в API речи).	Обязательный, если не предоставлен заголовок `Ocp-Apim-Subscription-Key`.
`Pronunciation-Assessment`	Задает параметры для отображения оценок произношения в результатах распознавания. Эти оценки определяют качество произношения входных данных речи, используя такие индикаторы, как точность, беглость и полнота. Этот параметр представляет собой JSON в кодировке Base64, содержащий несколько подробных параметров. Чтобы узнать, как создать этот заголовок, см. раздел Параметры оценки произношения.	Необязательно
`Content-type`	Описывает формат и кодек предоставленных аудиоданных. Допустимые значения: `audio/wav; codecs=audio/pcm; samplerate=16000` и `audio/ogg; codecs=opus`.	Обязательное поле
`Transfer-Encoding`	Указывает, что отправляются фрагментированные аудиоданные, а не один файл. Используйте этот заголовок, только если вы разбиваете аудиоданные на блоки.	Необязательно
`Expect`	Если вы используете блочную передачу, отправьте `Expect: 100-continue`. Служба "Речь" подтверждает первоначальный запрос и ожидает больше данных.	Требуется, если вы отправляете аудиоданные блочно.
`Accept`	Если указан, этот заголовок должен иметь значение `application/json`. Служба распознавания речи предоставляет результаты в формате JSON. Некоторые платформы запросов предоставляют несовместимое значение по умолчанию. Рекомендуется всегда включать `Accept`.	Необязательный, но рекомендуется включать.

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

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

Примечание.

Следует добавить параметр языка к URL-адресу, чтобы избежать получения ошибки HTTP 4xx. Например, выбор английского языка (США) с использованием конечной точки "Западная часть США" будет выглядеть так: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Параметр	Описание	Обязательно или необязательно
`language`	Определяет распознаваемую устную речь. См. сведения о поддерживаемых языках.	Обязательное поле
`format`	Указывает формат результатов. Допустимые значения: `simple` и `detailed`. К простым результатам относятся `RecognitionStatus`, `DisplayText`, `Offset` и `Duration`. Подробные ответы включают четыре различных представления отображаемого текста. Значение по умолчанию равно `simple`.	Необязательно
`profanity`	Указывает, как обрабатывать ненормативную лексику в результатах распознавания. Допустимые значения: `masked` для замены ненормативной лексики звездочками. `removed` для удаления всей ненормативной лексики из результата. `raw` для включения ненормативной лексики в результат. Значение по умолчанию равно `masked`.	Необязательно
`cid`	Когда вы используете Speech Studio для создания пользовательских моделей, вы можете воспользоваться значением Идентификатор конечной точки на странице Развертывание. Используйте значение Идентификатор конечной точки в качестве аргумента для параметра строки запроса `cid`.	Необязательно

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

Эта таблица содержит обязательные и необязательные параметры для оценки произношения.

Параметр	Описание	Обязательно или необязательно
`ReferenceText`	Текст, на который вычисляется произношение.	Обязательное поле
`GradingSystem`	Система баллов для калибровки оценок. Система `FivePoint` ставит оценку в виде числа с плавающей запятой от 0 до 5, а `HundredMark` — оценку в виде числа с плавающей запятой от 0 до 100. По умолчанию: `FivePoint`.	Необязательно
`Granularity`	Степень детализации оценки. Допустимые значения: `Phoneme` — отображает оценку на уровне всего текста, слова и фонемы. `Word` — отображает оценку на уровне всего текста и слова. `FullText` — отображает оценку только на уровне всего текста. Значение по умолчанию равно `Phoneme`.	Необязательно
`Dimension`	Определяет условия выходных данных. Допустимые значения: `Basic` — отображает только оценку точности. `Comprehensive` — отображает оценки по большему количеству измерений (например, оценку беглости речи и оценку полноты на уровне всего текста и тип ошибки на уровне слова). Чтобы просмотреть определения различных измерений показателей и типов ошибок слова, см. статью "Свойства ответа". Значение по умолчанию равно `Basic`.	Необязательно
`EnableMiscue`	Включает вычисление оговорок. Если этот параметр включен, то выраженные слова сравниваются с ссылочным текстом. Они отмечены упущением или вставкой на основе сравнения. Допустимые значения: `False` и `True`. Значение по умолчанию равно `False`.	Необязательно
`ScenarioId`	Уникальный идентификатор, который обозначает настроенную систему баллов.	Необязательно

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

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

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

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
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: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

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

Pronunciation-Assessment: eyJSZWZlcm...

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

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

Код состояния HTTP	Description	Возможные причины
100	Продолжить	Первоначальный запрос принимается. Перейдите к отправке данных, которые остались. (Этот код используется при блочной передаче.)
200	OK	Запрос выполнен успешно. Текст ответа представляет собой объект JSON.
400	Недопустимый запрос	Код языка не указан, язык не поддерживается или звуковой файл является недопустимым (например).
401	Не авторизовано	Ключ ресурса или маркер авторизации недопустим в указанном регионе или конечная точка является недопустимой.
403	Запрещено	Отсутствует ключ ресурса или маркер авторизации.

Образцы ответов

Типичный ответ для распознавания 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": "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
            }
        ]
      }
  ]
}

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

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

Свойство	Description
`RecognitionStatus`	Состояние, например, `Success` в случае успешного распознавания. См. таблицу ниже.
`DisplayText`	Распознанный текст после расстановки заглавных букв и знаков препинания, обратной нормализации текста и маскировки ненормативной лексики. Появляется только в случае успешного распознавания. Обратная нормализация текста — это преобразование произносимого текста в более короткие формы, например "200" вместо "двести" или "д-р Шевченко" вместо "доктор Шевченко".
`Offset`	Время (в единицах 100 нс), с которого в звуковом потоке начинается распознанная речь.
`Duration`	Длительность (в единицах 100 нс) распознанной речи в звуковом потоке.

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

Состояние	Description
`Success`	Речь распознана, и присутствует поле `DisplayText`.
`NoMatch`	В аудиопотоке был обнаружена речь, но не были сопоставлены слова в целевом языке. Это состояние обычно означает, что язык распознавания отличается от языка, на котором говорит пользователь.
`InitialSilenceTimeout`	В начале аудиопотока была только тишина, а время ожидания службой речи истекло.
`BabbleTimeout`	Начало аудиопотока содержало только шум, а время ожидания службой речи истекло.
`Error`	Служба распознавания столкнулась с внутренней ошибкой и не могла продолжиться. Повторите попытку, если это возможно.

Примечание.

Если звуковой файл содержит только ненормативную лексику, а параметр запроса profanity имеет значение remove, служба не возвращает результат распознавания речи.

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

Объект в списке NBest может включать следующие параметры.

Свойство	Description
`Confidence`	Оценка достоверности записи: от 0,0 (недостоверно) до 1,0 (полная достоверность).
`Lexical`	Лексическая форма распознанного текста: конкретные распознанные слова.
`ITN`	Форма распознанного текста после обратной нормализации (каноническая форма) с номерами телефонов, числами, сокращениями ("доктор Шевченко" до "д-р Шевченко") и другими выполненными преобразованиями.
`MaskedITN`	Форма ITN с применением маскировки ненормативной лексики, если запрашивалась.
`Display`	Отображаемая форма распознанного текста с расстановкой знаков препинания и прописных букв. Этот параметр совпадает с параметром `DisplayText`, если указан формат `simple`.
`AccuracyScore`	Точность произношения речи. Правильность указывает на степень соответствия фонем произношению носителя языка. Оценка точности на уровне слова и целого текста вычисляется из оценки точности на уровне фонемы.
`FluencyScore`	Беглость предоставленной речи. Владение языком указывает на степень соответствия речи использованию пауз между словами носителем языка.
`CompletenessScore`	Полнота речи, определяемая путем вычисления соотношения произнесенных слов и эталонного входного текста.
`PronScore`	Общая оценка, указывающая на качество произношения предоставленной речи. Эта оценка вычисляется на основе оценок `AccuracyScore`, `FluencyScore` и `CompletenessScore` с учетом их веса.
`ErrorType`	Значение, указывающее, пропущено ли слово, вставлено или неверно произнесено по сравнению с `ReferenceText`. Возможные значения: `None` (означает отсутствие ошибок в этом слове), `Omission`, `Insertion` и `Mispronunciation`.

Блочная передача

Блочная передача (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`	Да	Да
`Authorization: Bearer`	Да	Да

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

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

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

Другой вариант — использовать проверку подлинности Microsoft Entra, которая также использует Authorization: Bearer заголовок, но с маркером, выданным с помощью идентификатора Microsoft Entra. См. статью "Использование проверки подлинности Microsoft Entra".

Как получить маркер доступа

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

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

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

Замените <REGION_IDENTIFIER> идентификатором, соответствующим региону подписки.

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

Пример HTTP

Это простой HTTP-запрос для получения маркера. Замените YOUR_SUBSCRIPTION_KEY ключом ресурса для службы "Речь". Если ваша подписка не находится в регионе "Западная часть США", замените заголовок Host на имя узла в вашем регионе.

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

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

Пример для PowerShell

Это простой сценарий PowerShell для получения маркера доступа. Замените YOUR_SUBSCRIPTION_KEY ключом ресурса для службы "Речь". Обязательно используйте правильную конечную точку для региона, который соответствует вашей подписке. В этом примере используется конечная точка для западной части США.

$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

Пример cURL

cURL — это программа командной строки, доступная в Linux (и в подсистеме Windows для Linux). Эта команда cURL показывает, как получить маркер доступа. Замените YOUR_SUBSCRIPTION_KEY ключом ресурса для службы "Речь". Обязательно используйте правильную конечную точку для региона, который соответствует вашей подписке. В этом примере используется конечная точка для западной части США.

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"

Пример на языке C#

Этот класс C# показывает, как получить маркер доступа. Передайте ключ ресурса для службы "Речь" при создании экземпляра класса. Если регион вашей подписки — не западная часть США, измените значение FetchTokenUri в соответствии с регионом своей подписки.

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

Пример для 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)

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

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

Ниже приведен пример HTTP-запроса к API преобразования речи в текст 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...

Использование проверки подлинности Microsoft Entra

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

создавать ресурс службы "Речь";
Настройка ресурса службы "Речь" для проверки подлинности Microsoft Entra
Получение маркера доступа Microsoft Entra
Получение идентификатора ресурса службы "Речь"

После получения идентификатора ресурса и маркера доступа 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: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

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

Следующие шаги

Tutorial: Create a custom acoustic model (Руководство. Создание пользовательской акустической модели)
Общие сведения о пакетном транскрибировании

Поделиться через

Преобразование речи в REST API для короткого звука

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

Форматы аудио

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

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

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

Образец запроса

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

Образцы ответов

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

Блочная передача

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

Как получить маркер доступа

Пример HTTP

Пример для PowerShell

Пример cURL

Пример на языке C#

Пример для Python

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

Использование проверки подлинности Microsoft Entra

Следующие шаги

Обратная связь

Дополнительные ресурсы