REST API преобразования текста в речь

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

Текст для речи REST API поддерживает нейронный текст для речи голоса во многих языковых стандартах. Каждая доступная конечная точка связана с регионом. Требуется ключ ресурса службы "Речь" для конечной точки или региона, который планируется использовать. Далее приведены ссылки для получения дополнительных сведений:

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

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

Получение списка голосов

Вы можете использовать конечную точку tts.speech.microsoft.com/cognitiveservices/voices/list для получения полного списка голосов для определенного региона или конечной точки. Префикс конечной точки списка голосов с регионом, чтобы получить список голосов для этого региона. Например, чтобы получить список голосов для westus региона, используйте конечную точку https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list . Список всех поддерживаемых регионов см. в документации по регионам.

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

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

Текст запроса

Для запросов GET к этой конечной точке текст запроса не требуется.

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

Для этого запроса требуется только заголовок авторизации.

GET /cognitiveservices/voices/list HTTP/1.1

Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

Ниже приведен пример команды curl:

curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

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

Вы должны получить ответ с текстом JSON, который включает все поддерживаемые языковые стандарты, голоса, пол, стили и другие сведения. Свойство WordsPerMinute для каждого голоса можно использовать для оценки длины выходной речи. В этом примере JSON показаны частичные результаты для иллюстрации структуры ответа:

[  
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
        "DisplayName": "Jenny",
        "LocalName": "Jenny",
        "ShortName": "en-US-JennyNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "StyleList": [
          "assistant",
          "chat",
          "customerservice",
          "newscast",
          "angry",
          "cheerful",
          "sad",
          "excited",
          "friendly",
          "terrified",
          "shouting",
          "unfriendly",
          "whispering",
          "hopeful"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "ExtendedPropertyMap": {
          "IsHighQuality48K": "True"
        },
        "WordsPerMinute": "152"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
        "DisplayName": "Jenny Multilingual",
        "LocalName": "Jenny Multilingual",
        "ShortName": "en-US-JennyMultilingualNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "SecondaryLocaleList": [
          "de-DE",
          "en-AU",
          "en-CA",
          "en-GB",
          "es-ES",
          "es-MX",
          "fr-CA",
          "fr-FR",
          "it-IT",
          "ja-JP",
          "ko-KR",
          "pt-BR",
          "zh-CN"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "190"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
        "DisplayName": "Orla",
        "LocalName": "Orla",
        "ShortName": "ga-IE-OrlaNeural",
        "Gender": "Female",
        "Locale": "ga-IE",
        "LocaleName": "Irish (Ireland)",
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "139"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
        "DisplayName": "Yunxi",
        "LocalName": "云希",
        "ShortName": "zh-CN-YunxiNeural",
        "Gender": "Male",
        "Locale": "zh-CN",
        "LocaleName": "Chinese (Mandarin, Simplified)",
        "StyleList": [
          "narration-relaxed",
          "embarrassed",
          "fearful",
          "cheerful",
          "disgruntled",
          "serious",
          "angry",
          "sad",
          "depressed",
          "chat",
          "assistant",
          "newscast"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

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

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

Преобразование текста в речь

Конечная точка cognitiveservices/v1 позволяет преобразовать текст в речь с помощью Языка разметки синтеза речи (SSML).

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

Эти регионы поддерживаются для преобразования текста в речь через REST API. Обязательно выберите конечную точку, соответствующую региону ресурса службы "Речь".

Предварительно созданные нейронные голоса

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

Пользовательские нейронные голоса

Если вы создали пользовательский нейронный голос, используйте созданную для него конечную точку. Также можно использовать следующие конечные точки. Замените {deploymentId} на идентификатор развертывания для модели нейронных голосов.

API длинного звука

API длинных аудиоматериалов доступен в нескольких регионах с уникальными конечными точками.

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

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

Текст запроса

Если применяется пользовательская нейронная модель речи, основной текст запроса можно отправить в формате обычного текста (ASCII или UTF-8). В противном случае текст каждого запроса POST отправляется как SSML. SSML позволяет выбрать голос и язык синтезируемой речи, возвращаемой функцией преобразования текста в речь. Полный список поддерживаемых голосов см. в разделе Поддержка языков и голосов в службе "Речь".

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

В этом HTTP-запросе используется SSML для указания голоса и языка. Если длина текста слишком велика и длительность полученной аудиодорожки превышает 10 минут, она усекается до 10 минут. Иными словами, длина аудиодорожки не может превышать 10 минут.

POST /cognitiveservices/v1 HTTP/1.1

X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>

<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
    name='en-US-ChristopherNeural'>
        I'm excited to try text to speech!
</voice></speak>

^* Для Content-Length следует использовать собственную длину содержимого. В большинстве случаев это значение вычисляется автоматически.

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

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

Если состояние HTTP — 200 OK, текст ответа содержит звуковой файл в затребованном формате. Этот файл можно воспроизводить при передаче, сохранении в буфер или сохранении в файл.

Аудиосигналы

Поддерживаемые форматы потоковой передачи и непотоковых звуковых форматов отправляются в каждом запросе в качестве заголовка X-Microsoft-OutputFormat . Каждый формат включает значение скорости и типа кодирования. Служба "Речь" поддерживает выходные аудиоданные с частотой дискретизации 48, 24, 16 и 8 кГц. Каждая предварительно созданная нейронная голосовая модель доступна в 24 кбГц и высокой точности 48kГц.

amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

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

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

При использовании заголовка 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 фактический маркер доступа можно создать в следующем формате:

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, включая время существования маркеров, посетите маркеры доступа в платформа удостоверений Майкрософт.

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

• Создайте бесплатную учетную запись Azure
• Начало работы с пользовательским нейронным голосом
• Пакетный синтез