타입캐스트 API를 위한 공식 PHP 라이브러리입니다. AI 음성을 사용하여 텍스트를 자연스러운 음성으로 변환합니다.
Guzzle 7 기반의 안정적인 HTTP 통신. PHP 8.1+ 및 Composer 필요.
Composer로 설치합니다:
composer require neosapience/typecast-php
PHP 8.1 이상 및 Composer가 필요합니다. php -v로 버전을 확인하세요.
빠른 시작
<?php
use Neosapience\Typecast\TypecastClient;
use Neosapience\Typecast\Models\TTSRequest;
// 클라이언트 초기화
$client = new TypecastClient(apiKey: 'YOUR_API_KEY');
// 텍스트를 음성으로 변환
$response = $client->textToSpeech(new TTSRequest(
voiceId: 'tc_672c5f5ce59fac2a48faeaee',
text: '안녕하세요! 타입캐스트 PHP SDK입니다.',
model: 'ssfm-v30',
));
// 오디오 파일 저장
file_put_contents('output.wav', $response->audioData);
echo "재생 시간: {$response->duration}초, 포맷: {$response->format}\n";
- 다중 음성 모델:
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로 모델, 성별, 나이, 용도별 필터링
- 스트리밍: 저지연 재생을 위한 실시간 청크 오디오 전송 (콜백 기반)
- Guzzle 7: 업계 표준 HTTP 클라이언트
- 타입 안전성: 타입 프로퍼티와 네임드 아규먼트 (PHP 8.1+)
환경변수 또는 직접 API 키를 전달할 수 있습니다:
export TYPECAST_API_KEY="your-api-key-here"
고급 사용법
감정 제어 (ssfm-v30)
ssfm-v30은 두 가지 감정 제어 모드를 제공합니다: 프리셋 및 스마트.
AI가 문맥에서 감정을 추론합니다:use Neosapience\Typecast\Models\{TTSRequest, SmartPrompt};
$response = $client->textToSpeech(new TTSRequest(
voiceId: 'tc_672c5f5ce59fac2a48faeaee',
text: '모든 것이 잘 될 거예요.',
model: 'ssfm-v30',
prompt: new SmartPrompt(
previousText: '방금 최고의 소식을 들었어요!',
nextText: '축하하고 싶어요!',
),
));
프리셋 값으로 감정을 명시적으로 설정합니다:use Neosapience\Typecast\Models\{TTSRequest, PresetPrompt};
$response = $client->textToSpeech(new TTSRequest(
voiceId: 'tc_672c5f5ce59fac2a48faeaee',
text: '이 기능들을 보여드리게 되어 정말 기쁩니다!',
model: 'ssfm-v30',
prompt: new PresetPrompt(
emotionPreset: 'happy',
emotionIntensity: 1.5,
),
));
오디오 커스터마이징
음량, 피치, 템포, 출력 포맷을 제어합니다:
use Neosapience\Typecast\Models\{TTSRequest, Output};
$response = $client->textToSpeech(new TTSRequest(
voiceId: 'tc_672c5f5ce59fac2a48faeaee',
text: '커스터마이징된 오디오 출력!',
model: 'ssfm-v30',
output: new Output(
targetLufs: -14.0,
audioPitch: 2,
audioTempo: 1.2,
audioFormat: 'mp3',
),
seed: 42,
));
file_put_contents('output.mp3', $response->audioData);
보이스 탐색 (V2 API)
향상된 메타데이터와 함께 사용 가능한 보이스를 조회합니다:
use Neosapience\Typecast\Models\VoicesV2Filter;
// 모든 보이스 조회
$voices = $client->getVoicesV2();
// 필터링
$filtered = $client->getVoicesV2(new VoicesV2Filter(
model: 'ssfm-v30',
gender: 'female',
age: 'young_adult',
));
foreach ($voices as $voice) {
echo "ID: {$voice->voiceId}, 이름: {$voice->voiceName}\n";
}
// 특정 보이스 조회
$voice = $client->getVoiceV2('tc_672c5f5ce59fac2a48faeaee');
스트리밍
콜백을 통해 실시간으로 오디오 청크를 스트리밍합니다:
use Neosapience\Typecast\Models\TTSRequestStream;
$first = true;
$client->textToSpeechStream(
new TTSRequestStream(
voiceId: 'tc_672c5f5ce59fac2a48faeaee',
text: '이 텍스트를 실시간으로 오디오로 스트리밍합니다.',
model: 'ssfm-v30',
),
function (string $chunk) use (&$first): void {
if ($first) {
$chunk = substr($chunk, 44); // 44바이트 WAV 헤더 건너뛰기
$first = false;
}
// $chunk는 32000 Hz 16비트 모노 원시 PCM
// 오디오 출력으로 전달 또는 ffplay로 파이핑
},
);
WAV 스트리밍 형식: 32000 Hz, 16비트, 모노 PCM. 첫 번째 청크에 44바이트 WAV 헤더(size = 0xFFFFFFFF)가 포함되며, 이후 청크는 원시 PCM 데이터만 포함합니다. MP3 형식: 320 kbps, 44100 Hz, 각 청크는 독립적으로 디코딩 가능합니다. 스트리밍 엔드포인트는 volume 및 target_lufs를 지원하지 않습니다.
지원 언어
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는 HTTP 에러별 구체적인 예외를 발생시킵니다:
use Neosapience\Typecast\Exceptions\{
TypecastException,
UnauthorizedException,
PaymentRequiredException,
RateLimitException,
};
try {
$response = $client->textToSpeech($request);
} catch (UnauthorizedException $e) {
echo "유효하지 않은 API 키: {$e->getMessage()}\n";
} catch (PaymentRequiredException $e) {
echo "크레딧 부족\n";
} catch (RateLimitException $e) {
echo "요청 한도 초과 - 잠시 후 재시도\n";
} catch (TypecastException $e) {
echo "에러: {$e->getMessage()}\n";
}
| 예외 | 상태 코드 | 설명 |
|---|
BadRequestException | 400 | 잘못된 요청 파라미터 |
UnauthorizedException | 401 | 유효하지 않거나 누락된 API 키 |
PaymentRequiredException | 402 | 크레딧 부족 |
NotFoundException | 404 | 리소스를 찾을 수 없음 |
UnprocessableEntityException | 422 | 유효성 검사 오류 |
RateLimitException | 429 | 요청 한도 초과 |
InternalServerException | 500 | 서버 오류 |
API 레퍼런스
TypecastClient 메서드
| 메서드 | 설명 |
|---|
textToSpeech(TTSRequest) | 텍스트를 음성 오디오로 변환 |
textToSpeechStream(TTSRequestStream, callable) | 콜백을 통한 오디오 청크 스트리밍 |
getMySubscription() | 구독 정보 조회 |
getVoices(?string $model) | 사용 가능한 보이스 조회 (V1) |
getVoicesV2(?VoicesV2Filter) | 메타데이터와 함께 보이스 조회 (V2) |
getVoiceV2(string $voiceId) | 특정 보이스 조회 |
