텍스트 음성 변환의 일괄 처리 합성 속성

아티클
10/16/2024

Important

Batch 합성 API는 일반적으로 사용할 수 있습니다. Long Audio API는 2027년 4월 1일에 사용 중지됩니다. 자세한 내용은 일괄 처리 합성 API로 마이그레이션을 참조하세요.

일괄 처리 합성 API는 대량의 텍스트 입력(길고 짧음)을 비동기식으로 합성할 수 있습니다. 게시자 및 오디오 콘텐츠 플랫폼은 일괄 처리로 긴 오디오 콘텐츠를 만들 수 있습니다. 예: 오디오 책, 뉴스 기사 및 문서 일괄 처리 합성 API는 10분 이상의 합성 오디오를 만들 수 있습니다.

새 일괄 처리 합성 작업을 만들 때 JSON 형식의 일부 속성이 필요합니다. 다른 속성은 선택 사항입니다. 일괄 처리 합성 응답에는 합성 상태와 결과에 대한 정보를 제공하는 다른 속성이 포함됩니다. 예를 들어 outputs.result 속성에는 오디오 출력과 로그가 있는 일괄 처리 합성 결과 파일의 위치가 포함됩니다.

일괄 처리 합성 속성

일괄 처리 합성 속성은 다음 표에 설명되어 있습니다.

속성	설명
`createdDateTime`	일괄 처리 합성 작업이 만들어진 날짜 및 시간입니다. 이 속성은 읽기 전용입니다.
`customVoices`	Custom Voice 이름 및 해당 배포 ID의 맵입니다. 예: `"customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}` `synthesisConfig.voice`(`inputKind`이 `"PlainText"`로 설정된 경우) 또는 `inputs`의 SSML 텍스트(`inputKind`이 `"SSML"`로 설정된 경우)에서 음성 이름을 사용할 수 있습니다. 이 속성은 Custom Voice을 사용하는 데 필요합니다. 여기에 정의되지 않은 Custom Voice을 사용하려고 하면 서비스에서 오류를 반환합니다.
`description`	일괄 처리 합성에 대한 설명입니다. 이 속성은 선택 사항입니다.
`id`	경로에 전달한 일괄 처리 합성 작업 ID입니다. 이 속성은 경로에 필요합니다.
`inputs`	합성할 일반 텍스트 또는 SSML입니다. `inputKind`이 `"PlainText"`로 설정되면 다음과 같이 일반 텍스트를 제공합니다. `"inputs": [{"text": "The rainbow has seven colors."}]`. `inputKind`이 `"SSML"`로 설정되면 다음과 같이 SSML(Speech Synthesis Markup Language)로 텍스트를 제공합니다. `"inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}]`. 여러 오디오 출력 파일을 원하는 경우 최대 1,000개의 텍스트 개체를 포함합니다. 다음은 두 개의 오디오 출력 파일 `"inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]`로 합성되어야 하는 예 입력 텍스트입니다. 그러나 `properties.concatenateResult` 속성이 `true`로 설정된 경우 각 합성 결과는 동일한 오디오 출력 파일에 기록됩니다. 새 단락에 대해 별도의 텍스트 입력이 필요하지 않습니다. 최대 1,000개의 텍스트 입력 내에서 "\r\n"(개행) 문자열을 사용하여 새 단락을 지정할 수 있습니다. 다음은 동일한 오디오 출력 파일로 합성되어야 하는 두 개의 단락이 있는 입력 텍스트의 예입니다. `"inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]` 단락 제한은 없지만, 최대 JSON 페이로드 크기(텍스트 입력 및 기타 속성 모두 포함)는 2메가바이트입니다. 이 속성은 새 일괄 처리 합성 작업을 만들 때 필요합니다. 이 속성은 합성 작업을 가져올 때 응답에 포함되지 않습니다.
`internalId`	내부 일괄 처리 합성 작업 ID입니다. 이 속성은 읽기 전용입니다.
`lastActionDateTime`	`status` 속성 값이 변경된 가장 최근 날짜 및 시간입니다. 이 속성은 읽기 전용입니다.
`outputs.result`	오디오 출력 및 로그가 있는 일괄 처리 합성 결과 파일의 위치입니다. 이 속성은 읽기 전용입니다.
`properties`	선택적 일괄 처리 합성 구성 설정의 정의된 집합입니다.
`properties.sizeInBytes`	오디오 출력 크기(바이트)입니다. 이 속성은 읽기 전용입니다.
`properties.billingDetails`	`customNeuralCharacters` 대 `neuralCharacters`(미리 빌드된) 음성에서 처리되고 청구된 단어의 수입니다. 이 속성은 읽기 전용입니다.
`properties.concatenateResult`	결과를 연결할지 여부를 결정합니다. 이 선택적 `bool` 값("true" 또는 "false")은 기본적으로 "false"입니다.
`properties.decompressOutputFiles`	대상 컨테이너에서 합성 결과 파일의 압축을 해제할지 여부를 결정합니다. 이 속성은 `destinationContainerUrl` 속성이 설정된 경우에만 설정할 수 있습니다. 이 선택적 `bool` 값("true" 또는 "false")은 기본적으로 "false"입니다.
`properties.destinationContainerUrl`	일괄 처리 합성 결과는 쓰기 가능한 Azure 컨테이너에 저장할 수 있습니다. SAS(공유 액세스 서명) 토큰으로 컨테이너 URI를 지정하지 않으면 Speech Services는 Microsoft에서 관리하는 컨테이너에 결과를 저장합니다. 저장된 액세스 정책이 있는 SAS는 지원되지 않습니다. 합성 작업이 삭제되면 결과 데이터도 삭제됩니다. 이 선택적 속성은 합성 작업을 가져올 때 응답에 포함되지 않습니다.
`properties.destinationPath`	일괄 처리 합성 결과를 저장할 수 있는 접두사 경로입니다. 접두사 경로를 지정하지 않으면 기본 접두사 경로는 `YourSpeechResourceId/YourSynthesisId`입니다. 이 선택적 속성은 `destinationContainerUrl` 속성이 설정된 경우에만 설정할 수 있습니다.
`properties.durationInMilliseconds`	오디오 출력 기간(밀리초)입니다. 이 속성은 읽기 전용입니다.
`properties.failedAudioCount`	오디오 출력에 대한 일괄 처리 합성 입력 수에 실패했습니다. 이 속성은 읽기 전용입니다.
`properties.outputFormat`	오디오 출력 형식입니다. 허용되는 값에 대한 자세한 내용은 오디오 출력 형식을 참조하세요. 기본 출력 형식은 `riff-24khz-16bit-mono-pcm`입니다.
`properties.sentenceBoundaryEnabled`	문장 경계 데이터 생성 여부를 결정합니다. 이 선택적 `bool` 값("true" 또는 "false")은 기본적으로 "false"입니다. 문장 경계 데이터가 요청되면 해당 `[nnnn].sentence.json` 파일이 결과 데이터 ZIP 파일에 포함됩니다.
`properties.succeededAudioCount`	오디오 출력에 대한 일괄 처리 합성 입력의 카운트가 성공했습니다. 이 속성은 읽기 전용입니다.
`properties.timeToLiveInHours`	합성 작업이 만들어진 후 합성 결과가 자동으로 삭제되는 기간(시간)입니다. 이 선택적 설정은 기본적으로 `744`(31일)입니다. 최대 생존 기간은 31일입니다. 자동 삭제 날짜 및 시간(상태가 "성공" 또는 "실패"인 합성 작업의 경우)은 `lastActionDateTime` + `timeToLiveInHours` 속성과 같습니다. 그렇지 않으면 delete 합성 메서드를 호출하여 작업을 더 빨리 제거할 수 있습니다.
`properties.wordBoundaryEnabled`	단어 경계 데이터 생성 여부를 결정합니다. 이 선택적 `bool` 값("true" 또는 "false")은 기본적으로 "false"입니다. 단어 경계 데이터가 요청되면 해당 `[nnnn].word.json` 파일이 결과 데이터 ZIP 파일에 포함됩니다.
`status`	일괄 처리 합성 처리 상태입니다. 상태는 "NotStarted"에서 "Running"으로, 마지막으로 "Succeeded" 또는 "Failed"로 진행되어야 합니다. 이 속성은 읽기 전용입니다.
`synthesisConfig`	일반 텍스트의 일괄 처리 합성에 사용할 구성 설정입니다. 이 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.backgroundAudio`	각 오디오 출력의 배경 오디오입니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.backgroundAudio.fadein`	백그라운드 오디오 페이드인 시간(밀리초)입니다. 기본값은 페이드 인이 없는 `0`입니다. 허용되는 값은 `0`~`10000` 범위입니다. 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서에서 배경 오디오 추가 아래의 특성 테이블을 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.backgroundAudio.fadeout`	백그라운드 오디오 페이드 아웃 시간(밀리초)입니다. 기본값은 페이드 아웃이 없는 `0`입니다. 허용되는 값은 `0`~`10000` 범위입니다. 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서에서 배경 오디오 추가 아래의 특성 테이블을 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.backgroundAudio.src`	백그라운드 오디오 파일의 URI 위치입니다. 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서에서 배경 오디오 추가 아래의 특성 테이블을 참조하세요. 유효하지 않은 값은 무시됩니다. 이 속성은 `synthesisConfig.backgroundAudio`가 설정된 경우에 필요합니다.
`synthesisConfig.backgroundAudio.volume`	백그라운드 오디오 파일의 볼륨입니다. 허용되는 값은 `0`~`100` 범위입니다. 기본값은 `1`입니다. 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서에서 배경 오디오 추가 아래의 특성 테이블을 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.pitch`	오디오 출력의 피치입니다. 허용되는 값에 대한 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서의 prosody 조정 표를 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.rate`	오디오 출력의 속도입니다. 허용되는 값에 대한 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서의 prosody 조정 표를 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.role`	일부 음성의 경우 말하기 역할 플레이를 조정할 수 있습니다. 음성은 다른 나이와 성별을 흉내낼 수 있지만 음성 이름은 변경되지 않습니다. 예를 들어 남자 음성의 피치를 높이고 억양을 변경하여 여자 음성을 모방할 수 있지만 음성 이름은 변경되지 않습니다. 역할이 없거나 음성에 대해 지원되지 않는 경우 이 특성은 무시됩니다. 음성별로 사용 가능한 스타일에 대한 자세한 내용은 음성 스타일 및 역할을 참조하세요. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.speakerProfileId`	개인 음성의 화자 프로필 ID입니다. 사용 가능한 개인 음성 기반 모델 이름에 대한 자세한 내용은 개인 음성 통합을 참조하세요. 화자 프로필 ID를 가져오는 방법에 대한 자세한 내용은 언어 및 음성 지원을 참조하세요. 이 속성은 `inputKind`가 `"PlainText"`로 설정된 경우에 필요합니다.
`synthesisConfig.style`	일부 음성의 경우 말하기 스타일을 조정하여 명랑함, 공감, 차분함과 같은 다양한 감정을 표현할 수 있습니다. 고객 서비스, 뉴스캐스트, 음성 지원 등의 여러 시나리오에 맞게 음성을 최적화할 수 있습니다. 음성별로 사용 가능한 스타일에 대한 자세한 내용은 음성 스타일 및 역할을 참조하세요. 이 선택적 속성은 `synthesisConfig.style`이 설정된 경우에만 적용됩니다.
`synthesisConfig.styleDegree`	말하는 스타일의 강도입니다. 더 강한 스타일 또는 더 부드러운 스타일을 지정하여 음성에 감정을 더 싣거나 더 차분하게 말할 수 있습니다. 허용되는 값의 범위는 0.01에서 2까지입니다. 기본값은 미리 정의된 스타일 강도를 의미하는 1입니다. 최소 단위인 0.01은 대상 스타일의 성향을 약간 보입니다. 값이 2이면 기본 스타일 강도는 두 배가 됩니다. 스타일 정도가 누락되었거나 음성에 지원되지 않는 경우 이 특성은 무시됩니다. 음성별로 사용 가능한 스타일에 대한 자세한 내용은 음성 스타일 및 역할을 참조하세요. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`synthesisConfig.voice`	오디오 출력을 말하는 음성입니다. 사용 가능한 미리 빌드된 신경망 음성에 대한 자세한 내용은 언어 및 음성 지원을 참조하세요. Custom Voice을 사용하려면 `customVoices` 속성에 유효한 Custom Voice 및 배포 ID 매핑을 지정해야 합니다. 개인 음성을 사용하려면 `synthesisConfig.speakerProfileId` 속성을 지정해야 합니다. 이 속성은 `inputKind`가 `"PlainText"`로 설정된 경우에 필요합니다.
`synthesisConfig.volume`	오디오 출력의 볼륨입니다. 허용되는 값에 대한 자세한 내용은 SSML(Speech Synthesis Markup Language) 설명서의 prosody 조정 표를 참조하세요. 유효하지 않은 값은 무시됩니다. 이 선택적 속성은 `inputKind`이 `"PlainText"`로 설정된 경우에만 적용됩니다.
`inputKind`	`inputs` 텍스트 속성이 일반 텍스트인지 아니면 SSML인지를 나타냅니다. 가능한 대/소문자 구분 값은 "PlainText" 및 "SSML"입니다. `inputKind`이 `"PlainText"`로 설정되면 `synthesisConfig` 음성 속성도 설정해야 합니다. 이 속성은 필수입니다.

일괄 처리 합성 대기 시간 및 모범 사례

합성된 음성을 생성하기 위해 일괄 처리 합성을 사용하는 경우 관련된 대기 시간을 고려하고 최적의 결과를 달성하기 위한 모범 사례를 따르는 것이 중요합니다.

일괄 처리 합성의 대기 시간

일괄 처리 합성의 대기 시간은 입력 텍스트의 복잡성, 일괄 처리의 입력 수 및 기본 하드웨어의 처리 기능을 비롯한 다양한 요인에 따라 달라집니다.

일괄 처리 합성의 대기 시간은 다음과 같습니다(대략).

합성된 음성 출력 50%에 대한 대기 시간은 10-20초 이내입니다.
합성된 음성 출력 95%에 대한 대기 시간은 120초 이내입니다.

모범 사례

애플리케이션에 대한 일괄 처리 합성을 고려할 때 대기 시간이 사용자 요구에 적합한지 여부를 평가하는 것이 좋습니다. 대기 시간이 원하는 성능과 일치하는 경우 일괄 처리 합성이 적합한 선택일 수 있습니다. 그러나 대기 시간이 사용자 요구 사항을 충족하지 못하면 실시간 API를 사용하는 것이 좋습니다.

HTTP 상태 코드

섹션에서는 일괄 처리 합성 API의 HTTP 응답 코드 및 메시지에 대해 자세히 설명합니다.

HTTP 200 OK

HTTP 200 OK는 요청이 성공했음을 나타냅니다.

HTTP 201 Created

HTTP 201 Created는 일괄 처리 합성 만들기 요청(HTTP POST를 통해)이 성공했음을 나타냅니다.

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 음성 리소스를 사용하려고 했지만 해당 지역은 표준 음성 리소스 가격 책정 계층만 지원합니다.

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."
  }
}

다음을 통해 공유