> ## 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. # 타임스탬프 포함 텍스트 음성 변환(TTS with Timestamps) > 텍스트로부터 음성을 생성하면서 **단어·문자 단위 타임스탬프**를 함께 반환합니다. 자막 싱크, 문자 단위 하이라이트 애니메이션, 발화 구간 시각화 등에 활용할 수 있습니다. 요청 본문은 표준 `/v1/text-to-speech` 엔드포인트와 동일합니다(voice_id, text, model, language, prompt, output, seed). 응답은 바이너리 오디오가 아닌 JSON 이며, base64 로 인코딩된 오디오와 함께 `words` / `characters` 배열을 포함합니다. 필요에 따라 `granularity` 쿼리 파라미터로 단어 단위 또는 문자 단위 중 한쪽만 받아 응답 크기를 줄일 수 있습니다. > **언어 주의.** 일본어(`jpn`), 중국어(`zho`) 처럼 단어 사이에 공백이 없는 언어는 word 단위 정렬이 문장 전체를 하나의 "단어" 로 묶어 버립니다. 이런 언어에서는 항상 `granularity=char` 를 지정해 문자 단위 타임스탬프를 받으세요. 사용 가능한 캐릭터 목록은 [캐릭터 목록 조회](/docs/ko/api-reference/voices/list-voices) 를 참조하세요. ## OpenAPI ````yaml /ko/api-reference/openapi.json post /v1/text-to-speech/with-timestamps openapi: 3.1.0 info: title: Typecast API version: 0.1.2 x-logo: url: https://typecast.ai/_ipx/_/image/logo/tc_logo.webp servers: - url: https://api.typecast.ai description: 프로덕션 서버 security: - ApiKeyAuth: [] paths: /v1/text-to-speech/with-timestamps: post: tags: - Text-to-Speech summary: 타임스탬프 포함 텍스트 음성 변환(TTS with Timestamps) description: >- 텍스트로부터 음성을 생성하면서 **단어·문자 단위 타임스탬프**를 함께 반환합니다. 자막 싱크, 문자 단위 하이라이트 애니메이션, 발화 구간 시각화 등에 활용할 수 있습니다. 요청 본문은 표준 `/v1/text-to-speech` 엔드포인트와 동일합니다(voice_id, text, model, language, prompt, output, seed). 응답은 바이너리 오디오가 아닌 JSON 이며, base64 로 인코딩된 오디오와 함께 `words` / `characters` 배열을 포함합니다. 필요에 따라 `granularity` 쿼리 파라미터로 단어 단위 또는 문자 단위 중 한쪽만 받아 응답 크기를 줄일 수 있습니다. > **언어 주의.** 일본어(`jpn`), 중국어(`zho`) 처럼 단어 사이에 공백이 없는 언어는 word 단위 정렬이 문장 전체를 하나의 "단어" 로 묶어 버립니다. 이런 언어에서는 항상 `granularity=char` 를 지정해 문자 단위 타임스탬프를 받으세요. 사용 가능한 캐릭터 목록은 [캐릭터 목록 조회](/docs/ko/api-reference/voices/list-voices) 를 참조하세요. operationId: text_to_speech_with_timestamps_v1_text_to_speech_with_timestamps_post parameters: - name: granularity in: query required: false schema: type: string enum: - word - char description: >- 반환할 타임스탬프 배열을 선택합니다. - 생략: `words` 와 `characters` 모두 반환 - `word`: `words` 만 반환 (`characters` 는 null) - `char`: `characters` 만 반환 (`words` 는 null) **공백 없는 언어(예: `jpn`, `zho`):** `word` 정렬은 문장 전체를 하나의 구간으로 반환하므로, 의미 있는 타임스탬프를 얻으려면 `char` 를 사용하세요. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TTSRequestWith-timestamps' responses: '200': description: Success - Returns base64 audio and timestamps content: application/json: schema: $ref: '#/components/schemas/TTSWithTimestampsResponse' example: audio: UklGRs...(base64 오디오 생략) audio_format: wav audio_duration: 3.2 words: - text: 집중력이 start: 0.08 end: 0.76 - text: 떨어질 start: 0.8 end: 1.26 - text: 땐 start: 1.3 end: 1.52 - text: 5분간 start: 1.56 end: 2.02 - text: 스트레칭을 start: 2.06 end: 2.7 - text: 해보세요. start: 2.74 end: 3.2 characters: - text: 집 start: 0.08 end: 0.26 - text: 중 start: 0.26 end: 0.43 - text: 력 start: 0.43 end: 0.6 - text: 이 start: 0.6 end: 0.76 - text: ' ' start: 0.76 end: 0.8 - text: 떨 start: 0.8 end: 0.94 - text: 어 start: 0.94 end: 1.1 - text: 질 start: 1.1 end: 1.26 - text: ' ' start: 1.26 end: 1.3 - text: 땐 start: 1.3 end: 1.52 - text: ' ' start: 1.52 end: 1.56 - text: '5' start: 1.56 end: 1.68 - text: 분 start: 1.68 end: 1.84 - text: 간 start: 1.84 end: 2.02 - text: ' ' start: 2.02 end: 2.06 - text: 스 start: 2.06 end: 2.18 - text: 트 start: 2.18 end: 2.3 - text: 레 start: 2.3 end: 2.42 - text: 칭 start: 2.42 end: 2.56 - text: 을 start: 2.56 end: 2.7 - text: ' ' start: 2.7 end: 2.74 - text: 해 start: 2.74 end: 2.88 - text: 보 start: 2.88 end: 3.02 - text: 세 start: 3.02 end: 3.14 - text: 요 start: 3.14 end: 3.18 - text: . start: 3.18 end: 3.2 '400': description: Bad Request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid voice_id '401': description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid API key '402': description: Payment Required - Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Insufficient credit '404': description: Not Found - Voice model not available content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Voice not found '422': description: Validation Error - Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid request format '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Too many requests '500': description: Internal Server Error - TTS generation or timestamp alignment failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: An unexpected error occurred x-codeSamples: - lang: cURL label: cURL source: | curl --request POST \ --url https://api.typecast.ai/v1/text-to-speech/with-timestamps \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: ' \ --data @- <", "Content-Type": "application/json", } payload = { "voice_id": "tc_60e5426de8b95f1d3000d7b5", "text": "집중력이 떨어질 땐 5분간 스트레칭을 해보세요.", "model": "ssfm-v30", "language": "kor", "prompt": { "emotion_type": "preset", "emotion_preset": "normal", "emotion_intensity": 1.0, }, } response = requests.post( f"{API_HOST}/v1/text-to-speech/with-timestamps", headers=headers, json=payload, timeout=60, ) response.raise_for_status() data = response.json() with open("output.wav", "wb") as f: f.write(base64.b64decode(data["audio"])) print(f"저장 완료: duration={data['audio_duration']}초") for w in (data.get("words") or [])[:3]: print(f" 단어: {w['text']!r} {w['start']:.3f}s - {w['end']:.3f}s") components: schemas: TTSRequestWith-timestamps: type: object properties: voice_id: type: string title: Voice Id description: >- 캐릭터 식별자. 두 가지 prefix 를 지원합니다. - `tc_` — 기본 제공되는 타입캐스트 캐릭터 (예: `tc_60e5426de8b95f1d3000d7b5`). 사용 가능한 ID 는 [캐릭터 목록 조회](/docs/ko/api-reference/voices/list-voices) 를 참조하세요. - `uc_` — [퀵 클로닝](/docs/ko/api-reference/voices/instant-cloning) 으로 생성한 커스텀 보이스 (예: `uc_64a1b2c3d4e5f6a7b8c9d0e1`). 본인이 소유한 클로닝 보이스만 사용할 수 있습니다. 대소문자 구분: prefix 는 소문자만 사용합니다. example: tc_60e5426de8b95f1d3000d7b5 text: type: string title: Text description: >- 음성으로 변환할 텍스트. 최소 1자, 최대 2000자. 텍스트 길이에 따라 크레딧이 소비됩니다. 영어, 한국어, 일본어, 중국어를 포함한 여러 언어를 지원합니다. 특수 문자와 구두점은 자동으로 처리됩니다. example: 모든 것이 너무나 완벽해서 마치 꿈을 꾸는 것 같습니다. minLength: 1 maxLength: 2000 model: $ref: '#/components/schemas/TTSModel' description: | 음성 합성에 사용할 캐릭터 모델. - **ssfm-v30**: 향상된 플로우와 추가 감정 프리셋이 있는 최신 모델(권장) - **ssfm-v21**: 빠르고 안정적인 모델로 신뢰할 수 있는 품질 제공 example: ssfm-v30 language: type: string title: Language description: > ISO 639-3 표준을 따르는 언어 코드. 대소문자 구분 안 함("KOR"과 "kor" 모두 허용). 제공하지 않으면 텍스트 내용을 기반으로 자동 감지됩니다.
ssfm-v30 지원 언어 (37개) | 코드 | 언어 | 코드 | 언어 | 코드 | 언어 | |------|----------|------|----------|------|----------| | ARA | 아랍어 | IND | 인도네시아어 | POR | 포르투갈어 | | BEN | 벵골어 | ITA | 이탈리아어 | RON | 루마니아어 | | BUL | 불가리아어 | JPN | 일본어 | RUS | 러시아어 | | CES | 체코어 | KOR | 한국어 | SLK | 슬로바키아어 | | DAN | 덴마크어 | MSA | 말레이어 | SPA | 스페인어 | | DEU | 독일어 | NAN | 민남어 | SWE | 스웨덴어 | | ELL | 그리스어 | NLD | 네덜란드어 | TAM | 타밀어 | | ENG | 영어 | NOR | 노르웨이어 | TGL | 타갈로그어 | | FIN | 핀란드어 | PAN | 펀자브어 | THA | 태국어 | | FRA | 프랑스어 | POL | 폴란드어 | TUR | 터키어 | | HIN | 힌디어 | UKR | 우크라이나어 | VIE | 베트남어 | | HRV | 크로아티아어 | YUE | 광둥어 | ZHO | 중국어 | | HUN | 헝가리어 | | | | |
ssfm-v21 지원 언어 (27개) | 코드 | 언어 | 코드 | 언어 | 코드 | 언어 | |------|----------|------|----------|------|----------| | ARA | 아랍어 | IND | 인도네시아어 | RON | 루마니아어 | | BUL | 불가리아어 | ITA | 이탈리아어 | RUS | 러시아어 | | CES | 체코어 | JPN | 일본어 | SLK | 슬로바키아어 | | DAN | 덴마크어 | KOR | 한국어 | SPA | 스페인어 | | DEU | 독일어 | MSA | 말레이어 | SWE | 스웨덴어 | | ELL | 그리스어 | NLD | 네덜란드어 | TAM | 타밀어 | | ENG | 영어 | POL | 폴란드어 | TGL | 타갈로그어 | | FIN | 핀란드어 | POR | 포르투갈어 | UKR | 우크라이나어 | | FRA | 프랑스어 | HRV | 크로아티아어 | ZHO | 중국어 |
> **타임스탬프 엔드포인트 주의.** 일본어(`jpn`) · 중국어(`zho`) 처럼 단어 사이에 공백이 없는 언어는 word 단위 정렬이 문장 전체를 하나의 구간으로 묶어 버립니다. 이런 언어에서는 항상 `granularity=char` 를 함께 지정해 문자 단위 타임스탬프를 받으세요. example: kor prompt: title: Prompt description: >- 생성된 음성의 감정 및 스타일 설정, 감정 유형(happy/sad/angry/normal) 및 강도(0.0~2.0)를 포함하여 감정 표현을 제어합니다 oneOf: - $ref: '#/components/schemas/SmartPrompt' - $ref: '#/components/schemas/PresetPrompt' - $ref: '#/components/schemas/Prompt' discriminator: propertyName: emotion_type mapping: preset: $ref: '#/components/schemas/PresetPrompt' smart: $ref: '#/components/schemas/SmartPrompt' output: $ref: '#/components/schemas/Output' description: >- 볼륨(0-200), 피치(-12~+12 반음), 템포(0.5배~2.0배), 형식(wav/mp3)을 포함한 오디오 출력 설정으로 최종 오디오 특성을 제어합니다 seed: type: integer minimum: 0 title: Seed description: >- 재현 가능한 음성 생성을 위한 부호 없는 정수 시드. 동일한 시드와 동일한 입력 파라미터로 항상 같은 오디오 결과를 생성합니다. - 0 이상의 정수만 허용됩니다. 음수 값은 사용할 수 없습니다. - 생략하면 서버가 매번 랜덤 시드를 생성하여 약간의 변이가 발생합니다. example: 42 anyOf: - type: integer maximum: 4294967295 minimum: 0 - type: 'null' format: uint32 required: - voice_id - text - model title: TTSRequestWith-timestamps description: TTSRequestWith-timestamps parameters TTSWithTimestampsResponse: type: object properties: audio: type: string title: Audio description: base64 로 인코딩된 오디오 바이트. `audio_format` 확장자로 디코딩해 파일로 저장할 수 있습니다. audio_format: type: string enum: - wav - mp3 title: Audio Format description: >- `audio` 필드의 오디오 인코딩 포맷 — `wav` 또는 `mp3` (요청의 `output.audio_format` 에 따라 결정). audio_duration: type: number title: Audio Duration description: 생성된 오디오의 길이(초). words: title: Words description: 단어 단위 타임스탬프(문장부호 포함). 요청이 `granularity=char` 일 때는 `null`. anyOf: - type: array items: $ref: '#/components/schemas/AlignmentSegmentWord' - type: 'null' characters: title: Characters description: 문자 단위 타임스탬프(문장부호와 공백 포함). 요청이 `granularity=word` 일 때는 `null`. anyOf: - type: array items: $ref: '#/components/schemas/AlignmentSegmentCharacter' - type: 'null' required: - audio - audio_format - audio_duration - words - characters title: TTSWithTimestampsResponse description: TTS 생성 + 타임스탬프 정렬 통합 응답. ErrorResponse: type: object properties: detail: type: string description: 문제를 설명하는 오류 메시지 required: - detail example: detail: An error occurred processing the request TTSModel: type: string enum: - ssfm-v30 - ssfm-v21 title: TTSModel description: | 음성 합성에 사용할 TTS 모델 버전. 다양한 모델은 다양한 기능과 품질 수준을 제공합니다. 사용 가능한 모델: - **ssfm-v30**: 향상된 플로우와 추가 감정 프리셋이 있는 최신 모델(권장) - **ssfm-v21**: 검증된 신뢰성과 일관된 품질을 갖춘 안정적인 모델 SmartPrompt: type: object properties: emotion_type: type: string title: Emotion Type description: | 프롬프트 유형을 식별하는 판별자 필드. 컨텍스트 인식 감정 추론을 위해 "smart"로 설정해야 합니다. default: smart const: smart previous_text: type: string title: Previous Text description: | TTSRequest의 `text` 필드 이전에 오는 텍스트. 감정 추론을 위한 후방 컨텍스트를 제공합니다. 모델은 흐름을 분석합니다: `previous_text` → `text`(합성됨) → `next_text` - 최대 2000자 - 모델이 감정 빌드업과 컨텍스트를 이해하는 데 도움 - 이전 컨텍스트가 없으면 비워 둡니다 default: '' example: I feel like I'm walking on air and I just want to scream with joy! next_text: type: string title: Next Text description: | TTSRequest의 `text` 필드 이후에 오는 텍스트. 감정 추론을 위한 전방 컨텍스트를 제공합니다. 모델은 흐름을 분석합니다: `previous_text` → `text`(합성됨) → `next_text` - 최대 2000자 - 모델이 감정 전환을 예측하는 데 도움 - 다음 컨텍스트가 없으면 비워 둡니다 default: '' example: >- I am literally bursting with happiness and I never want this feeling to end! title: 스마트 프롬프트 (ssfm-v30) description: 생성된 음성의 감정 및 스타일 설정. example: 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! additionalProperties: false PresetPrompt: type: object properties: emotion_type: type: string title: Emotion Type description: | 프롬프트 유형을 식별하는 판별자 필드. 프리셋 기반 감정 제어를 위해 "preset"으로 설정해야 합니다. default: preset const: preset emotion_preset: $ref: '#/components/schemas/EmotionEnum' description: | 생성된 음성에 적용할 감정 프리셋. 지원되는 감정: normal, happy, sad, angry, whisper, toneup, tonedown /v2/voices API를 통해 각 캐릭터에 사용 가능한 감정을 확인하세요. default: normal example: normal emotion_intensity: type: number maximum: 2 minimum: 0 title: Emotion Intensity description: | 생성된 음성의 감정 표현 강도를 제어합니다. - 0.0: 완전히 중립적, 감정 색채 없음 - 0.5: 미묘한 감정 힌트 - 1.0: 표준 감정 표현(기본값) - 1.5: 강한 감정 강조 - 2.0: 최대 강도, 매우 표현력 있음 default: 1 example: 1 title: 프리셋 프롬프트 (ssfm-v30) description: 생성된 음성의 감정 및 스타일 설정. additionalProperties: false Prompt: properties: emotion_preset: description: | 적용할 감정 프리셋. ssfm-v21 지원 감정: normal, happy, sad, angry /v2/voices API를 통해 각 캐릭터에 사용 가능한 감정을 확인하세요. example: normal emotion_intensity: description: | 감정 표현 강도 제어(0.0~2.0). - 0.0: 완전히 중립적 - 1.0: 표준 표현(기본값) - 2.0: 최대 강도 example: 1 title: 프롬프트 (ssfm-v21) description: 생성된 음성의 감정 및 스타일 설정. Output: type: object properties: target_lufs: type: integer title: Target Lufs description: > 출력 음성의 목표 절대 음량(LUFS) 설정. 원본 음성의 크기와 상관없이 모든 음성을 일정한 크기로 정규화하여 생성합니다. 값이 0에 가까울수록 소리가 커지며, -70에 가까울수록 작아집니다. - 필수 범위: -70 <= x <= 0 - 권장값: -14 (일반적인 스트리밍 표준), -23 (방송 표준) - **주의:** `volume` 파라미터와 함께 사용할 수 없습니다. 절대적인 음량 기준이 필요할 때는 `target_lufs`를, 상대적인 비율 조절이 필요할 때는 `volume`을 선택하여 사용하세요. example: -14 anyOf: - type: number maximum: 0 minimum: -70 - type: 'null' volume: title: Volume description: > 출력 음성의 상대적인 음량 조절: 0(완전 무음), 50(절반 볼륨), 100(표준 볼륨, 기본값), 150(표준보다 50% 크게), 200(최대 볼륨, 표준의 두 배). 출력된 음성마다 음량이 다를 경우, 단순 비율 조절인 `volume`을 사용하면 음성 간의 음량 편차가 더욱 커질 수 있습니다. 일정한 음량 출력이 필요한 경우 `target_lufs` 사용을 권장합니다. - **주의:** `target_lufs`와 동시에 사용할 수 없습니다. 필수 범위: 0 <= x <= 200 example: 100 anyOf: - type: integer maximum: 200 minimum: 0 - type: 'null' audio_pitch: type: integer maximum: 12 minimum: -12 title: Audio Pitch description: >- 성별과 나이에 영향을 주는 반음 단위의 피치 조정: -12(한 옥타브 낮게, 더 깊은 목소리), -6(반 옥타브 낮게), 0(원래 피치, 기본값), +6(반 옥타브 높게), +12(한 옥타브 높게, 더 높은 목소리) default: 0 example: 0 audio_tempo: type: number maximum: 2 minimum: 0.5 title: Audio Tempo description: >- 음성 속도 제어: 0.5(절반 속도, 매우 느리고 명확함), 0.75(보통보다 약간 느림), 1.0(보통 말하기 속도, 기본값), 1.5(보통보다 50% 빠름), 2.0(두 배 속도, 매우 빠른 음성) default: 1 example: 1 audio_format: type: string enum: - wav - mp3 title: Audio Format description: | 출력 오디오 형식. **WAV 형식:** - 비압축 PCM 오디오 - 16비트 깊이, 모노 채널, 44100 Hz 샘플링 속도 - 더 높은 품질, 더 큰 파일 크기 - 전문 오디오 제작에 권장 **MP3 형식:** - 압축된 MPEG Layer III 오디오 - 320 kbps 비트레이트, 44100 Hz 샘플링 속도 - 더 작은 파일 크기 - 웹 스트리밍 및 배포에 권장 default: wav example: wav title: Output AlignmentSegmentWord: type: object properties: text: type: string title: Text description: 원본 transcript 의 텍스트 조각 (문장부호 포함). start: type: number title: Start description: 이 구간의 시작 시각(오디오 시작 기준 초). end: type: number title: End description: 이 구간의 종료 시각(오디오 시작 기준 초). required: - text - start - end title: AlignmentSegmentWord description: 원본 transcript 와 생성된 오디오 사이의 단어 단위 정렬 구간. AlignmentSegmentCharacter: type: object properties: text: type: string title: Text description: 원본 transcript 의 텍스트 조각 (문장부호/공백 포함). start: type: number title: Start description: 이 구간의 시작 시각(오디오 시작 기준 초). end: type: number title: End description: 이 구간의 종료 시각(오디오 시작 기준 초). required: - text - start - end title: AlignmentSegmentCharacter description: 원본 transcript 와 생성된 오디오 사이의 문자 단위 정렬 구간. EmotionEnum: type: string enum: - normal - sad - happy - angry - whisper - toneup - tonedown title: EmotionEnum description: | 음성 합성에 사용 가능한 감정 프리셋. 각 감정은 생성된 음성의 톤, 속도, 표현력에 영향을 줍니다. **ssfm-v21 지원 감정 (4종류):** - normal: 중립적이고 균형 잡힌 톤 - happy: 밝고 명랑한 표현 - sad: 우울하고 차분한 톤 - angry: 강하고 강렬한 전달 **ssfm-v30 지원 감정 (7종류):** - normal: 중립적이고 균형 잡힌 톤 - happy: 밝고 명랑한 표현 - sad: 우울하고 차분한 톤 - angry: 강하고 강렬한 전달 - whisper: 부드럽고 조용한 말 - toneup: 더 높은 톤 강조 - tonedown: 더 낮은 톤 강조 /v2/voices API 응답을 통해 각 음성에 사용 가능한 감정을 확인하세요. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: 인증을 위한 API 키. 타입캐스트 API 콘솔에서 API 키를 생성할 수 있습니다. ````