음성 합성(TTS) 안내

음성 합성(TTS) 안내

POST /v1/audio/speech는 OpenAI-compatible 형식입니다. JSON을 보내면 오디오 파일을 바이너리로 받습니다. ElevenLabs 계열에는 elevenlabs/eleven-v4, eleven-v4-turbo, eleven-v3, eleven-v3-conversational, eleven-multilingual-v2, eleven-flash-v2.5, eleven-flash-v2, eleven-turbo-v2.5, eleven-turbo-v2가 있습니다. 최신 목록은 GET /v1/models?output_modalities=speech에서 확인하세요. GET /v1/models는 기본적으로 텍스트 모델만 반환하므로 ?output_modalities=speech(또는 all)를 붙여 목록을 확인하세요.

매개변수

위의 음성 설정 7개는 모두 선택 사항이며, 보내지 않으면 아무것도 바뀌지 않습니다. 범위를 벗어난 값은 400을 반환하며 전송도 과금도 되지 않습니다. 응답 헤더 X-Voice-Settings는 설정이 사용되었는지 알려 줍니다: applied = 사용됨; ignored = 예비 경로가 응답하여 설정이 사용되지 않았습니다(오디오는 정상적으로 생성됩니다); 헤더 없음 = 음성 설정을 보내지 않았습니다. 예: stability 0은 더 표현력 있게, 1은 더 고르게 읽습니다.

음성 규칙

ElevenLabs 모델(elevenlabs/…)에는 다음 음성 이름(대소문자 무관) 중 하나를 넣으세요: george, sarah, adam, alice, bella, bill, brian, callum, charlie, chris, daniel, eric, harry, jessica, laura, liam, lily, matilda, river, roger, will. ElevenLabs 모델은 voice를 생략할 수 있습니다(기본 george). 그 외 값은 400 invalid_voice를 반환합니다. 내 사용자 지정 음성(voice_…)은 아래 ‘사용자 지정 음성’ 섹션을 참조하세요.

alloy, echo, nova 같은 OpenAI-style 음성 이름은 해당 이름을 나열한 모델에서만 작동합니다. 모델 페이지에서 지원 음성을 확인하세요.

사용자 지정 음성(복제)은 단계적으로 공개 중입니다. 아래 ‘사용자 지정 음성’ 섹션(POST /v1/voices)을 참조하세요. 계정에서 활성화되기 전에는 위의 21개 프리셋 이름이나 공개 음성 ID를 사용하세요.

기본 제공 음성 목록

voice에는 아래 표의 음성 이름(소문자)을 지정할 수 있습니다. 각 음성에는 짧은 미리듣기 클립이 있으며, GET /api/v1/audio/voices로 전체 목록(성별, 연령대, 억양, 스타일, 미리듣기 URL)을 가져올 수 있습니다.

?lang=(en, zh-TW, zh-CN, 기본값은 Accept-Language)은 description의 언어만 정합니다. 미리듣기 URL은 바뀌지 않습니다: preview_urls.en(preview_url과 동일)은 영어, preview_urls.zh(preview_url_zh와 동일)는 중국어 클립입니다.

감정·동작 태그(audio tags)

input 안에 대괄호로 태그를 직접 적습니다. 예: [laughs], [whispers], [excited], [sighs], [crying], [curious], [softly]. 태그는 입력한 그대로 모델에 전달되어 뒤따르는 말의 연기 방식을 정합니다. 본문이 한국어여도 태그는 영어로 유지하세요.

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-v3","input":"[laughs] That was actually funny. [whispers] Do not tell anyone.","voice":"george","response_format":"mp3"}' \
  --output audio-tags.mp3

elevenlabs/eleven-v3 와 elevenlabs/eleven-v4 계열이 지원합니다. 다른 음성 모델은 태그를 해석하지 않고 대괄호 안 글자를 그대로 읽을 수 있으니 먼저 짧은 문장으로 시험해 보세요.

태그도 input 글자 수에 포함되며 나머지 텍스트와 같은 방식으로 과금됩니다.

출력 형식

response_format을 생략하면 mp3(Content-Type audio/mpeg)가 기본입니다. pcm(audio/pcm, 원시 16-bit PCM)도 동작합니다. API는 opus, aac, flac, wav도 받지만 ElevenLabs 모델은 현재 400으로 거부합니다. 파일은 응답의 Content-Type 헤더에 따라 저장하세요.

요금

음성 합성은 입력 문자 수에 따라 청구됩니다. 문자당 가격은 /models의 모델 페이지와 GET /v1/models의 pricing.character에 있습니다. 모델 페이지에는 백만 문자 기준으로 표시됩니다.

예제

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-flash-v2.5","input":"Hello from BazaarLink.","voice":"george","response_format":"mp3"}' \
  --output speech.mp3

흔한 오류

전체 매개변수 참조: 음성 합성

음성 합성

/v1/models?output_modalities=speech의 모델 ID로 텍스트를 음성으로 변환합니다. 모델 페이지의 백만 문자당 가격으로 청구합니다. 전체 오디오를 버퍼링한 뒤 바이너리로 반환하며, 구간별 스트리밍은 지원하지 않습니다. provider, transforms, route, service_tier, preset 같은 라우팅 제어 필드는 무시됩니다.

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "$BAZAARLINK_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{"model":"<speech-model-id>","input":"Hello","voice":"alloy","response_format":"mp3"}' \
  --output speech.mp3

# Voice settings (elevenlabs/* models; the X-Voice-Settings response header says applied or ignored)
curl -D - https://api.bazaarlink.ai/v1/audio/speech \
  -H "$BAZAARLINK_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-v4","input":"Hello","voice":"george","stability":0.4,"similarity_boost":0.8,"style":0.2,"use_speaker_boost":true,"language_code":"en","audio_effects":{"distance":0.3}}' \
  --output speech.mp3