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

Статья
04/25/2024

API синтеза пакетной службы может синтезировать большой объем ввода текста (длинный и короткий) асинхронно. Издатели и платформы аудиоконтентов могут создавать длинное звуковое содержимое в пакете. Например: аудио книги, новостные статьи и документы. API пакетного синтеза может создавать синтезированный звук дольше 10 минут.

Внимание

API синтеза пакетной службы общедоступен. API long Audio будет прекращен 1 апреля 2027 г. Дополнительные сведения см. в разделе "Миграция в API пакетного синтеза".

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

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

Схема рабочего процесса API пакетного синтеза.

Совет

Вы также можете использовать пакет SDK службы "Речь" для создания синтезированного звука дольше 10 минут, итерируя текст и синтезируя его в блоках. Пример C# см. в разделе GitHub.

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

Операция	Method	Вызов REST API
Создание пакетного синтеза	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
Получение пакетного синтеза	`GET`	texttospeech/batchsyntheses/YourSynthesisId
Перечисление пакетного синтеза	`GET`	texttospeech/batchsyntheses
Удаление пакетного синтеза	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

Примеры кода см. в разделе GitHub.

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

Чтобы отправить запрос на синтез пакетной обработки, создайте путь запроса HTTP PUT и текст в соответствии со следующими инструкциями:

Задайте обязательное свойство inputKind.
inputKind Если для свойства задано значение "PlainText", необходимо также задать voice свойство в объекте synthesisConfig. В приведенном ниже inputKind примере задано значение SSML, поэтому synthesisConfig оно не задано.
При необходимости можно задать descriptiontimeToLiveInHoursи другие свойства. Дополнительные сведения см. в свойствах пакетного синтеза.

Примечание.

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

Задайте необходимый YourSynthesisId путь. Необходимо YourSynthesisId быть уникальным. Оно должно быть длиной 3–64, содержит только цифры, буквы, дефисы, знаки подчеркивания и точки, начинается и заканчивается буквой или номером.

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

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

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

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

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

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

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

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

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

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

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

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

Чтобы перечислить все задания пакетного синтеза для ресурса "Речь", сделайте HTTP-запрос GET с помощью URI, как показано в следующем примере. Замените ключом ресурса "Речь" и замените YourSpeechKeyYourSpeechRegion регионом ресурсов службы "Речь". При необходимости можно задать skip параметры запроса и maxpagesize (до 100) в URL-адресе. Значение skip по умолчанию равно 0, а значение maxpagesize по умолчанию — 100.

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

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

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

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

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

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

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

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

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

Результаты пакетного синтеза

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

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

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

Результаты находятся в ZIP-файле, который содержит звук (например 0001.wav, сводку и сведения об отладке). Нумерованный префикс каждого имени файла (показано ниже, как [nnnn]) находится в том же порядке, что и текстовые входные данные, используемые при создании синтеза пакетной службы.

Примечание.

Файл [nnnn].debug.json содержит идентификатор результата синтеза и другие сведения, которые могут помочь в устранении неполадок. Свойства, содержащиеся в нем, могут измениться, поэтому не следует принимать никаких зависимостей в формате JSON.

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

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

Если запрашивались данные границ предложения ("sentenceBoundaryEnabled": true), соответствующий [nnnn].sentence.json файл включается в результаты. Аналогичным образом, если запрашивались данные границ слова ("wordBoundaryEnabled": true), соответствующий [nnnn].word.json файл включается в результаты.

Ниже приведен пример файла данных word с смещением звука и длительностью в миллисекундах:

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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

При использовании пакетного синтеза для создания синтезированного речи важно учитывать задержку и следовать рекомендациям по достижению оптимальных результатов.

Задержка в пакетном синтезе

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

Задержка для синтеза пакетной службы выполняется следующим образом (приблизительно):

Задержка в 50% от синтезированных выходных данных речи составляет от 10 до 20 секунд.
Задержка в 95% от синтезированных выходных данных речи составляет в течение 120 секунд.

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

В разделе подробно описаны коды и сообщения HTTP-ответов из API пакетного синтеза.

HTTP 200 OK

HTTP 200 OK указывает, что запрос выполнен успешно.

Создано HTTP 201

Http 201 Create указывает на успешное выполнение запроса на синтез пакетной службы (через HTTP PUT).

Ошибка HTTP 204

Ошибка HTTP 204 указывает, что запрос выполнен успешно, но ресурс не существует. Например:

Вы попытались получить или удалить задание синтеза, которое не существует.
Задание синтеза успешно удалено.

Ошибка HTTP 400

Ниже приведены примеры, которые могут привести к ошибке 400:

Неподдерживаемый outputFormat или недопустимый. Укажите допустимое значение формата или оставьте outputFormat пустым, чтобы использовать параметр по умолчанию.
Число запрошенных текстовых входных данных превысило ограничение в 10 000.
Вы попытались использовать недопустимый идентификатор развертывания или пользовательский голос, который не был успешно развернут. Убедитесь, что ресурс "Речь" имеет доступ к пользовательскому голосу, а пользовательский голос успешно развернут. Необходимо также убедиться, что сопоставление {"your-custom-voice-name": "your-deployment-ID"} правильно в запросе синтеза пакетной службы.
Вы пытались использовать ресурс "Речь F0", но регион поддерживает только ценовую категорию ресурсов "Стандартная речь".
Вы попытались создать новое задание синтеза пакетной службы, которое превысит ограничение в 300 активных заданий. Каждый ресурс службы "Речь" может иметь до 300 заданий пакетного синтеза, которые не имеют состояния "Успешно" или "Неудачно".

Ошибка HTTP 404

Не удается найти указанную сущность. Проверьте правильность идентификатора синтеза.

Ошибка HTTP 429

Слишком много последних запросов. Каждое клиентское приложение может отправлять до 100 запросов в 10 секунд для каждого ресурса службы "Речь". Уменьшите количество запросов в секунду.

Ошибка HTTP 500

Ошибка внутреннего сервера HTTP 500 указывает на сбой запроса. Текст ответа содержит сообщение об ошибке.

Пример ошибки HTTP

Ниже приведен пример запроса, который приводит к ошибке HTTP 400, так как inputs свойство требуется для создания задания.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

В этом случае заголовки ответа включают HTTP/1.1 400 Bad Request.

Текст ответа похож на следующий пример JSON:

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

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

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

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

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

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

Результаты пакетного синтеза

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

Задержка в пакетном синтезе

Рекомендации

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

HTTP 200 OK

Создано HTTP 201

Ошибка HTTP 204

Ошибка HTTP 400

Ошибка HTTP 404

Ошибка HTTP 429

Ошибка HTTP 500

Пример ошибки HTTP

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

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