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

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

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

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

Необходимые условия

Чтобы использовать текст для распознавания речи REST API, вам потребуется:

• Учетная запись Azure. Создайте аккаунт бесплатно.
• Ресурс "Речь" на портале Azure.
• Ключ ресурса и конечная точка со страницы ресурса «Речь» Ключи и конечная точка.

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

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

При использовании заголовка 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.

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

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

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

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

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

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

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

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

GET /tts/cognitiveservices/voices/list HTTP/1.1

Host: YourResourceName.cognitiveservices.azure.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

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

curl --location --request GET 'https://YourResourceName.cognitiveservices.azure.com/tts/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": "48000",
        "VoiceType": "Neural",
        "Status": "GA",
        "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": "48000",
        "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": "48000",
        "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": "48000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

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

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

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

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

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

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

Стандартные голоса

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

Пользовательские голоса

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

Интерфейс прикладного программирования для длительного аудио

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

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

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

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

Если вы используете пользовательский голос, текст запроса можно отправить как обычный текст (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: YourResourceName.cognitiveservices.azure.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>

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

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

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

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

Аудиовыходы

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

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
g722-16khz-64kbps
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

Дальнейшие действия

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