> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Supertone CLI로 터미널에서 음성을 생성·스트리밍·일괄 처리하고 보이스를 관리하세요 — 빠른 시작, 명령어, 레시피, 문제 해결.

> [!NOTE]
>
> 이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/developer-tools/cli)을 함께 확인해 주세요.

코드 없이 터미널에서 바로 텍스트를 음성으로 변환하세요. Supertone CLI는 문자열·파일·표준 입력(stdin)으로 합성하고, 스피커로 실시간 스트리밍하고, 디렉터리 전체를 일괄 처리하고, 보이스·사용량·크레딧을 관리합니다.

소스: [supertone-inc/supertone-cli](https://github.com/supertone-inc/supertone-cli).

## 빠른 시작

**1. 설치**

```bash theme={"dark"}
pip install "supertone-cli[stream]"
```

Python 3.12+ 필요. `[stream]` 추가 옵션은 실시간 재생을 더합니다.

**2. API 키 설정**

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

**3. 소리 듣기**

```bash theme={"dark"}
supertone tts "터미널에서 내뱉는 첫 마디." \
  --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
```

소리가 들리면 준비 완료입니다. ✅

> [!NOTE]
>
> 애플리케이션 코드에 통합하시나요? [Python](/ko/docs/developer-tools/python) 또는 [TypeScript](/ko/docs/developer-tools/typescript) SDK를 사용하세요. AI 에이전트용은 [MCP](/ko/docs/developer-tools/mcp)를 참고하세요.

## 설치

**pip**

```bash theme={"dark"}
pip install supertone-cli
```

**스트리밍 포함**

```bash theme={"dark"}
pip install "supertone-cli[stream]"
```

Python 3.12+ 필요. `[stream]` 추가 옵션은 `--stream`을 통한 시스템 스피커 실시간 재생을 활성화합니다.

## 인증

**환경 변수**

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

**설정 파일**

```bash theme={"dark"}
supertone config init             # 대화형 설정
supertone config set api_key Kp9mZ3xQ7v...
```

`~/.config/supertone/config.toml`에 저장됩니다.

> **기본값을 설정해 입력 줄이기**
>
> 기본값을 한 번 저장해 두면 매 호출마다 해당 플래그를 생략할 수 있습니다:
>
> | 설정 키 | 생략 시 사용처 | 기본값 |
> | - | - | - |
> | `api_key` | 항상 | — |
> | `default_voice` | `--voice` 미지정 시 | — |
> | `default_model` | `--model` 미지정 시 | `sona_speech_2` |
> | `default_lang` | `--lang` 미지정 시 | `ko` |
>
> ```bash theme={"dark"}
> supertone config set default_voice 20160a4c5ba38967330c84
> supertone config set default_lang en
> ```

## 음성 합성

```bash theme={"dark"}
# 문자열로부터
supertone tts "터미널에서 안녕하세요." --voice VOICE_ID -o output.wav

# 파일로부터
supertone tts -i input.txt -v VOICE_ID -o output.wav

# 표준 입력(stdin)으로부터 — 파이프 친화적
echo "파이프로 전달된 텍스트." | supertone tts -v VOICE_ID -o output.wav

# 저장 대신 실시간 재생 ([stream] 추가 옵션 필요)
supertone tts "이건 실시간으로 재생됩니다." -v VOICE_ID -m sona_speech_1 --stream

# 포맷·보이스 설정 조정
supertone tts "더 느리고 더 낮게." -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# 폴더 전체 일괄 처리 — 입력마다 오디오 파일 하나
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID
```

## 보이스 관리

```bash theme={"dark"}
supertone voices list                                  # Supertone 제공 프리셋 보이스
supertone voices list --type custom                    # 내가 복제한 보이스만
supertone voices search --lang en --gender female      # 프리셋 필터링
supertone voices get VOICE_ID                         # 상세 정보
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yes는 확인 절차 생략
```

## 길이 예측 및 사용량 추적

`tts-predict`는 크레딧을 **소모하지 않고** 길이와 크레딧 비용을 추정합니다 — 대량 일괄 처리 전에 유용합니다.

```bash theme={"dark"}
supertone tts-predict "이건 얼마나 길까요?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30
```

## 레시피

> **스크립트 폴더를 한 번에 내레이션**
>
> `.txt` 파일을 한 디렉터리에 모아 한꺼번에 합성합니다:
>
> ```bash theme={"dark"}
> supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
> ```

> **LLM 출력을 실시간으로 읽기**
>
> 어떤 명령의 출력이든 실시간 음성으로 파이프합니다:
>
> ```bash theme={"dark"}
> my-llm "오늘 헤드라인 요약해줘" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
> ```

> **jq로 커스텀 보이스 찾기**
>
> `--format json`은 모든 읽기 명령을 스크립트화할 수 있게 합니다:
>
> ```bash theme={"dark"}
> supertone voices list --type custom --format json | jq '.[].name'
> ```

> **일괄 처리 전 비용 추정**
>
> 입력을 순회하며 예측 길이를 합산해 크레딧 소모 전에 가늠합니다:
>
> ```bash theme={"dark"}
> for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done
> ```

## 레퍼런스

> **지원 모델**
>
> `sona_speech_1`, `sona_speech_2`, `sona_speech_2_flash`, `sona_speech_2t`, `supertonic_api_1`, `supertonic_api_3`. 각 모델의 기능과 장단점은 [모델](/ko/docs/core-concepts/models)을 참고하세요.

> **종료 코드**
>
> | 코드 | 의미 |
> | - | - |
> | `0` | 성공 |
> | `1` | API 오류 |
> | `2` | 인증 오류 |
> | `3` | 입력 검증 오류 |
> | `130` | 중단됨 (Ctrl-C) |

## 문제 해결

> **command not found: supertone**
>
> 설치 디렉터리가 `PATH`에 없거나, 활성화되지 않은 가상환경에 설치된 경우입니다. 가상환경을 다시 활성화하거나, `pip install --user supertone-cli`로 재설치하고 사용자 스크립트 디렉터리를 `PATH`에 추가하세요.

> **인증 오류 (종료 코드 2)**
>
> API 키가 없거나 잘못되었습니다. `echo $SUPERTONE_API_KEY`로 확인하거나 `supertone config set api_key your-api-key`를 실행하세요. 키는 [Developer Console](https://console.supertoneapi.com)에서 발급받습니다.

> **--stream에서 소리가 안 남**
>
> 실시간 재생에는 스트리밍 추가 옵션(`pip install "supertone-cli[stream]"`)과 **`sona_speech_1` 모델**이 필요합니다 — `-m sona_speech_1`을 전달하세요. 다른 모델은 *"Streaming requires sona\_speech\_1"* 오류를 내며, 그 경우 `-o output.wav`로 파일에 저장하세요.

> **크레딧 소진 (402)**
>
> 잔액이 바닥나면 합성이 중단됩니다. `supertone usage balance`로 확인하고 [Developer Console](https://console.supertoneapi.com)에서 충전하세요.

## 관련 문서

> **[MCP](/ko/docs/developer-tools/mcp)**
>
> Model Context Protocol을 통해 AI 에이전트가 Supertone를 호출하도록 합니다.

> **[Python SDK](/ko/docs/developer-tools/python)**
>
> 애플리케이션 코드를 위한 동일한 API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.