API пакетного синтеза для text to speech

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

Внимание

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

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

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

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

Совет

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

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

Операция	Метод	Вызов 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",
  "status": "Running",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 168,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

Свойство status должно перейти из состояния 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",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 168,
    "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, как показано в следующем примере. Замените YourSpeechKey вашим ключом ресурса «Речь», а YourSpeechRegion на регион вашего ресурса «Речь». При необходимости можно задать параметры запроса skip и maxpagesize в URL-адресе (до 100). Значение 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",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 168,
        "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",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 168,
        "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" предоставляется по мере необходимости, чтобы получить следующую страницу списка с разбивкой на страницы.

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

Удалите журнал заданий пакетного синтеза после получения результатов вывода звука. Служба "Speech" по умолчанию сохраняет историю пакетного синтеза в течение 168 часов (7 дней). Кроме того, этот период хранения можно указать с помощью timeToLiveInHours свойства до 744 часов (31 дней). Дата и время автоматического удаления (для заданий синтеза с состоянием "Успешно" или "Сбой") равно свойствам 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, если запрос на удаление был успешным.

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

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

Чтобы получить файл результатов пакетного синтеза, выполните HTTP GET запрос по указанному URI, как показано в следующем примере. Замените YourOutputsResultUrl на URL-адрес из свойства outputs.result ответа GET синтеза пакетного. Замените 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 секунд.

Лучшие практики

При рассмотрении пакетного синтеза для приложения рекомендуется оценить, соответствует ли задержка вашим требованиям. Если задержка соответствует требуемой производительности, пакетный синтез может быть подходящим вариантом. Однако если задержка не соответствует вашим потребностям, можно рассмотреть возможность использования API в режиме реального времени.

Коды состояния 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.
Вы попытались использовать недопустимый идентификатор развертывания или пользовательский голос, который не был успешно развернут. Убедитесь, что ресурс «Speech» имеет доступ к пользовательскому голосу и что он успешно развернут. Необходимо также убедиться, что в запросе пакетного синтеза сопоставление {"your-custom-voice-name": "your-deployment-ID"} правильно.
Вы пытались использовать ресурс Речь F0, но регион поддерживает только ценовую категорию ресурсов Стандартная речь.

Ошибка 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."
  }
}

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-02-25

API пакетного синтеза для text to speech

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

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

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

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

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

Задержка пакетного синтеза и лучшие практики

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

Лучшие практики

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

HTTP 200 OK

Создано HTTP 201

Ошибка HTTP 204

Ошибка HTTP 400

Ошибка HTTP 404

Ошибка HTTP 429

Ошибка HTTP 500

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

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

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

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