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

Статья
01/13/2025

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

Искусственный аватар видео будет создан асинхронно после того, как система получает ввод текста. Созданные выходные данные видео можно скачать в пакетном режиме синтеза. Вы отправляете текст для синтеза, опрос состояния синтеза и скачивание выходных данных видео, когда состояние указывает на успешность. Форматы ввода текста должны быть простым текстом или текстом языка разметки синтеза речи (SSML).

На этой схеме представлен общий обзор рабочего процесса.

Для выполнения пакетного синтеза можно использовать следующие операции REST API.

Операция	Method	Вызов REST API
Создание пакетного синтеза	PUT	аватар/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Получение пакетного синтеза	GET	аватар/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Перечисление пакетного синтеза	GET	аватар/batchsyntheses/?api-version=2024-08-01
Удаление пакетного синтеза	DELETE	аватар/batchsyntheses/{SynthesisId}?api-version=2024-08-01

Примеры кода можно ссылаться на GitHub.

Создание запроса на синтез пакетной службы

Некоторые свойства в формате JSON требуются при создании нового задания пакетного синтеза. Другие свойства являются необязательными. Ответ пакетного синтеза содержит другие свойства для предоставления сведений о состоянии синтеза и результатах. Например, outputs.result свойство содержит расположение, из которого можно скачать видеофайл , содержащий видео аватар. В outputs.summaryэтом разделе можно получить доступ к сводке и сведениям об отладке.

Чтобы отправить запрос на синтез пакетной службы, создайте текст ЗАПРОСА HTTP POST, выполнив следующие инструкции:

Задайте обязательное свойство inputKind.
inputKind Если для свойства задано PlainTextзначение, необходимо также задать voice свойство в объекте synthesisConfig. В приведенном ниже inputKind примере задано SSMLзначение , поэтому speechSynthesis оно не задано.
Задайте обязательное свойство SynthesisId. Выберите уникальный SynthesisId для одного и того же ресурса речи. Это SynthesisId может быть строка от 3 до 64 символов, включая буквы, цифры, "-" или "_", с условием, что он должен начинаться и заканчиваться буквой или числом.
Задайте обязательные talkingAvatarCharacter и talkingAvatarStyle свойства. Здесь можно найти поддерживаемые символы аватара и стили.
При необходимости можно задать videoFormatbackgroundColorи другие свойства. Дополнительные сведения см. в свойствах пакетного синтеза.

Примечание.

Максимальный размер полезных данных JSON составляет 500 килобайт.

Каждый ресурс службы "Речь" может выполнять до 200 заданий пакетного синтеза одновременно.

Максимальная длина выходного видео в настоящее время составляет 20 минут, что может увеличиться в будущем.

Чтобы сделать HTTP-запрос PUT, используйте формат URI, показанный в следующем примере. Замените YourSpeechKey ключом ресурса "Речь", YourSpeechRegion регионом ресурса "Речь" и задайте свойства текста запроса, как описано выше.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML",
    "inputs": [
        {
         "content": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"
        }
    ],
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting"
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/my-job-01?api-version=2024-08-01"

Вы должны получить ответ в следующем формате:

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "NotStarted",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:08.9487012Z",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    }
}

Свойство status должно выполняться от NotStarted состояния до Running и, наконец, до Succeeded или Failed. Вы можете периодически вызывать API пакетного синтеза GET до тех пор, пока возвращенное состояние не будет Succeeded или Failed.

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

Чтобы получить состояние задания пакетного синтеза, сделайте HTTP-запрос GET с помощью URI, как показано в следующем примере.

Замените YourSynthesisId идентификатором пакетного синтеза, YourSpeechKey ключом ресурса "Речь" и YourSpeechRegion регионом ресурса "Речь".

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Вы должны получить ответ в следующем формате:

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "Succeeded",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:12.5698769",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 344460,
        "durationInMilliseconds": 2520,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
            "neuralCharacters": 29,
            "talkingAvatarDurationSeconds": 2
        }
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    },
    "outputs": {
        "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
        "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
    }
}

outputs.result В поле можно скачать видеофайл, содержащий видео аватар. Поле outputs.summary позволяет скачать сведения о сводке и отладке. Дополнительные сведения о результатах пакетного синтеза см. в разделе результатов пакетного синтеза.

Перечисление пакетного синтеза

Чтобы перечислить все задания пакетного синтеза для ресурса "Речь", сделайте HTTP-запрос GET с помощью URI, как показано в следующем примере.

Замените YourSpeechKey ключом ресурса "Речь" и YourSpeechRegion регионом ресурса "Речь". При необходимости можно задать skip параметры запроса и top (размер страницы) в URL-адресе. Значение skip по умолчанию равно 0, а значение maxpagesize по умолчанию — 100.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses?skip=0&maxpagesize=2&api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Текст ответа будет получен в следующем формате:

{
    "value": [
        {
            "id": "my-job-02",
            "internalId": "14c25fcf-3cb6-4f46-8810-ecad06d956df",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:52:23.9054709Z",
            "lastActionDateTime": "2024-03-06T07:52:29.3416944",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 502676,
                "durationInMilliseconds": 2950,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 32,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "casual-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "h264",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        },
        {
            "id": "my-job-01",
            "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:34:08.9487009Z",
            "lastActionDateTime": "2024-03-06T07:34:12.5698769",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 344460,
                "durationInMilliseconds": 2520,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 29,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "graceful-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "hevc",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        }
    ],
    "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/?api-version=2024-08-01&skip=2&maxpagesize=2"
}

Из outputs.resultэтого файла можно скачать видео, содержащий видео аватар. В outputs.summaryэтом разделе можно получить доступ к сводке и сведениям об отладке. Дополнительные сведения см. в результатах пакетного синтеза.

Свойство в ответе value JSON выводит запросы синтеза. Этот список разбит на страницы. Максимальный размер страницы составляет 100 запросов. Свойство nextLink предоставляется по мере необходимости, чтобы получить следующую страницу списка с разбивкой на страницы.

Получение файла результатов пакетного синтеза

После получения задания пакетного синтеза с status параметром "Успешно" можно скачать результаты вывода видео. Используйте URL-адрес из outputs.result свойства ответа получения пакетного синтеза .

Чтобы получить файл результатов синтеза пакетной службы, сделайте HTTP-запрос GET с помощью URI, как показано в следующем примере. Замените YourOutputsResultUrl URL-адресом свойства outputs.result ответа получения пакетного синтеза . Замените YourSpeechKey ключом ресурса службы речи.

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > output.mp4

Чтобы получить сводный файл пакетного синтеза, сделайте HTTP-запрос GET с помощью URI, как показано в следующем примере. Замените YourOutputsResultUrl URL-адресом свойства outputs.summary ответа получения пакетного синтеза . Замените YourSpeechKey ключом ресурса службы речи.

curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json

Сводный файл содержит результаты синтеза для каждого текстового ввода. Ниже приведен пример файла summary.json:

{
  "jobID": "5a25b929-1358-4e81-a036-33000e788c46",
  "status": "Succeeded",
  "results": [
    {
      "texts": [
        "<speak version='1.0' xml:lang='en-US'><voice name='en-US-AvaMultilingualNeural'>The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "videoFileName": "244a87c294b94ddeb3dbaccee8ffa7eb/5a25b929-1358-4e81-a036-33000e788c46/0001.mp4",
      "TalkingAvatarCharacter": "lisa",
      "TalkingAvatarStyle": "graceful-sitting"
    }
  ]
}

Удаление пакетного синтеза

После получения результатов вывода звука и больше не требуется журнал заданий пакетного синтеза, его можно удалить. Служба "Речь" сохраняет каждый журнал синтеза timeToLiveInHours до 31 дней или длительность, указанную свойством запроса, в зависимости от того, что происходит раньше. Дата и время автоматического удаления для заданий синтеза с состоянием "Успешно" или "Сбой" вычисляется как сумма lastActionDateTime и timeToLive свойства.

Чтобы удалить задание синтеза пакетной службы, сделайте запрос HTTP DELETE с помощью следующего формата URI. Замените YourSynthesisId идентификатором пакетного синтеза, YourSpeechKey ключом ресурса "Речь" и YourSpeechRegion регионом ресурса "Речь".

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Заголовки ответа включают в себя HTTP/1.1 204 No Content успешное выполнение запроса на удаление.

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

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

Создание запроса на синтез пакетной службы

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

Перечисление пакетного синтеза

Получение файла результатов пакетного синтеза

Удаление пакетного синтеза

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

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

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