텍스트 음성 변환 아바타에 대한 일괄 처리 합성을 사용하는 방법
텍스트 음성 변환 아바타에 대한 일괄 처리 합성 API를 사용하면 텍스트를 말하는 아바타로 동영상 파일로 비동기 합성할 수 있습니다. 게시자와 동영상 콘텐츠 플랫폼은 이 API를 활용하여 일괄 처리로 아바타 동영상 콘텐츠를 만들 수 있습니다. 이러한 방식은 학습 자료, 프레젠테이션, 보급 알림 등 다양한 사용 사례에 적합할 수 있습니다.
가상 아바타 동영상은 시스템이 텍스트 입력을 받은 후 비동기적으로 생성됩니다. 생성된 동영상 출력은 일괄 처리 모드 합성으로 다운로드할 수 있습니다. 합성을 위해 텍스트를 제출하고, 합성 상태를 폴링하고, 상태가 성공을 나타내면 동영상 출력을 다운로드합니다. 텍스트 입력 형식은 일반 텍스트 또는 SSML(Speech Synthesis Markup Language) 텍스트여야 합니다.
이 다이어그램에서는 워크플로의 개략적인 개요를 제공합니다.
일괄 처리 합성을 수행하려면 다음 REST API 작업을 사용할 수 있습니다.
| 연산 | 메서드 | REST API 호출 |
|---|---|---|
| 일괄 처리 합성 만들기 | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| 일괄 처리 합성 가져오기 | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| 목록 일괄 처리 합성 | GET | avatar/batchsyntheses/?api-version=2024-08-01 |
| 일괄 처리 합성 삭제 | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
GitHub에서 코드 샘플을 참조할 수 있습니다.
일괄 처리 합성 요청 만들기
새 일괄 처리 합성 작업을 만들 때 JSON 형식의 일부 속성이 필요합니다. 다른 속성은 선택 사항입니다. 일괄 처리 합성 응답에는 합성 상태 및 결과에 대한 정보를 제공하는 다른 속성이 포함되어 있습니다. 예를 들어, outputs.result 속성에는 아바타 동영상이 포함된 동영상 파일을 다운로드할 수 있는 위치가 포함되어 있습니다. outputs.summary에서 요약 및 디버그 세부 정보에 액세스할 수 있습니다.
일괄 처리 합성 요청을 제출하려면 다음 지침에 따라 HTTP POST 요청 본문을 구성합니다.
- 필수
inputKind속성을 설정합니다. inputKind속성이PlainText로 설정된 경우synthesisConfig에서voice속성도 설정해야 합니다. 아래 예에서는inputKind이SSML로 설정되어 있으므로speechSynthesis가 설정되지 않습니다.- 필수
SynthesisId속성을 설정합니다. 동일한 음성 리소스에 대해 고유한SynthesisId를 선택합니다.SynthesisId는 문자, 숫자, '-' 또는 '_'를 포함하여 3~64자의 문자열일 수 있으며 문자나 숫자로 시작하고 끝나야 한다는 조건이 있습니다. - 필수
talkingAvatarCharacter및talkingAvatarStyle속성을 설정합니다. 지원되는 아바타 캐릭터와 스타일은 여기에서 확인할 수 있습니다. - 선택적으로
videoFormat,backgroundColor및 기타 속성을 설정할 수 있습니다. 자세한 내용은 일괄 처리 합성 속성을 참조하세요.
참고 항목
수락되는 최대 JSON 페이로드 크기는 500KB입니다.
각 음성 리소스에는 동시에 실행되는 일괄 처리 합성 작업이 최대 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로 진행되어야 합니다. 반환된 상태가 Succeeded 또는 Failed가 될 때까지 주기적으로 GET 일괄 처리 합성 API를 호출할 수 있습니다.
일괄 처리 합성 가져오기
일괄 처리 합성 작업의 상태를 검색하려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 수행합니다.
YourSynthesisId를 일괄 처리 합성 ID로 바꾸고, 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 필드를 사용하면 요약 및 디버그 세부 정보를 다운로드할 수 있습니다. 일괄 처리 합성 결과에 대한 자세한 내용은 일괄 처리 합성 결과를 참조하세요.
목록 일괄 처리 합성
음성 리소스에 대한 모든 일괄 처리 합성 작업을 나열하려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 수행합니다.
YourSpeechKey를 음성 리소스 키로 바꾸고 YourSpeechRegion을 음성 리소스 지역으로 바꿉니다. 선택적으로 URL에 skip 및 top(페이지 크기) 쿼리 매개 변수를 설정할 수 있습니다. 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에서 요약 및 디버그 세부 정보에 액세스할 수 있습니다. 자세한 내용은 일괄 처리 합성 결과를 참조하세요.
JSON 응답의 value 속성은 합성 요청을 나열합니다. 최대 100페이지가 포함된 목록의 페이지가 매겨집니다. 페이지가 매겨진 목록의 다음 페이지를 가져오기 위해 필요에 따라 nextLink 속성이 제공됩니다.
일괄 처리 합성 결과 파일 가져오기
status가 "성공"인 일괄 처리 합성 작업을 가져오면 동영상 출력 결과를 다운로드할 수 있습니다. 일괄 처리 합성 가져오기 응답의 outputs.result 속성에서 URL을 사용합니다.
일괄 처리 합성 결과 파일을 가져오려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 만듭니다. YourOutputsResultUrl을 일괄 처리 합성 가져오기 응답의 outputs.result 속성에 있는 URL로 바꿉니다. YourSpeechKey를 Speech 리소스 키로 바꿉니다.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > output.mp4
일괄 처리 합성 요약 파일을 가져오려면 다음 예와 같이 URI를 사용하여 HTTP GET 요청을 수행합니다. YourOutputsResultUrl을 일괄 처리 합성 가져오기 응답의 outputs.summary 속성에 있는 URL로 바꿉니다. YourSpeechKey를 Speech 리소스 키로 바꿉니다.
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"
}
]
}
일괄 처리 합성 삭제
오디오 출력 결과를 검색하고 일괄 처리 합성 작업 기록이 더 이상 필요하지 않으면 삭제할 수 있습니다. Speech Services는 최대 31일 또는 요청의 timeToLiveInHours 속성에 지정된 기간 중 더 빠른 기간 동안 각 합성 기록을 보존합니다. "성공" 또는 "실패" 상태의 합성 작업에 대한 자동 삭제 날짜 및 시간은 lastActionDateTime 및 timeToLive 속성의 합으로 계산됩니다.
일괄 처리 합성 작업을 삭제하려면 다음 URI 형식을 사용하여 HTTP DELETE 요청을 수행합니다. YourSynthesisId를 일괄 처리 합성 ID로 바꾸고, 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가 포함됩니다.