Channel Developers

Channel TTS API 사용 가이드

채널톡 TTS API는 한국어 텍스트를 고품질 음성으로 변환해 주는 서비스입니다.

용도에 따라 실시간 스트리밍 방식과 배치(전체 생성) 방식 두 가지를 제공합니다.

1. 실시간 스트리밍 TTS

텍스트를 음성으로 변환하면서 오디오를 실시간으로 스트리밍합니다.

첫 번째 오디오 청크가 매우 빠르게 도착하므로, 실시간 대화/챗봇에 적합합니다.

1-1. 엔드포인트

Plaintext
https://ch-tts-streaming-demo.channel.io/v1/text-to-speech/{voice_id}/stream?optimize_streaming_latency={level}

  1. voice_id

    • 설명

      • "hana"만 지원합니다. 현재는 단일 음성만 제공되며,추후 여러 음성 ID를 지원할 예정입니다.

    • 가이드

      • voice_id는 항상 "hana"로 고정해 주세요.

  2. optimize_streaming_latency: 레이턴시 최적화 레벨 (0–4)

1-2. 요청 예시

기본 사용 (최고 품질)

Shell

레이턴시 최적화 (빠른 응답)

Shell

1-3. 레이턴시 최적화 레벨

Level

Chunk Size

품질

레이턴시

권장 용도

0

20 tokens

가장 느림

고품질 음성 필요 시

1

16 tokens

느림

품질/속도 균형

2

12 tokens

보통

일반적인 대화

3

8 tokens

빠름

실시간 대화

4

6 tokens

가장 빠름

초저지연 필요 시

1-4. 요청 형식

HTTP Method

  • POST /v1/text-to-speech/{voice_id}/stream

Path Parameters

  • voice_id (string, 필수)

    • 기본값 : hana

Query Parameters

  • optimize_streaming_latency (integer, 선택, 0–4)

    • 기본값: 0

    • 0: 최고 품질 (chunk_tokens=20)

    • 1: 높은 품질 (chunk_tokens=16)

    • 2: 균형 (chunk_tokens=12)

    • 3: 빠른 응답 (chunk_tokens=8)

    • 4: 최저 레이턴시 (chunk_tokens=6)

Request Body (JSON)

JSON

  1. text (string, 필수)

    • 음성으로 변환할 한국어 텍스트 (비어 있으면 안 됨)

  2. model_id

    • 설명

      • 현재는 단일 기본 TTS 모델만 제공됩니다.

    • 가이드

      • model_id는 생략하거나 "default"로 고정해서 사용해 주세요.

      • 추후 여러 모델을 지원할 때, 이 필드로 모델을 선택할 수 있도록 확장될 예정입니다.

  3. voice_settings

    • 설명

      • 현재는 고정된 음성 세팅만 제공하며, 개별 파라미터 튜닝은 지원하지 않습니다.

    • 가이드

      • voice_settings는 생략하거나 빈 객체 {}로 고정해서 사용해 주세요.

      • 이후 속도, 감정, 스타일 등 세부 옵션을 받을 때 이 필드를 사용할 예정입니다.

  4. output_format (string, 선택)

    • 기본값: "pcm_24000"

    • 허용 값:

      • "pcm_16000"

      • "pcm_24000"

      • "pcm_44100"

      • "pcm_48000"

      • "wav_24000"

1-5. 응답

  1. text (string, 필수)

    • 음성으로 변환할 한국어 텍스트 (비어 있으면 안 됨)

  2. model_id (string 또는 null, 선택)

    • 기본값 : hana

  3. voice_settings (object 또는 null, 선택)

    • 음성 관련 추가 설정. 현재는 무시됨.

  4. output_format (string, 선택)

    • 기본값: "pcm_24000"

    • 허용 값:

      • "pcm_16000"

      • "pcm_24000"

      • "pcm_44100"

      • "pcm_48000"

      • "wav_24000"

2. 배치 TTS (전체 생성)

배치 TTS는 텍스트를 음성으로 변환한 뒤, 완성된 전체 오디오 파일을 한 번에 반환합니다.

스트리밍보다 첫 응답까지의 시간(TTFA)이 길지만, 안정성이 높고 파일 저장이 간단합니다.

2-1. 엔드포인트

Plaintext
https://ch-tts-streaming-demo.channel.io/v1/text-to-speech/{voice_id}

  • voice_id:

    • 설명

      • "hana"만 지원합니다. 현재는 단일 음성만 제공되며,추후 여러 음성 ID를 지원할 예정입니다.

    • 가이드

      • voice_id는 항상 "hana"로 고정해 주세요.

2-2. 사용 예시

WAV 파일로 저장하기

Shell

PCM 포맷으로 바로 재생하기

Plaintext
curl -X POST "https://ch-tts-streaming-demo.channel.io/v1/text-to-speech/hana" \
  -H "Content-Type: application/json" \
  -d '{"text":"안녕하세요. 채널톡입니다.","output_format":"pcm_24000"}' \
  | ffplay -nodisp -autoexit -f s16le -ar 24000 -i -

Python 예제

Python

2-3. 요청 형식

HTTP Method

  • POST /v1/text-to-speech/{voice_id}

Path Parameters

  • voice_id (string, 필수)

    • 기본값 : hana

Request Body (JSON)

JSON

  1. text (string, 필수)

    • 음성으로 변환할 한국어 텍스트

  2. model_id

    • 설명

      • 현재는 단일 기본 TTS 모델만 제공됩니다.

    • 가이드

      • model_id는 생략하거나 "default"로 고정해서 사용해 주세요.

  3. voice_settings

    • 설명

      • 현재는 고정된 음성 세팅만 제공하며, 개별 파라미터 튜닝은 지원하지 않습니다.

    • 가이드

      • voice_settings는 생략하거나 빈 객체 {}로 고정해서 사용해 주세요.

      • 이후 속도, 감정, 스타일 등 세부 옵션을 받을 때 이 필드를 사용할 예정입니다.

  4. output_format (string, 선택)

    • 기본값: "pcm_24000"

    • 허용 값:

      • "pcm_16000"

      • "pcm_24000"

      • "pcm_44100"

      • "pcm_48000"

      • "wav_24000"

2-4. 응답

성공 (200)

  • 완성된 오디오 데이터 (PCM 또는 WAV 형식)

에러 코드

  • 400: 잘못된 요청 (필수 파라미터 누락 또는 형식 오류)

  • 422: 유효성 검사 실패

  • 429: 서버 과부하 (동시 요청 수 초과, 잠시 후 재시도 필요)