텍스트 음성 변환 REST API

아티클
01/21/2024

Speech Service를 사용하면 텍스트를 합성 음성으로 변환하고 REST API를 사용하여 지역에 지원되는 음성 목록을 가져올 수 있습니다. 이 문서에서는 권한 부여 옵션, 쿼리 옵션, 요청을 구성하는 방법 및 응답을 해석하는 방법에 대해 알아봅니다.

팁

텍스트 음성 변환 REST API의 일반적인 사용 사례는 제한되어 있습니다. 음성 SDK를 사용할 수 없는 경우에만 사용합니다. 예를 들어 Speech SDK를 사용하면 이벤트를 구독하여 텍스트 음성 변환 처리 및 결과에 대한 더 많은 인사이트를 얻을 수 있습니다.

Text to Speech REST API는 많은 로캘에서 인공신경망 텍스트 음성 음성을 지원합니다. 사용 가능한 각 엔드포인트는 지역과 연결됩니다. 사용하려는 엔드포인트나 지역의 음성 리소스 키가 필요합니다. 자세한 내용은 다음 링크를 참조하세요.

음성의 전체 목록은 Speech Service의 언어 및 음성 지원을 참조하세요.
지역 가용성에 대한 자세한 내용은 Speech Service 지원 지역을 참조하세요.
Azure Government 및 21Vianet 엔드포인트에 의해 운영되는 Microsoft Azur 소버린 클라우드에 대한 이 문서를 참조하세요.

Important

비용은 미리 빌드된 음성신경망 음성(가격 책정 페이지에서 인공신경망이라고 함) 및 사용자 지정 신경망 음성(가격 책정 페이지에서 사용자 지정 신경망이라고 함)에 따라 다릅니다. 자세한 내용은 Speech Service 가격 책정을 참조하세요.

텍스트 음성 변환 REST API를 사용하기 전에 서비스에 액세스하려면 인증의 일부로 토큰 교환을 완료해야 합니다. 자세한 내용은 인증을 참조 하세요.

음성 목록 가져오기

tts.speech.microsoft.com/cognitiveservices/voices/list 엔드포인트를 사용하여 특정 지역이나 엔드포인트의 전체 음성 목록을 가져올 수 있습니다. 음성 목록 엔드포인트를 지역에 접두사로 추가하여 해당 지역의 음성 목록을 얻습니다. 예를 들어 westus 지역에 대한 음성 목록을 얻으려면 https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list 엔드포인트를 사용합니다. 지원되는 모든 지역 목록은 지역 설명서를 참조하세요.

참고 항목

미리 보기로 제공되는 음성 및 스타일은 미국 동부, 서유럽 및 동남 아시아의 3개 서비스 지역에서만 사용할 수 있습니다.

요청 헤더

이 표에는 텍스트 음성 변환 요청에 대한 필수 헤더 및 선택적 헤더가 나열되어 있습니다.

헤더	설명	필수 또는 선택 사항
`Ocp-Apim-Subscription-Key`	음성 리소스 키입니다.	이 헤더 또는 `Authorization`가 필요합니다.
`Authorization`	단어 `Bearer`앞에 오는 권한 부여 토큰입니다. 자세한 내용은 인증을 참조 하세요.	이 헤더 또는 `Ocp-Apim-Subscription-Key`가 필요합니다.

요청 본문

본문은 이 엔드포인트에 대한 GET 요청에 필요하지 않습니다.

샘플 요청

이 요청에는 권한 부여 헤더만 필요합니다.

GET /cognitiveservices/voices/list HTTP/1.1

Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

다음은 curl 명령의 예입니다.

curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

샘플 응답

지원되는 모든 로캘, 음성, 성별, 스타일 및 기타 세부 정보가 포함된 JSON 본문으로 응답을 받아야 합니다. 각 음성의 WordsPerMinute 속성을 사용하여 출력 음성의 길이를 예측할 수 있습니다. 이 JSON 예제에서는 응답의 구조를 설명하는 부분 결과를 보여 줍니다.

[  
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
        "DisplayName": "Jenny",
        "LocalName": "Jenny",
        "ShortName": "en-US-JennyNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "StyleList": [
          "assistant",
          "chat",
          "customerservice",
          "newscast",
          "angry",
          "cheerful",
          "sad",
          "excited",
          "friendly",
          "terrified",
          "shouting",
          "unfriendly",
          "whispering",
          "hopeful"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "ExtendedPropertyMap": {
          "IsHighQuality48K": "True"
        },
        "WordsPerMinute": "152"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
        "DisplayName": "Jenny Multilingual",
        "LocalName": "Jenny Multilingual",
        "ShortName": "en-US-JennyMultilingualNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "SecondaryLocaleList": [
          "de-DE",
          "en-AU",
          "en-CA",
          "en-GB",
          "es-ES",
          "es-MX",
          "fr-CA",
          "fr-FR",
          "it-IT",
          "ja-JP",
          "ko-KR",
          "pt-BR",
          "zh-CN"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "190"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
        "DisplayName": "Orla",
        "LocalName": "Orla",
        "ShortName": "ga-IE-OrlaNeural",
        "Gender": "Female",
        "Locale": "ga-IE",
        "LocaleName": "Irish (Ireland)",
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "139"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
        "DisplayName": "Yunxi",
        "LocalName": "云希",
        "ShortName": "zh-CN-YunxiNeural",
        "Gender": "Male",
        "Locale": "zh-CN",
        "LocaleName": "Chinese (Mandarin, Simplified)",
        "StyleList": [
          "narration-relaxed",
          "embarrassed",
          "fearful",
          "cheerful",
          "disgruntled",
          "serious",
          "angry",
          "sad",
          "depressed",
          "chat",
          "assistant",
          "newscast"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

HTTP 상태 코드

각 응답에 대한 HTTP 상태 코드는 성공 또는 일반적인 오류를 나타냅니다.

HTTP 상태 코드	설명	가능한 원인
200	OK	요청에 성공했습니다.
400	Bad request	필수 매개 변수가 없거나 비어 있거나 null입니다. 또는 필수 또는 선택적 매개 변수에 전달된 값이 잘못되었습니다. 일반적인 원인은 헤더가 너무 길다는 점입니다.
401	Unauthorized	요청에 부여된 권한이 없습니다. 리소스 키 또는 토큰이 유효하고 올바른 영역에 있는지 확인합니다.
429	Too many requests	리소스에 허용되는 요청의 할당량 또는 비율을 초과했습니다.
502	잘못된 게이트웨이	네트워크 또는 서버 쪽 문제가 있습니다. 이 상태는 잘못된 헤더를 나타낼 수도 있습니다.

텍스트 음성 변환

cognitiveservices/v1 엔드포인트를 사용하면 SSML(Speech Synthesis Markup Language)을 사용하여 텍스트를 음성으로 변환할 수 있습니다.

지역 및 엔드포인트

이러한 지역은 REST API를 통한 텍스트 음성 변환에 지원됩니다. 사용자 음성 리소스 지역과 일치하는 엔드포인트를 선택해야 합니다.

미리 빌드된 신경망 음성

다음 표를 사용하여 지역 또는 엔드포인트별 신경망 음성의 가용성을 확인 합니다 .

지역	엔드포인트
오스트레일리아 동부	`https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1`
브라질 남부	`https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1`
캐나다 중부	`https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1`
미국 중부	`https://centralus.tts.speech.microsoft.com/cognitiveservices/v1`
동아시아	`https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1`
미국 동부	`https://eastus.tts.speech.microsoft.com/cognitiveservices/v1`
미국 동부 2	`https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1`
프랑스 중부	`https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1`
독일 중서부	`https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1`
인도 중부	`https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1`
일본 동부	`https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1`
일본 서부	`https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1`
Jio 인도 서부	`https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1`
한국 중부	`https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1`
미국 중북부	`https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1`
북유럽	`https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1`
노르웨이 동부	`https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1`
미국 중남부	`https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1`
동남아시아	`https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1`
스웨덴 중부	`https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1`
스위스 북부	`https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1`
스위스 서부	`https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1`
아랍에미리트 북부	`https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1`
US Gov 애리조나	`https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1`
US Gov 버지니아	`https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1`
영국 남부	`https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1`
미국 중서부	`https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1`
서유럽	`https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1`
미국 서부	`https://westus.tts.speech.microsoft.com/cognitiveservices/v1`
미국 서부 2	`https://westus2.tts.speech.microsoft.com/cognitiveservices/v1`
미국 서부 3	`https://westus3.tts.speech.microsoft.com/cognitiveservices/v1`

팁

미리 보기로 제공되는 음성은 미국 동부, 서유럽 및 동남 아시아 등 3지역에서만 사용 가능합니다.

사용자 지정 신경망 음성

사용자 지정 신경망 음성 글꼴을 만든 경우 사용자가 만든 엔드포인트를 사용합니다. 다음 엔드포인트를 사용할 수도 있습니다. {deploymentId}를 인공신경망 음성 모델의 배포 ID로 바꿉니다.

지역	학습	배포	엔드포인트
오스트레일리아 동부	예	예	`https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
브라질 남부	예	예	`https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
캐나다 중부	예	예	`https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 중부	예	예	`https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
동아시아	예	예	`https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 동부	예	예	`https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 동부 2	예	예	`https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
프랑스 중부	예	예	`https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
독일 중서부	예	예	`https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
인도 중부	예	예	`https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
일본 동부	예	예	`https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
일본 서부	예	예	`https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
Jio 인도 서부	예	예	`https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
한국 중부	예	예	`https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 중북부	예	예	`https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
북유럽	예	예	`https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
노르웨이 동부	예	예	`https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
남아프리카 북부	예	예	`https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 중남부	예	예	`https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
동남아시아	예	예	`https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
스위스 북부	예	예	`https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
스위스 서부	예	예	`https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
아랍에미리트 북부	예	예	`https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
영국 남부	예	예	`https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 중서부	예	예	`https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
서유럽	예	예	`https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 서부	예	예	`https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 서부 2	예	예	`https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`
미국 서부 3	예	네	`https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}`

참고 항목

앞선 지역은 인공신경망 음성 모델 호스트 및 실시간 합성에 사용될 수 있습니다. 사용자 지정 신경망 음성 학습은 일부 지역에서만 사용할 수 있습니다. 그러나 사용자는 이러한 지역의 인공신경망 음성 모델을 앞선 목록에 있는 지역으로 간편하게 복사할 수 있습니다.

긴 오디오 API

긴 오디오 API는 고유한 엔드포인트를 통해 여러 지역에서 사용 가능합니다.

지역	엔드포인트
오스트레일리아 동부	`https://australiaeast.customvoice.api.speech.microsoft.com`
미국 동부	`https://eastus.customvoice.api.speech.microsoft.com`
인도 중부	`https://centralindia.customvoice.api.speech.microsoft.com`
미국 중남부	`https://southcentralus.customvoice.api.speech.microsoft.com`
동남아시아	`https://southeastasia.customvoice.api.speech.microsoft.com`
영국 남부	`https://uksouth.customvoice.api.speech.microsoft.com`
서유럽	`https://westeurope.customvoice.api.speech.microsoft.com`

요청 헤더

이 표에는 텍스트 음성 변환 요청에 대한 필수 헤더 및 선택적 헤더가 나열되어 있습니다.

헤더	설명	필수 또는 선택 사항
`Authorization`	단어 `Bearer`앞에 오는 권한 부여 토큰입니다. 자세한 내용은 인증을 참조 하세요.	Required
`Content-Type`	제공된 텍스트의 콘텐츠 형식을 지정합니다. 허용되는 값: `application/ssml+xml`.	Required
`X-Microsoft-OutputFormat`	오디오 출력 형식을 지정합니다. 허용되는 값의 전체 목록은 오디오 출력을 참조하세요.	Required
`User-Agent`	애플리케이션 이름입니다. 제공된 값은 255자 미만이어야 합니다.	Required

요청 본문

사용자 지정 신경망 음성을 사용하는 경우에는 요청 본문을 일반 텍스트(ASCII 또는 UTF-8)로 전송할 수 있습니다. 그렇지 않으면 각 POST 요청의 본문이 SSML로 전송됩니다. SSML을 사용하면 텍스트 음성 변환 기능에서 반환한 합성 음성의 음성과 언어를 선택할 수 있습니다. 지원되는 음성의 전체 목록은 Speech Service의 언어 및 음성 지원을 참조하세요.

샘플 요청

이 HTTP 요청은 SSML을 사용하여 음성 및 언어를 지정합니다. 본문 길이가 길어 오디오가 10분을 초과하면 10분으로 잘립니다. 즉, 오디오 길이는 10분을 초과할 수 없습니다.

POST /cognitiveservices/v1 HTTP/1.1

X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>

<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
    name='en-US-ChristopherNeural'>
        I'm excited to try text to speech!
</voice></speak>

^* Content-Length의 경우 고유한 콘텐츠 길이를 사용해야 합니다. 대부분의 경우 이 값은 자동으로 계산됩니다.

HTTP 상태 코드

각 응답의 HTTP 상태 코드는 성공 또는 일반 오류를 나타냅니다.

HTTP 상태 코드	설명	가능한 원인
200	OK	요청에 성공했습니다. 응답 본문은 오디오 파일입니다.
400	Bad request	필수 매개 변수가 없거나 비어 있거나 null입니다. 또는 필수 또는 선택적 매개 변수에 전달된 값이 잘못되었습니다. 일반적인 원인은 헤더가 너무 길다는 점입니다.
401	Unauthorized	요청에 부여된 권한이 없습니다. 음성 리소스 키 또는 토큰이 유효하고 올바른 지역에 있는지 확인합니다.
415	지원되지 않는 미디어 형식	잘못된 `Content-Type` 값이 제공되었을 수 있습니다. `Content-Type`는 `application/ssml+xml`로 설정되어야 합니다.
429	Too many requests	리소스에 허용되는 요청의 할당량 또는 비율을 초과했습니다.
502	잘못된 게이트웨이	네트워크 또는 서버 쪽 문제가 있습니다. 이 상태는 잘못된 헤더를 나타낼 수도 있습니다.

HTTP 상태 200 OK응답 본문에 요청된 형식의 오디오 파일이 포함됩니다. 이 파일은 전송되거나, 버퍼에 저장되거나, 파일에 저장될 때 재생할 수 있습니다.

오디오 출력

지원되는 스트리밍 및 비스트림 오디오 형식은 각 요청에서 헤더로 X-Microsoft-OutputFormat 전송됩니다. 각 형식은 비트 속도와 인코딩 형식을 통합합니다. Speech Service에서는 48kHz, 24kHz, 16kHz 및 8kHz 오디오 출력을 지원합니다. 미리 빌드된 각 신경망 음성 모델은 24kHz 및 고충실도 48kHz에서 사용할 수 있습니다.

스트리밍
NonStreaming

amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

참고 항목

48kHz 출력 형식을 선택하면 48kHz가 있는 안정적인 음성 모델이 그에 따라 호출됩니다. 24kHz 및 48kHz 이외의 샘플 속도는 합성 시 업샘플링 또는 다운샘플링을 통해 얻을 수 있습니다. 예를 들어 44.1kHz는 48kHz에서 다운샘플링됩니다.

선택한 음성 및 출력 형식의 비트 속도가 다르면 필요에 따라 오디오가 다시 샘플링됩니다. Opus 코덱을 사용하여 ogg-24khz-16bit-mono-opus 형식을 디코딩할 수 있습니다.

인증

각 요청에는 권한 부여 헤더가 필요합니다. 이 표에서는 각 기능에 대해 지원되는 헤더를 보여줍니다.

지원되는 인증 헤더	음성 텍스트 변환	텍스트 음성 변환
`Ocp-Apim-Subscription-Key`	예	네
`Authorization: Bearer`	네	예

Ocp-Apim-Subscription-Key 헤더를 사용하는 경우 리소스 키만 제공하면 됩니다. 예시:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Authorization: Bearer 헤더를 사용하는 경우 issueToken 엔드포인트에 요청해야 합니다. 이 요청에서는 10분 동안 유효한 액세스 토큰에 대한 리소스 키를 교환합니다.

액세스 토큰을 가져오는 방법

액세스 토큰을 가져오려면 Ocp-Apim-Subscription-Key 및 리소스 키를 사용하여 issueToken 엔드포인트에 요청해야 합니다.

issueToken 엔드포인트의 형식은 다음과 같습니다.

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

<REGION_IDENTIFIER>를 구독 지역과 일치하는 식별자로 바꿉니다.

다음 샘플을 사용하여 액세스 토큰 요청을 만듭니다.

HTTP 샘플

이 예제는 토큰을 가져오는 간단한 HTTP 요청입니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독이 미국 서부 지역에 없는 경우 헤더를 Host 해당 지역의 호스트 이름으로 바꿉시다.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

응답 본문에는 JWT(JSON Web Token) 형식의 액세스 토큰이 포함됩니다.

PowerShell 샘플

이 예제는 액세스 토큰을 가져오는 간단한 PowerShell 스크립트입니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독과 일치하는 지역에 올바른 엔드포인트를 사용해야 합니다. 이 예제는 현재 미국 서부로 설정됩니다.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL 샘플

cURL은 Linux(및 Linux용 Windows 하위 시스템)에서 사용할 수 있는 명령줄 도구입니다. 이 cURL 명령은 액세스 토큰을 가져오는 방법을 보여 줍니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독과 일치하는 지역에 올바른 엔드포인트를 사용해야 합니다. 이 예제는 현재 미국 서부로 설정됩니다.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

C# 샘플

이 C# 클래스는 액세스 토큰을 가져오는 방법을 보여 줍니다. 이 클래스를 인스턴스화할 때 Speech Service에 대한 리소스 키를 전달합니다. 구독이 미국 서부 지역에 없는 경우 구독의 FetchTokenUri 지역과 일치하도록 값을 변경합니다.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Python 샘플

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

액세스 토큰을 사용하는 방법

액세스 토큰은 헤더로 Authorization: Bearer <TOKEN> 서비스에 전송되어야 합니다. 각 액세스 토큰은 10분 동안 유효합니다. 언제든지 새 토큰을 가져올 수 있지만, 네트워크 트래픽 및 대기 시간을 최소화하려면 동일한 토큰을 9분 동안 사용하는 것이 좋습니다.

다음은 짧은 오디오를 위한 음성 텍스트 변환 REST API에 대한 샘플 HTTP 요청입니다.

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

텍스트 음성 변환 REST API

음성 목록 가져오기

요청 헤더

요청 본문

샘플 요청

샘플 응답

HTTP 상태 코드

텍스트 음성 변환

지역 및 엔드포인트

미리 빌드된 신경망 음성

사용자 지정 신경망 음성

긴 오디오 API

요청 헤더

요청 본문

샘플 요청

HTTP 상태 코드

오디오 출력

인증

액세스 토큰을 가져오는 방법

HTTP 샘플

PowerShell 샘플

cURL 샘플

C# 샘플

Python 샘플

액세스 토큰을 사용하는 방법

다음 단계

추가 리소스