텍스트 음성 변환을 위한 Batch 합성 API
일괄 처리 합성 API는 대량의 텍스트 입력(길고 짧음)을 비동기식으로 합성할 수 있습니다. 게시자 및 오디오 콘텐츠 플랫폼은 일괄 처리로 긴 오디오 콘텐츠를 만들 수 있습니다. 예: 오디오 책, 뉴스 기사 및 문서 일괄 처리 합성 API는 10분 이상의 합성 오디오를 만들 수 있습니다.
Important
Batch 합성 API는 일반적으로 사용할 수 있습니다. Long Audio API는 2027년 4월 1일에 사용 중지됩니다. 자세한 내용은 일괄 처리 합성 API로 마이그레이션을 참조하세요.
일괄 처리 합성 API는 비동기식이며 합성된 오디오를 실시간으로 반환하지 않습니다. 합성할 텍스트 파일을 제출하고, 상태를 폴링하고, 상태가 성공을 나타내는 경우 오디오 출력을 다운로드합니다. 텍스트 입력은 일반 텍스트 또는 SSML(Speech Synthesis Markup Language) 텍스트여야 합니다.
이 다이어그램에서는 워크플로의 개략적인 개요를 제공합니다.
팁
또한 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"로 설정된 경우synthesisConfig에서voice속성도 설정해야 합니다. 아래 예에서inputKind은 "SSML"로 설정되어 있으므로synthesisConfig는 설정되지 않습니다.- 선택적으로
description,timeToLiveInHours및 기타 속성을 설정할 수 있습니다. 자세한 내용은 일괄 처리 합성 속성을 참조하세요.
참고 항목
허용되는 최대 JSON 페이로드 크기는 2MB입니다. 각 음성 리소스는 동시에 실행되는 최대 300개의 일괄 처리 합성 작업을 가질 수 있습니다.
경로에 필요한 YourSynthesisId(을)를 설정합니다. YourSynthesisId(은)는 고유해야 합니다. 3-64 길이여야 하며 숫자, 문자, 하이픈, 밑줄 및 점만 포함하며 문자 또는 숫자로 시작하고 끝납니다.
다음 예제와 같이 URI를 사용하여 HTTP PUT 요청을 수행합니다. YourSpeechKey를 Speech 리소스 키로 바꾸고, YourSpeechRegion을 Speech 리소스 영역으로 바꾸고, 앞에서 설명한 대로 요청 본문 속성을 설정합니다.
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로 진행되어야 합니다. 반환된 상태가 Succeeded 또는 Failed가 될 때까지 주기적으로 GET 일괄 처리 합성 API를 호출할 수 있습니다.
일괄 처리 합성 가져오기
일괄 처리 합성 작업의 상태를 가져오려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 수행합니다. 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에서 오디오(예: 0001.wav), 요약 및 디버그 세부 정보가 포함된 ZIP 파일을 다운로드할 수 있습니다. 자세한 내용은 일괄 처리 합성 결과를 참조하세요.
목록 일괄 처리 합성
음성 리소스에 대한 모든 일괄 처리 합성 작업을 나열하려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 수행합니다. YourSpeechKey를 음성 리소스 키로 바꾸고, YourSpeechRegion을 음성 리소스 지역으로 바꿉니다. 필요에 따라 URL에서 skip 및 maxpagesize (최대 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",
"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"
}
outputs.result에서 오디오(예: 0001.wav), 요약 및 디버그 세부 정보가 포함된 ZIP 파일을 다운로드할 수 있습니다. 자세한 내용은 일괄 처리 합성 결과를 참조하세요.
json 응답의 value 속성은 합성 요청을 나열합니다. 최대 100페이지가 포함된 목록의 페이지가 매겨집니다. 페이지가 매겨진 목록의 다음 페이지를 가져오기 위해 필요에 따라 "nextLink" 속성이 제공됩니다.
일괄 처리 합성 삭제
오디오 출력 결과를 검색한 후 일괄 처리 합성 작업 기록을 삭제합니다. Speech Service는 일괄 합성 기록을 최대 31일 또는 요청 timeToLiveInHours 속성의 기간 중 더 빠른 기간 동안 유지합니다. 자동 삭제 날짜 및 시간(상태가 "성공" 또는 "실패"인 합성 작업의 경우)은 lastActionDateTime + timeToLiveInHours 속성과 같습니다.
일괄 처리 합성 작업을 삭제하려면 다음 예와 같이 URI를 사용하여 HTTP DELETE 요청을 만듭니다. YourSynthesisId를 일괄 처리 합성 ID로 바꾸고 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가 포함됩니다.
일괄 처리 합성 결과
"Succeeded"의 status로 일괄 처리 합성 작업을 가져온 후에 오디오 출력 결과를 다운로드할 수 있습니다. 일괄 처리 합성 가져오기 응답의 outputs.result 속성에서 URL을 사용합니다.
일괄 처리 합성 결과 파일을 가져오려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 만듭니다. YourOutputsResultUrl을 일괄 처리 합성 가져오기 응답의 outputs.result 속성에 있는 URL로 바꿉니다. YourSpeechKey를 Speech 리소스 키로 바꿉니다.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip
결과는 오디오(예: 0001.wav), 요약 및 디버그 세부 정보가 포함된 ZIP 파일에 있습니다. 각 파일 이름의 번호가 붙은 접두사(아래 [nnnn]으로 표시됨)는 일괄 처리 합성을 만들 때 사용된 텍스트 입력과 동일한 순서입니다.
참고 항목
[nnnn].debug.json 파일에는 합성 결과 ID 및 문제 해결에 도움이 될 수 있는 기타 정보가 포함되어 있습니다. 여기에 포함된 속성은 변경될 수 있으므로 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 파일이 결과에 포함됩니다.
다음은 오디오 오프셋과 지속 시간(밀리초)이 모두 포함된 단어 데이터 파일의 예입니다.
[
{
"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 상태 코드
섹션에서는 일괄 처리 합성 API의 HTTP 응답 코드 및 메시지에 대해 자세히 설명합니다.
HTTP 200 OK
HTTP 200 OK는 요청이 성공했음을 나타냅니다.
HTTP 201 Created
HTTP 201 Created는 일괄 처리 합성 만들기 요청(HTTP PUT를 통해)이 성공했음을 나타냅니다.
HTTP 204 오류
HTTP 204 오류는 요청이 성공했지만 리소스가 존재하지 않음을 나타냅니다. 예시:
- 존재하지 않는 합성 작업을 가져오거나 삭제하려고 했습니다.
- 합성 작업을 성공적으로 삭제했습니다.
HTTP 400 오류
다음은 400 오류가 발생할 수 있는 예입니다.
outputFormat은 지원되지 않거나 유효하지 않습니다. 유효한 형식 값을 제공하거나outputFormat을 비워 두어 기본 설정을 사용합니다.- 요청된 텍스트 입력 수가 10,000개 제한을 초과했습니다.
- 성공적으로 배포되지 않은 잘못된 배포 ID 또는 Custom Voice를 사용하려고 했습니다. 음성 리소스가 Custom Voice에 액세스할 수 있고 Custom Voice가 성공적으로 배포되었는지 확인합니다. 또한 일괄 처리 합성 요청에서
{"your-custom-voice-name": "your-deployment-ID"}의 매핑이 올바른지 확인해야 합니다. - F0 음성 리소스를 사용하려고 했지만 해당 지역은 표준 음성 리소스 가격 책정 계층만 지원합니다.
- 300개의 활성 작업 제한을 초과하는 새 일괄 처리 합성 작업을 만들려고 했습니다. 각 음성 리소스에는 "Succeeded" 또는 "Failed" 상태가 아닌 최대 300개의 일괄 처리 합성 작업이 있을 수 있습니다.
HTTP 404 오류
지정된 엔터티를 찾을 수 없습니다. 합성 ID가 올바른지 확인합니다.
HTTP 429 오류
최근 요청이 너무 많습니다. 각 클라이언트 애플리케이션은 각 음성 리소스에 대해 10초당 최대 100개의 요청을 제출할 수 있습니다. 초당 요청 수를 줄입니다.
HTTP 500 오류
HTTP 500 내부 서버 오류는 요청이 실패했음을 나타냅니다. 응답 본문에는 오류 메시지가 포함되어 있습니다.
HTTP 오류 예
다음은 작업을 만드는 데 inputs 속성이 필요하기 때문에 HTTP 400 오류가 발생하는 예제 요청입니다.
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."
}
}