메인 콘텐츠로 건너뛰기
타입캐스트 API를 위한 공식 Ruby SDK입니다. AI 음성을 사용해 텍스트를 자연스러운 음성으로 변환하고, 타임스탬프, 캐릭터 조회, 커스텀 보이스 생성 기능을 사용할 수 있습니다. Ruby SDK는 런타임 의존성 없이 Ruby 표준 라이브러리만 사용하며 Ruby 2.6 이상을 지원합니다.

RubyGems

타입캐스트 Ruby SDK

소스 코드

타입캐스트 Ruby SDK 소스 코드

​
설치

RubyGems에서 설치합니다: 
gem install typecast-ruby
또는 Gemfile에 추가합니다: 
gem "typecast-ruby", "~> 0.1.2"
Ruby 2.6 이상이 필요합니다. ruby -v로 버전을 확인하세요.

​
빠른 시작

require "typecast"

client = Typecast::Client.new(api_key: ENV["TYPECAST_API_KEY"])

response = client.text_to_speech(
  Typecast::Models::TTSRequest.new(
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    text: "안녕하세요! 타입캐스트 Ruby SDK입니다.",
    model: Typecast::Models::TTS_MODEL_V30,
    language: "kor",
    output: Typecast::Models::Output.new(audio_format: "wav")
  )
)

File.binwrite("output.wav", response.audio_data)
puts "재생 시간: #{response.duration}초, 포맷: #{response.format}"

​
기능

  • 다중 음성 모델: ssfm-v30 및 ssfm-v21 AI 음성 모델 지원
  • 다국어 지원: 영어, 한국어, 일본어, 중국어, 스페인어 등 37개 언어
  • 감정 제어: 프리셋 감정 또는 스마트 문맥 인식 추론
  • 오디오 커스터마이징: 음량, 피치, 템포, 출력 포맷 제어
  • 캐릭터 탐색: V2 Voices API로 모델, 성별, 나이, 용도별 필터링
  • 스트리밍 엔드포인트: Ruby에서 스트리밍 TTS 응답 사용
  • 타임스탬프 TTS: SRT/VTT 헬퍼가 포함된 단어·문자 단위 정렬 데이터
  • 즉시 보이스 클로닝: WAV 샘플을 업로드해 커스텀 보이스 ID 생성
  • 런타임 의존성 없음: Ruby 표준 라이브러리 net/http 기반

​
설정

환경변수 또는 생성자에 API 키를 직접 전달할 수 있습니다: 
export TYPECAST_API_KEY="your-api-key-here"
자체 프록시를 통해 요청하는 경우 base_url을 프록시 엔드포인트로 설정하고 api_key를 생략할 수 있습니다. API 키가 비어 있거나 없으면 SDK는 X-API-KEY 헤더를 보내지 않습니다. 기본 Typecast 호스트로 요청할 때는 API 키가 계속 필요합니다.
API 키 없는 프록시
client = Typecast::Client.new(
  base_url: "https://your-proxy.example.com"
)
API 호스트와 HTTP 타임아웃도 설정할 수 있습니다: 
client = Typecast::Client.new(
  api_key: ENV["TYPECAST_API_KEY"],
  base_url: "https://api.typecast.ai",
  open_timeout: 10,
  read_timeout: 30
)

​
고급 사용법

​
감정 제어 (ssfm-v30)

ssfm-v30은 두 가지 감정 제어 모드를 제공합니다: 프리셋 및 스마트.
AI가 문맥에서 감정을 추론합니다:
response = client.text_to_speech(
  Typecast::Models::TTSRequest.new(
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    text: "모든 것이 잘 될 거예요.",
    model: Typecast::Models::TTS_MODEL_V30,
    prompt: Typecast::Models::SmartPrompt.new(
      previous_text: "방금 최고의 소식을 들었어요!",
      next_text: "축하하고 싶어요!"
    )
  )
)

​
오디오 커스터마이징

음량, 피치, 템포, 출력 포맷을 제어합니다: 
response = client.text_to_speech(
  Typecast::Models::TTSRequest.new(
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    text: "커스터마이징된 오디오 출력!",
    model: Typecast::Models::TTS_MODEL_V30,
    output: Typecast::Models::Output.new(
      target_lufs: -14.0,
      audio_pitch: 2,
      audio_tempo: 1.2,
      audio_format: Typecast::Models::AUDIO_MP3
    ),
    seed: 42
  )
)

File.binwrite("output.mp3", response.audio_data)

​
파일로 바로 생성하기

generate_to_file은 음성 합성과 파일 저장을 한 번에 처리합니다. model은 기본값으로 ssfm-v30을 사용하고, .mp3 또는 .wav 확장자로 출력 형식을 결정합니다. 
client.generate_to_file(
  "hello.mp3",
  text: "안녕하세요, 타입캐스트입니다.",
  voice_id: "tc_672c5f5ce59fac2a48faeaee" # voice_id는 https://typecast.ai/developers/api/voices 에서 확인하세요.
)

​
캐릭터 탐색 (V2 API)

향상된 메타데이터와 함께 사용 가능한 캐릭터를 조회합니다: 
voices = client.get_voices_v2

filtered = client.get_voices_v2(
  Typecast::Models::VoicesV2Filter.new(
    model: Typecast::Models::TTS_MODEL_V30,
    gender: "female",
    age: "young_adult"
  )
)

voices.each do |voice|
  puts "ID: #{voice.voice_id}, 이름: #{voice.voice_name}"
  puts "성별: #{voice.gender}, 나이: #{voice.age}"
end

voice = client.get_voice_v2("tc_672c5f5ce59fac2a48faeaee")
puts voice.voice_name

​
스트리밍

text_to_speech_stream()으로 스트리밍 엔드포인트를 호출합니다: 
client.text_to_speech_stream(
  Typecast::Models::TTSRequestStream.new(
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    text: "이 텍스트를 오디오로 스트리밍합니다.",
    model: Typecast::Models::TTS_MODEL_V30,
    output: Typecast::Models::OutputStream.new(audio_format: "wav")
  )
) do |audio|
  File.binwrite("stream.wav", audio)
end
WAV 스트리밍 형식: 32000 Hz, 16비트, 모노 PCM. 첫 번째 청크에 44바이트 WAV 헤더(size = 0xFFFFFFFF)가 포함되며, 이후 청크는 원시 PCM 데이터만 포함합니다.

​
타임스탬프 TTS

text_to_speech_with_timestamps()는 POST /v1/text-to-speech/with-timestamps를 래핑하며, 오디오와 함께 단어·문자 단위 정렬 데이터를 반환합니다. 
result = client.text_to_speech_with_timestamps(
  Typecast::Models::TTSRequest.new(
    voice_id: "tc_60e5426de8b95f1d3000d7b5",
    text: "안녕하세요. 반갑습니다.",
    model: Typecast::Models::TTS_MODEL_V30,
    language: "kor"
  )
)

result.save_audio("output.wav")
puts "재생 시간: #{result.audio_duration}초"

result.words.each do |word|
  puts "[#{word.start_time}초 - #{word.end_time}초] #{word.word}"
end

​
정밀도(Granularity) 설정

granularity: "word"(기본값) 또는 granularity: "char"를 설정해 정렬 단위를 제어합니다. 
result = client.text_to_speech_with_timestamps(
  Typecast::Models::TTSRequest.new(
    voice_id: "tc_60e5426de8b95f1d3000d7b5",
    text: "안녕하세요. 반갑습니다.",
    model: Typecast::Models::TTS_MODEL_V30,
    language: "kor"
  ),
  granularity: "char"
)

​
자막 내보내기

File.write("output.srt", result.to_srt)
File.write("output.vtt", result.to_vtt)

​
즉시 보이스 클로닝

짧은 WAV 샘플을 업로드해 커스텀 보이스를 생성합니다: 
voice = client.clone_voice(
  audio: File.binread("sample.wav"),
  filename: "sample.wav",
  name: "My Voice",
  model: Typecast::Models::TTS_MODEL_V30
)

puts "커스텀 보이스 ID: #{voice.voice_id}"
보이스 클로닝 오디오는 25 MB 이하여야 하며, 커스텀 보이스 이름은 1-30자여야 합니다.