타입캐스트 API를 위한 공식 Kotlin 라이브러리입니다. AI 기반 음성을 사용하여 텍스트를 생동감 있는 음성으로 변환하세요.Kotlin 1.9+ 및 JDK 17 이상 버전과 호환됩니다. Gradle (Kotlin DSL 또는 Groovy) 및 Maven과 함께 작동합니다.
import com.neosapience.TypecastClientimport com.neosapience.models.*import java.io.Filefun main() { // 클라이언트 초기화 val client = TypecastClient.create("YOUR_API_KEY") // 텍스트를 음성으로 변환 val request = TTSRequest.builder() .voiceId("tc_672c5f5ce59fac2a48faeaee") .text("안녕하세요! 저는 텍스트 음성 변환 에이전트입니다.") .model(TTSModel.SSFM_V30) .build() val response = client.textToSpeech(request) // 오디오 파일 저장 File("output.${response.format}").writeBytes(response.audioData) println("Audio saved! Duration: ${response.duration}s, Format: ${response.format}") // 정리 client.close()}
// 환경 변수 사용// export TYPECAST_API_KEY="your-api-key-here"val client = TypecastClient.create()// 또는 직접 전달val client = TypecastClient.create("your-api-key-here")// 또는 사용자 정의 구성을 위해 빌더 사용val client = TypecastClient.builder() .apiKey("your-api-key-here") .baseUrl("https://custom-api.example.com") .build()
자체 프록시를 통해 요청하는 경우 baseUrl을 프록시 엔드포인트로 설정하고 apiKey를 생략할 수 있습니다. API 키가 비어 있거나 없으면 SDK는 X-API-KEY 헤더를 보내지 않습니다. 기본 Typecast 호스트로 요청할 때는 API 키가 계속 필요합니다.
API 키 없는 프록시
val client = TypecastClient.builder() .baseUrl("https://your-proxy.example.com") .build()
val request = TTSRequest.builder() .voiceId("tc_672c5f5ce59fac2a48faeaee") .text("모든 것이 잘 될 거예요.") .model(TTSModel.SSFM_V30) .prompt(SmartPrompt.builder() .previousText("방금 최고의 소식을 들었어요!") // 선택적 문맥 .nextText("축하할 수 있어서 너무 기다려져요!") // 선택적 문맥 .build()) .build()val response = client.textToSpeech(request)
프리셋 값으로 감정을 명시적으로 설정합니다:
val request = TTSRequest.builder() .voiceId("tc_672c5f5ce59fac2a48faeaee") .text("이 기능들을 보여드리게 되어 정말 기대됩니다!") .model(TTSModel.SSFM_V30) .prompt(PresetPrompt.builder() .emotionPreset(EmotionPreset.HAPPY) // normal, happy, sad, angry, whisper, toneup, tonedown .emotionIntensity(1.5) // 범위: 0.0 ~ 2.0 .build()) .build()val response = client.textToSpeech(request)
한 voice로 읽는 문장 안에 쉼만 넣고 싶다면 텍스트에 pause markup을 직접 작성합니다. <|5s|>, <|1s|>, <|0.3s|>, <|0.34413s|>처럼 쓰며 값은 초 단위이고 반드시 s로 끝납니다. 별도 pause 함수를 호출하지 않아도 텍스트만 보고 쉼 위치를 확인할 수 있습니다.
val audio = client.composeSpeech() .defaults(ComposerSettings(voiceId = "tc_672c5f5ce59fac2a48faeaee", model = TTSModel.SSFM_V30)) .say("안녕하세요<|5s|>반갑습니다<|1s|>오늘<|2s|>날씨는 어떤 것 같으세요?") .generate()
한 파일 안에서 서로 다른 voice나 구간별 pitch, tempo, prompt, seed 같은 옵션을 조합해야 할 때 사용합니다. composer는 각 구간을 WAV로 생성하고 앞뒤 무음 PCM 샘플을 trim한 뒤 합성합니다. MP3가 필요하면 먼저 WAV를 생성한 다음 앱 또는 서버 파이프라인에서 변환하세요.
val client = TypecastClient.create("YOUR_API_KEY")val audio = client.composeSpeech() .defaults(ComposerSettings(voiceId = "tc_672c5f5ce59fac2a48faeaee", model = TTSModel.SSFM_V30)) .say("Hello there") .pause(5.0) .say("Nice to meet you", ComposerSettings(voiceId = "tc_60e5426de8b95f1d3000d7b5", output = Output(audioPitch = 2))) .say("Today") .pause(2.0) .say("How does the weather feel?") .generate()File("conversation.wav").writeBytes(audio.audioData)
textToSpeechWithTimestamps()는 POST /v1/text-to-speech/with-timestamps를 래핑하며, 오디오와 함께 단어·문자 단위 정렬 데이터를 반환합니다. 가라오케 하이라이트, 자막 생성, 립싱크 애플리케이션에 활용할 수 있습니다.
granularity("word")(기본값) 또는 granularity("char")을 설정해 정렬 단위를 제어합니다.
// 문자 단위 정렬 — 일본어·중국어에 필수val result = client.textToSpeechWithTimestamps( TTSRequestWithTimestamps.builder() .voiceId("tc_60e5426de8b95f1d3000d7b5") .text("Hello. How are you?") .model("ssfm-v30") .granularity("char") .build())
