Providers

Azure 음성 서비스

Azure Speech는 번들로 제공되는 Azure AI Speech 텍스트 음성 변환 제공자입니다. OpenClaw은 SSML을 사용하여 Azure Speech REST API를 직접 호출하며, 일반 응답에는 MP3를, 음성 메모에는 네이티브 Ogg/Opus를, Voice Call과 같은 전화 통신 채널에는 8kHz mulaw를 합성합니다. 요청은 제공자가 소유한 출력 형식을 X-Microsoft-OutputFormat 헤더를 통해 전송합니다.

세부 정보	값
제공자 ID	`azure-speech`(별칭: `azure`)
웹사이트	Azure AI Speech
문서	Speech REST 텍스트 음성 변환
인증	`AZURE_SPEECH_KEY` 및 `AZURE_SPEECH_REGION`
기본 음성	`en-US-JennyNeural`
기본 파일 출력	`audio-24khz-48kbitrate-mono-mp3`
기본 음성 메모 파일	`ogg-24khz-16bit-mono-opus`

시작하기

Azure Speech 리소스 만들기

Azure 포털에서 Speech 리소스를 만듭니다. Resource Management > Keys and Endpoint에서 KEY 1을 복사하고, eastus와 같은 리소스 위치를 복사합니다.

Code

AZURE_SPEECH_KEY=<speech-resource-key>AZURE_SPEECH_REGION=eastus

messages.tts에서 Azure Speech 선택하기

json5

{  messages: {    tts: {      auto: "always",      provider: "azure-speech",      providers: {        "azure-speech": {          voice: "en-US-JennyNeural",          lang: "en-US",        },      },    },  },}

메시지 보내기

연결된 채널을 통해 응답을 보냅니다. OpenClaw은 Azure Speech로 오디오를 합성하고, 일반 오디오에는 MP3를, 채널에서 음성 메모를 요구하는 경우에는 Ogg/Opus를 전송합니다.

구성 옵션

모든 옵션은 messages.tts.providers["azure-speech"] 아래에 있습니다.

옵션	설명
`apiKey`	Azure Speech 리소스 키입니다. `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` 또는 `SPEECH_KEY`를 대체 값으로 사용합니다.
`region`	Azure Speech 리소스 리전입니다. `AZURE_SPEECH_REGION` 또는 `SPEECH_REGION`을 대체 값으로 사용합니다.
`endpoint`	선택적 Azure Speech 엔드포인트 재정의입니다. `AZURE_SPEECH_ENDPOINT`를 대체 값으로 사용합니다.
`baseUrl`	선택적 Azure Speech 기본 URL 재정의입니다.
`voice`	Azure 음성 ShortName입니다(기본값: `en-US-JennyNeural`). 레거시 별칭: `voiceId`.
`lang`	SSML 언어 코드입니다(기본값: `en-US`).
`outputFormat`	오디오 파일 출력 형식입니다(기본값: `audio-24khz-48kbitrate-mono-mp3`).
`voiceNoteOutputFormat`	음성 메모 출력 형식입니다(기본값: `ogg-24khz-16bit-mono-opus`).
`timeoutMs`	요청 제한 시간을 밀리초 단위로 재정의합니다. 전역 `messages.tts.timeoutMs`를 대체 값으로 사용합니다.

apiKey와 함께 region, endpoint 또는 baseUrl 중 하나를 설정하면 제공자가 구성된 것으로 간주됩니다. 환경 변수는 설정되지 않은 구성 키의 대체 값으로만 확인됩니다.

참고 사항

인증

Azure Speech는 Azure OpenAI 키가 아니라 Speech 리소스 키를 사용합니다. 키는 Ocp-Apim-Subscription-Key로 전송됩니다. endpoint 또는 baseUrl을 제공하지 않으면 OpenClaw은 region에서 https://<region>.tts.speech.microsoft.com을 도출합니다.

음성 이름

Azure Speech 음성의 ShortName 값(예: en-US-JennyNeural)을 사용합니다. 번들 제공자는 동일한 Speech 리소스를 통해 음성 목록을 가져올 수 있으며, 사용 중단 예정, 폐기 또는 비활성화로 표시된 음성을 제외합니다.

오디오 출력

Azure는 audio-24khz-48kbitrate-mono-mp3, ogg-24khz-16bit-mono-opus, riff-24khz-16bit-mono-pcm 등의 출력 형식을 허용합니다. OpenClaw은 채널에서 별도의 MP3 변환 없이 네이티브 음성 말풍선을 보낼 수 있도록 voice-note 대상에 Ogg/Opus를 요청하며, 전화 통신 대상에는 raw-8khz-8bit-mono-mulaw를 강제로 사용합니다.

별칭

기존 구성에서는 azure를 제공자 별칭으로 사용할 수 있지만, Azure OpenAI 모델 제공자와 혼동하지 않도록 새 구성에서는 azure-speech를 사용해야 합니다.