> ## Documentation Index > Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Go > 공식 Go SDK로 타입캐스트 API에 액세스하세요. [타입캐스트 API](https://typecast.ai)를 위한 공식 Go 라이브러리입니다. AI 기반 음성을 사용하여 텍스트를 생동감 있는 음성으로 변환하세요. Go 1.21 이상 버전과 호환됩니다. 외부 의존성 없이 Go 표준 라이브러리만 사용합니다. Typecast Go SDK Typecast Go SDK 소스 코드 ## 설치 ```bash theme={null} go get github.com/neosapience/typecast-sdk/typecast-go ``` 최신 등록 버전은 Go modules 기준 **typecast-go/v0.3.7**입니다. **Go 1.21 이상**이 설치되어 있는지 확인하세요. `go version` 명령으로 버전을 확인할 수 있습니다. ## 빠른 시작 ```go theme={null} package main import ( "context" "os" typecast "github.com/neosapience/typecast-sdk/typecast-go" ) func main() { // 클라이언트 초기화 client := typecast.NewClient(&typecast.ClientConfig{ APIKey: "YOUR_API_KEY", }) ctx := context.Background() // 텍스트를 음성으로 변환 response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "안녕하세요! 저는 텍스트 음성 변환 에이전트입니다.", Model: typecast.ModelSSFMV30, }) if err != nil { panic(err) } // 오디오 파일 저장 os.WriteFile("output.wav", response.AudioData, 0644) println("Audio saved! Format:", string(response.Format)) } ``` ## 기능 Typecast Go SDK는 텍스트 음성 변환을 위한 강력한 기능을 제공합니다: * **다중 음성 모델**: `ssfm-v30`(최신) 및 `ssfm-v21` AI 음성 모델 지원 * **다국어 지원**: 영어, 한국어, 스페인어, 일본어, 중국어 등 37개 언어 지원 * **감정 제어**: 이모션 프리셋(normal, happy, sad, angry, whisper, toneup, tonedown) 또는 스마트 문맥 인식 추론 * **오디오 커스터마이징**: 라우드니스(LUFS -70 to 0), 피치(-12 to +12 반음), 템포(0.5x to 2.0x), 형식(WAV/MP3) 제어 * **음성 검색**: 모델, 성별, 나이, 사용 사례별 필터링이 가능한 V2 Voices API * **Context 지원**: 취소 및 타임아웃을 위한 `context.Context` 완전 지원 * **타임스탬프 TTS**: 자막, 가라오케, 립싱크를 위한 단어·문자 단위 정렬 데이터 * **스트리밍**: 저지연 재생을 위한 실시간 청크 오디오 전송 * **의존성 없음**: Go 표준 라이브러리만 사용 ## 보이스 추천 원하는 스타일은 알지만 정확한 `voice_id`를 모를 때 `RecommendVoices`를 사용합니다. ```go theme={null} voices, err := client.RecommendVoices( context.Background(), "warm female voice for a product tutorial", 3, ) if err != nil { panic(err) } for _, voice := range voices { fmt.Println(voice.VoiceID, voice.VoiceName, voice.Score) } ``` 추천 결과에는 `VoiceID`, `VoiceName`, `Score`만 포함됩니다. 지원 모델, 감정, 성별, 연령대, 사용 사례 같은 상세 메타데이터가 필요하면 `GetVoiceV2` 또는 `GetVoicesV2`로 추가 조회하세요. ## 설정 환경 변수 또는 직접 전달로 API 키를 설정하세요: ```go theme={null} import typecast "github.com/neosapience/typecast-sdk/typecast-go" // 환경 변수 사용 (권장) // export TYPECAST_API_KEY="your-api-key-here" client := typecast.NewClient(nil) // 또는 직접 전달 client := typecast.NewClient(&typecast.ClientConfig{ APIKey: "your-api-key-here", }) // 사용자 정의 설정 client := typecast.NewClient(&typecast.ClientConfig{ APIKey: "your-api-key-here", BaseURL: "https://api.typecast.ai", // 선택사항 Timeout: 60 * time.Second, // 선택사항 }) ``` 자체 프록시를 통해 요청하는 경우 `BaseURL` 또는 `TYPECAST_API_HOST`를 프록시 엔드포인트로 설정하고 `APIKey`를 생략할 수 있습니다. API 키가 비어 있거나 없으면 SDK는 `X-API-KEY` 헤더를 보내지 않습니다. 기본 Typecast 호스트로 요청할 때는 API 키가 계속 필요합니다. ```go API 키 없는 프록시 theme={null} client := typecast.NewClient(&typecast.ClientConfig{ BaseURL: "https://your-proxy.example.com", }) ``` ### 환경 변수 | 변수 | 설명 | | ------------------- | ------------------------ | | `TYPECAST_API_KEY` | 타입캐스트 API 키 | | `TYPECAST_API_HOST` | 사용자 정의 API 기본 URL (선택사항) | ## 고급 사용법 ### 감정 제어 (ssfm-v30) ssfm-v30은 두 가지 감정 제어 모드를 제공합니다: **프리셋**과 **스마트**. AI가 문맥에서 감정을 추론하도록 합니다: ```go theme={null} response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "모든 것이 잘 될 거예요.", Model: typecast.ModelSSFMV30, Prompt: &typecast.SmartPrompt{ EmotionType: "smart", PreviousText: "방금 최고의 소식을 들었어요!", // 선택적 문맥 NextText: "축하하고 싶어요!", // 선택적 문맥 }, }) ``` 프리셋 값으로 감정을 명시적으로 설정합니다: ```go theme={null} intensity := 1.5 response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "이 기능들을 보여드리게 되어 정말 신나요!", Model: typecast.ModelSSFMV30, Prompt: &typecast.PresetPrompt{ EmotionType: "preset", EmotionPreset: typecast.EmotionHappy, // normal, happy, sad, angry, whisper, toneup, tonedown EmotionIntensity: &intensity, // 범위: 0.0 ~ 2.0 }, }) ``` ### 오디오 커스터마이징 라우드니스, 피치, 템포, 출력 형식을 제어합니다: ```go theme={null} lufs := -14.0 pitch := 2 tempo := 1.2 seed := uint32(42) response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "커스터마이즈된 오디오 출력!", Model: typecast.ModelSSFMV30, Output: &typecast.Output{ TargetLUFS: &lufs, // 범위: -70 ~ 0 (LUFS) AudioPitch: &pitch, // 범위: -12 to +12 반음 AudioTempo: &tempo, // 범위: 0.5x to 2.0x AudioFormat: typecast.AudioFormatMP3, // 옵션: WAV, MP3 }, Seed: &seed, // 재현 가능한 결과를 위해 }) os.WriteFile("output.mp3", response.AudioData, 0644) fmt.Printf("Format: %s\n", response.Format) ``` ### 파일로 바로 생성하기 `GenerateToFile`은 음성 합성과 파일 저장을 한 번에 처리합니다. `model`은 기본값으로 `ssfm-v30`을 사용하고, `.mp3` 또는 `.wav` 확장자로 출력 형식을 결정합니다. ```go theme={null} _, err := client.GenerateToFile(ctx, "output.mp3", typecast.GenerateToFileRequest{ Text: "안녕하세요, 타입캐스트입니다.", VoiceID: "tc_672c5f5ce59fac2a48faeaee", // voice_id는 https://typecast.ai/developers/api/voices 에서 확인하세요. }) if err != nil { panic(err) } ``` ### 텍스트만으로 쉼 표현 한 voice로 읽는 문장 안에 쉼만 넣고 싶다면 텍스트에 pause markup을 직접 작성합니다. `<|5s|>`, `<|1s|>`, `<|0.3s|>`, `<|0.34413s|>`처럼 쓰며 값은 초 단위이고 반드시 `s`로 끝납니다. 별도 pause 함수를 호출하지 않아도 텍스트만 보고 쉼 위치를 확인할 수 있습니다. ```go theme={null} audio, err := client.ComposeSpeech(). Defaults(typecast.ComposerSettings{VoiceID: "tc_672c5f5ce59fac2a48faeaee", Model: typecast.TTSModelSSFMV30}). Say("안녕하세요<|5s|>반갑습니다<|1s|>오늘<|2s|>날씨는 어떤 것 같으세요?"). Generate(ctx) ``` ### 다중 화자 합성 한 파일 안에서 서로 다른 voice나 구간별 pitch, tempo, prompt, seed 같은 옵션을 조합해야 할 때 사용합니다. composer는 각 구간을 WAV로 생성하고 앞뒤 무음 PCM 샘플을 trim한 뒤 합성합니다. MP3가 필요하면 먼저 WAV를 생성한 다음 앱 또는 서버 파이프라인에서 변환하세요. ```go theme={null} package main import ( "context" "os" typecast "github.com/neosapience/typecast-sdk/typecast-go" ) func main() { client := typecast.NewClient("YOUR_API_KEY") response, err := client.ComposeSpeech(). Defaults(typecast.ComposerSettings{VoiceID: "tc_672c5f5ce59fac2a48faeaee", Model: typecast.ModelSSFMV30}). Say("Hello there"). Pause(5). SayWith("Nice to meet you", typecast.ComposerSettings{VoiceID: "tc_60e5426de8b95f1d3000d7b5", Output: &typecast.Output{AudioPitch: 2}}). Say("Today"). Pause(2). Say("How does the weather feel?"). Generate(context.Background()) if err != nil { panic(err) } _ = os.WriteFile("conversation.wav", response.AudioData, 0644) } ``` ### 음성 검색 (V2 API) 향상된 메타데이터로 사용 가능한 음성을 나열하고 필터링합니다: ```go theme={null} // 모든 음성 가져오기 voices, err := client.GetVoicesV2(ctx, nil) // 조건별 필터링 voices, err := client.GetVoicesV2(ctx, &typecast.VoicesV2Filter{ Model: typecast.ModelSSFMV30, Gender: typecast.GenderFemale, Age: typecast.AgeYoungAdult, }) // 음성 정보 표시 for _, voice := range voices { fmt.Printf("ID: %s, Name: %s\n", voice.VoiceID, voice.VoiceName) if voice.Gender != nil { fmt.Printf("Gender: %s\n", *voice.Gender) } if voice.Age != nil { fmt.Printf("Age: %s\n", *voice.Age) } for _, model := range voice.Models { fmt.Printf("Model: %s, Emotions: %v\n", model.Version, model.Emotions) } } // 특정 음성 상세 정보 가져오기 voice, err := client.GetVoiceV2(ctx, "tc_672c5f5ce59fac2a48faeaee") ``` ### 다국어 콘텐츠 SDK는 자동 언어 감지를 통해 37개 언어를 지원합니다: ```go theme={null} // 언어 자동 감지 (권장) response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "こんにちは。お元気ですか。", Model: typecast.ModelSSFMV30, }) // 또는 언어 명시적으로 지정 response, err := client.TextToSpeech(ctx, &typecast.TTSRequest{ VoiceID: "tc_672c5f5ce59fac2a48faeaee", Text: "안녕하세요. 반갑습니다.", Model: typecast.ModelSSFMV30, Language: "kor", // ISO 639-3 언어 코드 }) ``` ### 스트리밍 저지연 재생을 위한 실시간 오디오 청크 스트리밍: ```go theme={null} // 원시 PCM 추출 (44바이트 WAV 헤더 건너뛰기) reader, _ := client.TextToSpeechStream(context.Background(), request) defer reader.Close() buf := make([]byte, 4096) first := true for { n, err := reader.Read(buf) if n > 0 { data := buf[:n] if first { data = data[44:] // WAV 헤더 건너뛰기 first = false } // data는 32000 Hz 16비트 모노 원시 PCM // 오디오 출력으로 전달 (예: oto, portaudio) _ = data } if err != nil { break } } ``` **WAV 스트리밍 형식:** 32000 Hz, 16비트, 모노 PCM. 첫 번째 청크에 44바이트 WAV 헤더(size = `0xFFFFFFFF`)가 포함되며, 이후 청크는 원시 PCM 데이터만 포함합니다. MP3 형식: 320 kbps, 44100 Hz, 각 청크는 독립적으로 디코딩 가능합니다. ## 타임스탬프 TTS `TextToSpeechWithTimestamps()`는 `POST /v1/text-to-speech/with-timestamps`를 래핑하며, 오디오와 함께 단어·문자 단위 정렬 데이터를 반환합니다. 가라오케 하이라이트, 자막 생성, 립싱크 애플리케이션에 활용할 수 있습니다. ### 기본 사용법 ```go theme={null} package main import ( "context" "fmt" "os" typecast "github.com/neosapience/typecast-sdk/typecast-go" ) func main() { client := typecast.NewClient(&typecast.ClientConfig{APIKey: "YOUR_API_KEY"}) ctx := context.Background() result, err := client.TextToSpeechWithTimestamps(ctx, &typecast.TTSRequestWithTimestamps{ VoiceID: "tc_60e5426de8b95f1d3000d7b5", Text: "Hello. How are you?", Model: typecast.ModelSSFMV30, }) if err != nil { panic(err) } os.WriteFile("output.wav", result.AudioBytes(), 0644) fmt.Printf("재생 시간: %.3f초\n", result.AudioDuration) for _, w := range result.Words { fmt.Printf(" [%.3fs – %.3fs] %s\n", w.StartTime, w.EndTime, w.Text) } } ``` ### 정밀도(Granularity) 설정 `Granularity: typecast.GranularityWord`(기본값) 또는 `Granularity: typecast.GranularityChar`를 전달해 정렬 단위를 제어합니다. ```go theme={null} // 문자 단위 정렬 — 일본어·중국어에 필수 result, err := client.TextToSpeechWithTimestamps(ctx, &typecast.TTSRequestWithTimestamps{ VoiceID: "tc_60e5426de8b95f1d3000d7b5", Text: "Hello. How are you?", Model: typecast.ModelSSFMV30, Granularity: typecast.GranularityChar, }) ``` ### 자막 내보내기 ```go theme={null} srt, _ := result.ToSrt() os.WriteFile("output.srt", []byte(srt), 0644) vtt, _ := result.ToVtt() os.WriteFile("output.vtt", []byte(vtt), 0644) ``` **일본어·중국어:** 공백 구분자가 없는 언어(jpn, zho)는 단어 단위 세그먼트가 의미를 갖지 않습니다. 해당 언어에는 `GranularityChar`를 사용해 문자 단위 정렬 데이터를 얻으세요. ## 지원 언어 SDK는 자동 언어 감지를 통해 37개 언어를 지원합니다: | 코드 | 언어 | 코드 | 언어 | 코드 | 언어 | | ----- | ----- | ----- | ------ | ----- | ------ | | `eng` | 영어 | `jpn` | 일본어 | `ukr` | 우크라이나어 | | `kor` | 한국어 | `ell` | 그리스어 | `ind` | 인도네시아어 | | `spa` | 스페인어 | `tam` | 타밀어 | `dan` | 덴마크어 | | `deu` | 독일어 | `tgl` | 타갈로그어 | `swe` | 스웨덴어 | | `fra` | 프랑스어 | `fin` | 핀란드어 | `msa` | 말레이어 | | `ita` | 이탈리아어 | `zho` | 중국어 | `ces` | 체코어 | | `pol` | 폴란드어 | `slk` | 슬로바키아어 | `por` | 포르투갈어 | | `nld` | 네덜란드어 | `ara` | 아랍어 | `bul` | 불가리아어 | | `rus` | 러시아어 | `hrv` | 크로아티아어 | `ron` | 루마니아어 | | `ben` | 벵골어 | `hin` | 힌디어 | `hun` | 헝가리어 | | `nan` | 민난어 | `nor` | 노르웨이어 | `pan` | 펀자브어 | | `tha` | 태국어 | `tur` | 터키어 | `vie` | 베트남어 | | `yue` | 광동어 | | | | | 지정하지 않으면 입력 텍스트에서 자동으로 언어가 감지됩니다. ## 오류 처리 SDK는 특정 오류를 처리하기 위한 헬퍼 메서드가 있는 `APIError` 타입을 제공합니다: ```go theme={null} import typecast "github.com/neosapience/typecast-sdk/typecast-go" response, err := client.TextToSpeech(ctx, request) if err != nil { if apiErr, ok := err.(*typecast.APIError); ok { fmt.Printf("Error %d: %s\n", apiErr.StatusCode, apiErr.Message) // 특정 오류 처리 switch { case apiErr.IsUnauthorized(): // 401: 잘못된 API 키 case apiErr.IsForbidden(): // 403: 접근 거부 case apiErr.IsPaymentRequired(): // 402: 크레딧 부족 case apiErr.IsNotFound(): // 404: 리소스를 찾을 수 없음 case apiErr.IsValidationError(): // 422: 유효성 검사 오류 case apiErr.IsRateLimited(): // 429: 요청 제한 초과 case apiErr.IsServerError(): // 5xx: 서버 오류 case apiErr.IsBadRequest(): // 400: 잘못된 요청 } } } ``` ### 오류 유형 | 메서드 | 상태 코드 | 설명 | | --------------------- | ----- | --------------- | | `IsBadRequest()` | 400 | 잘못된 요청 매개변수 | | `IsUnauthorized()` | 401 | 잘못되거나 누락된 API 키 | | `IsPaymentRequired()` | 402 | 크레딧 부족 | | `IsForbidden()` | 403 | 접근 거부 | | `IsNotFound()` | 404 | 리소스를 찾을 수 없음 | | `IsValidationError()` | 422 | 유효성 검사 오류 | | `IsRateLimited()` | 429 | 요청 제한 초과 | | `IsServerError()` | 5xx | 서버 오류 | ## Context와 타임아웃 SDK는 취소 및 타임아웃을 위한 Go의 `context.Context`를 완전히 지원합니다: ```go theme={null} // 타임아웃 사용 ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel() response, err := client.TextToSpeech(ctx, request) if err != nil { if ctx.Err() == context.DeadlineExceeded { fmt.Println("Request timed out") } } // 취소 사용 ctx, cancel := context.WithCancel(context.Background()) go func() { time.Sleep(5 * time.Second) cancel() // 5초 후 취소 }() response, err := client.TextToSpeech(ctx, request) ``` ## API 레퍼런스 ### 클라이언트 메서드 | 메서드 | 설명 | | ------------------------------------ | ------------------------- | | `TextToSpeech(ctx, request)` | 텍스트를 음성 오디오로 변환 | | `GenerateToFile(ctx, path, request)` | 음성을 생성하고 로컬 파일로 바로 저장 | | `GetVoicesV2(ctx, filter)` | 필터링으로 사용 가능한 음성 가져오기 | | `GetVoiceV2(ctx, voiceID)` | ID로 특정 음성 가져오기 | | `GetVoices(ctx, model)` | 음성 가져오기 (V1 API, 권장하지 않음) | | `GetVoice(ctx, voiceID, model)` | 음성 가져오기 (V1 API, 권장하지 않음) | ### TTSRequest 필드 | 필드 | 타입 | 필수 | 설명 | | ---------- | -------------------------------------------- | -- | ----------------------------------------- | | `VoiceID` | `string` | ✓ | 음성 ID (형식: `tc_*` 또는 `uc_*`) | | `Text` | `string` | ✓ | 합성할 텍스트 (최대 2000자) | | `Model` | `TTSModel` | ✓ | TTS 모델 (`ModelSSFMV21` 또는 `ModelSSFMV30`) | | `Language` | `string` | | ISO 639-3 코드 (생략 시 자동 감지) | | `Prompt` | `*Prompt` / `*PresetPrompt` / `*SmartPrompt` | | 감정 설정 | | `Output` | `*Output` | | 오디오 출력 설정 | | `Seed` | `*uint32` | | 재현성을 위한 부호 없는 정수 시드 (≥ 0) | ### TTSResponse 필드 | 필드 | 타입 | 설명 | | ----------- | ------------- | ----------------------- | | `AudioData` | `[]byte` | 생성된 오디오 데이터 | | `Duration` | `float64` | 오디오 길이 (초) | | `Format` | `AudioFormat` | 오디오 형식 (`wav` 또는 `mp3`) | ### 상수 #### 모델 | 상수 | 값 | 설명 | | -------------- | ---------- | ------------- | | `ModelSSFMV30` | `ssfm-v30` | 향상된 운율의 최신 모델 | | `ModelSSFMV21` | `ssfm-v21` | 안정적인 프로덕션 모델 | #### 감정 프리셋 | 상수 | ssfm-v21 | ssfm-v30 | | ----------------- | -------- | -------- | | `EmotionNormal` | ✓ | ✓ | | `EmotionHappy` | ✓ | ✓ | | `EmotionSad` | ✓ | ✓ | | `EmotionAngry` | ✓ | ✓ | | `EmotionWhisper` | ✗ | ✓ | | `EmotionToneUp` | ✗ | ✓ | | `EmotionToneDown` | ✗ | ✓ | #### 오디오 형식 | 상수 | 값 | 설명 | | ---------------- | ----- | ----------- | | `AudioFormatWAV` | `wav` | 비압축 PCM 오디오 | | `AudioFormatMP3` | `mp3` | 압축된 MP3 오디오 |