이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
Python SDK
pip install supertone — 동기 및 비동기 클라이언트, 병렬 자동 청크 분할.TypeScript SDK
npm add @supertone/supertone — Promise 기반, ESM/CJS, Node 및 Bun 지원.CLI
pip install supertone-cli — 터미널에서 합성·스트리밍·일괄 처리 및 보이스 관리.MCP
uvx supertone-mcp — Claude, Cursor 등 AI 에이전트를 위한 조립형 도구.무엇을 사용해야 하나요?
| 하고 싶은 것 | 사용 | 대상 |
|---|---|---|
| Python 또는 Node 코드에서 Supertone 호출 | Python / TypeScript SDK | 애플리케이션 개발자 |
| 셸, 스크립트, CI에서 오디오 생성·일괄 처리 | CLI | DevOps, 콘텐츠/스크립팅 |
| AI 에이전트가 보이스를 찾고 음성을 합성하도록 | MCP 서버 | Claude / Cursor / 에이전트 사용자 |
| SDK가 없는 언어 사용, 또는 와이어 포맷 직접 제어 | REST API | 모든 런타임 |
각 도구가 제공하는 것
SDK (Python & TypeScript) — 애플리케이션 코드를 위한 관용적 클라이언트입니다. 인증 처리, 타입 안전 모델·enum, 오디오 청크 스트리밍, 긴 텍스트 자동 청크 분할(300자 단위로 나눠 투명하게 병합), HTTP 상태 코드에 매핑된 타입 기반 오류, 백오프 기반의 설정 가능한 재시도를 제공합니다. 자세한 기능 표는 각 SDK 페이지에 있습니다. CLI — 터미널과 스크립트에서 쓰는 API입니다. 문자열·파일·표준 입력으로 합성하고, 스피커로 스트리밍하고, 디렉터리 전체를 일괄 처리하고, 보이스를 관리·복제하고, 사용량 조회와 길이 예측을 할 수 있습니다.--format json 출력은 파이프 친화적이라 자동화에 적합하며, 관용적인 종료 코드로 스크립트에서 실패를 분기 처리할 수 있습니다.
MCP 서버 — AI 에이전트(Claude, Cursor 등 MCP 클라이언트)가 Supertone를 구동하도록 하는 조립형 도구입니다. 에이전트는 보이스를 검색·미리듣기하고, 비용을 추정하고, 보이스를 복제하고, 음성을 합성하며 — 이 단계들을 스스로 다단계 워크플로로 연결합니다.
REST API를 직접 사용해야 할 때
REST API는 SDK가 공개되지 않은 언어와 런타임(Go, Java, PHP, Rust, 임베디드 시스템 등)에서 사용할 수 있으며, 와이어 포맷을 최대한 직접 제어하고 싶을 때도 사용할 수 있습니다. 엔드포인트는 API 레퍼런스에 문서화되어 있으며, 해당 섹션의 예제에는curl, JavaScript, Go, Python, PHP, Java가 포함되어 있습니다.
REST를 직접 호출하는 경우, 청크 분할, 재시도, 스트리밍 소비를 직접 구현해야 합니다.