> ## 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.

# 변경 로그

> 타입캐스트 Text-to-Speech API의 변경 사항 및 업데이트

<Update label="2026년 4월" tags={["API","SDK","타임스탬프"]} description="타임스탬프 TTS & SDK v0.3/0.4 릴리스">
  ### 새 엔드포인트: POST /v1/text-to-speech/with-timestamps

  단일 응답으로 합성된 오디오와 단어·문자 단위 정렬 데이터를 함께 반환합니다. 자동 자막, 가라오케 하이라이트, 립싱크 애니메이션 등에 활용하기 좋습니다.

  ```text theme={null}
  POST /v1/text-to-speech/with-timestamps
  ```

  **요청 스키마:**

  ```json theme={null}
  {
    "voice_id": "tc_60e5426de8b95f1d3000d7b5",
    "text": "안녕?",
    "model": "ssfm-v30"
  }
  ```

  **응답 스키마 (요약):**

  ```json theme={null}
  {
    "audio": "<base64>",
    "audio_format": "wav",
    "audio_duration": 0.52,
    "words": [
      { "text": "안녕?", "start": 0.0, "end": 0.52 }
    ],
    "characters": [
      { "text": "안", "start": 0.0, "end": 0.2 },
      { "text": "녕", "start": 0.2, "end": 0.45 },
      { "text": "?", "start": 0.45, "end": 0.52 }
    ]
  }
  ```

  **`granularity` 파라미터:**

  `granularity`는 선택 파라미터이며, 생략하면 단어 단위 정렬과 문자 단위 정렬을 함께 응답합니다.

  | 값      | 설명                                         |
  | :----- | :----------------------------------------- |
  | `word` | 단어 단위 정렬. 공백이 있는 언어에 권장됩니다.                |
  | `char` | 문자 단위 정렬. 일본어(`jpn`) 및 중국어(`zho`)에는 필수입니다. |

  **캡션 분할 규칙:** 문장 종결 기호(`. ? ! 。 ？ ！`)에서 분할하며, 큐당 7초/42자 상한선을 적용합니다(BBC/Netflix 자막 가이드라인).

  ### SDK 업데이트 — 타임스탬프 TTS 전 11개 SDK에 추가

  | SDK        | 버전     | 메서드                                         |
  | :--------- | :----- | :------------------------------------------ |
  | Python     | 0.3.0  | `text_to_speech_with_timestamps()`          |
  | JavaScript | 0.4.0  | `textToSpeechWithTimestamps()`              |
  | Go         | v0.3.0 | `TextToSpeechWithTimestamps()`              |
  | Rust       | 0.3.0  | `text_to_speech_with_timestamps()`          |
  | Swift      | v0.3.0 | `textToSpeechWithTimestamps()`              |
  | C#         | 0.3.0  | `TextToSpeechWithTimestampsAsync()`         |
  | Java       | 1.2.0  | `textToSpeechWithTimestamps()`              |
  | Kotlin     | 1.2.0  | `textToSpeechWithTimestamps()`              |
  | C          | 1.2.0  | `typecast_text_to_speech_with_timestamps()` |
  | Zig        | v0.2.0 | `textToSpeechWithTimestamps()`              |
  | PHP        | v0.1.0 | `textToSpeechWithTimestamps()`              |

  모든 SDK 응답 객체에는 `toSrt()` / `toVtt()` 자막 내보내기 헬퍼와 `saveAudio(path)` / `audio_bytes()` 편의 메서드가 포함되어 있습니다.
</Update>

<Update label="2026년 4월" tags={["API","SDK","스트리밍"]} description="스트리밍 TTS & 구독 API">
  ### 새 엔드포인트: POST /v1/text-to-speech/stream

  전체 합성을 기다리지 않고 생성되는 오디오 청크를 실시간으로 전달하는 저지연 스트리밍 엔드포인트가 추가되었습니다.

  ```text theme={null}
  POST /v1/text-to-speech/stream
  ```

  **`/v1/text-to-speech`와의 주요 차이점:**

  | 기능            | 표준         | 스트리밍                                      |
  | :------------ | :--------- | :---------------------------------------- |
  | 응답            | 완성된 오디오 파일 | 청크 오디오 스트림                                |
  | 지연 시간         | 전체 합성 대기   | 첫 청크 \~200ms                              |
  | `volume`      | 지원         | 미지원                                       |
  | `target_lufs` | 지원         | 지원                                        |
  | 출력 설정         | `Output`   | `OutputStream` (피치, 템포, 포맷, target\_lufs) |

  **요청 스키마:**

  ```json theme={null}
  {
    "voice_id": "tc_xxxxx",
    "text": "문의해 주셔서 감사합니다. 금요일 오후 7시로 예약이 확정되었습니다.",
    "model": "ssfm-v30",
    "language": "kor",
    "output": {
      "audio_pitch": 0,
      "audio_tempo": 1.0,
      "audio_format": "wav"
    }
  }
  ```

  **응답:** 청크 바이너리 스트림 (`audio/wav` 또는 `audio/mpeg`).

  ### 새 엔드포인트: GET /v1/users/me/subscription

  인증된 사용자의 플랜 등급, 크레딧 사용량, 동시 요청 제한을 조회합니다.

  ```text theme={null}
  GET /v1/users/me/subscription
  ```

  **응답 스키마:**

  ```json theme={null}
  {
    "plan": "lite",
    "credits": {
      "plan_credits": 100000,
      "used_credits": 157300
    },
    "limits": {
      "concurrency_limit": 5
    }
  }
  ```

  ### SDK 업데이트

  9개 공식 SDK 모두 스트리밍 및 구독 지원이 추가되었습니다:

  | SDK        | 버전     | 스트리밍 메서드                                       |
  | :--------- | :----- | :--------------------------------------------- |
  | Python     | 0.2.0  | `text_to_speech_stream()` (동기 + 비동기)           |
  | JavaScript | 0.3.0  | `textToSpeechStream()` → `ReadableStream`      |
  | Go         | v0.2.0 | `TextToSpeechStream()` → `io.ReadCloser`       |
  | Rust       | 0.2.0  | `text_to_speech_stream()` → `Stream<Bytes>`    |
  | Swift      | v0.2.0 | `textToSpeechStream()` → `AsyncThrowingStream` |
  | C#         | 0.2.0  | `TextToSpeechStreamAsync()` → `Stream`         |
  | Java       | 1.1.0  | `textToSpeechStream()` → `InputStream`         |
  | Kotlin     | 1.1.0  | `textToSpeechStream()` → `InputStream`         |
  | C          | 1.1.0  | `typecast_text_to_speech_stream()` (콜백)        |
</Update>

<Update label="2026년 1월" tags={["모델","API","보이스"]} description="ssfm-v30 모델 & v2 API">
  ### 새 모델: ssfm-v30

  음성 품질이 개선되고 기능이 확장된 새로운 `ssfm-v30` 모델 지원이 추가되었습니다.

  **새로운 기능:**

  * **스마트 이모션** - `SmartPrompt`를 사용한 문맥 인식 감정 추론
  * **7가지 감정 프리셋** - `whisper`, `toneup`, `tonedown` 프리셋 추가
  * **범용 감정 지원** - 모든 감정을 모든 보이스에서 사용 가능
  * **37개 언어** - 10개 새 언어 추가

  **새로 추가된 언어:** 벵골어, 광둥어, 힌디어, 헝가리어, 민난어, 노르웨이어, 펀자브어, 태국어, 터키어, 베트남어

  **요청 스키마 변경:**

  ```json theme={null}
  // ssfm-v30 SmartPrompt 사용 (문맥 인식 감정)
  {
    "model": "ssfm-v30",
    "prompt": {
      "emotion_type": "smart",
      "previous_text": "I feel like I'm walking on air and I just want to scream with joy!",
      "next_text": "I am literally bursting with happiness and I never want this feeling to end!"
    }
  }

  // ssfm-v30 PresetPrompt 사용 (수동 감정 선택)
  {
    "model": "ssfm-v30",
    "prompt": {
      "emotion_type": "preset",
      "emotion_preset": "happy",
      "emotion_intensity": 1.0
    }
  }
  ```

  ### 새 엔드포인트: GET /v2/voices

  모델별로 그룹화된 감정과 추가 메타데이터가 포함된 향상된 보이스 목록 엔드포인트가 추가되었습니다.

  ```text theme={null}
  GET /v2/voices
  ```

  **쿼리 파라미터:**

  | 파라미터        | 타입     | 설명                                                                   |
  | :---------- | :----- | :------------------------------------------------------------------- |
  | `model`     | string | 모델별 필터링 (`ssfm-v21`, `ssfm-v30`)                                     |
  | `gender`    | string | 성별별 필터링 (`male`, `female`)                                           |
  | `age`       | string | 연령대별 필터링 (`child`, `teenager`, `young_adult`, `middle_age`, `elder`) |
  | `use_cases` | string | 사용 사례별 필터링 (`Audiobook`, `Game`, `E-learning` 등)                     |

  **응답 스키마:**

  ```json theme={null}
  [
    {
      "voice_id": "tc_xxxxx",
      "voice_name": "음성 이름",
      "models": [
        {
          "version": "ssfm-v30",
          "emotions": ["normal", "happy", "sad", "angry", "whisper", "toneup", "tonedown"]
        },
        {
          "version": "ssfm-v21",
          "emotions": ["normal", "happy", "sad"]
        }
      ],
      "gender": "female",
      "age": "young_adult",
      "use_cases": ["Audiobook", "E-learning"]
    }
  ]
  ```

  ### 지원 중단: 보이스 관리 엔드포인트

  다음 엔드포인트가 지원 중단되어 제거되었습니다:

  | 엔드포인트                       | 상태  |
  | :-------------------------- | :-- |
  | `POST /v1/voices`           | 제거됨 |
  | `GET /v1/voices/{voice_id}` | 제거됨 |

  향상된 메타데이터가 포함된 보이스 목록을 보려면 `GET /v2/voices`를 사용하세요.
</Update>

<Update label="2025년 7월" tags={["모델","API"]} description="초기 API 출시">
  ### 초기 출시: ssfm-v21

  `ssfm-v21` 모델로 타입캐스트 Text-to-Speech API를 출시했습니다.

  **엔드포인트:**

  | 메서드  | 엔드포인트                | 설명           |
  | :--- | :------------------- | :----------- |
  | POST | `/v1/text-to-speech` | 텍스트에서 음성 생성  |
  | GET  | `/v1/voices`         | 사용 가능한 음성 목록 |

  **기능:**

  * 저지연 음성 합성
  * 4가지 감정 프리셋: `normal`, `happy`, `sad`, `angry`
  * 음성에 따라 감정 사용 가능 여부가 다름
  * 27개 언어 지원

  **지원 언어:** 영어, 한국어, 아랍어, 불가리아어, 중국어, 크로아티아어, 체코어, 덴마크어, 네덜란드어, 핀란드어, 프랑스어, 독일어, 그리스어, 인도네시아어, 이탈리아어, 일본어, 말레이어, 폴란드어, 포르투갈어, 루마니아어, 러시아어, 슬로바키아어, 스페인어, 스웨덴어, 타갈로그어, 타밀어, 우크라이나어

  **요청 스키마:**

  ```json theme={null}
  {
    "voice_id": "tc_xxxxx",
    "text": "Everything is so incredibly perfect that I feel like I'm dreaming.",
    "model": "ssfm-v21",
    "language": "kor",
    "prompt": {
      "emotion_preset": "normal",
      "emotion_intensity": 1.0
    },
    "output": {
      "volume": 100,
      "audio_pitch": 0,
      "audio_tempo": 1.0,
      "audio_format": "wav"
    }
  }
  ```
</Update>