Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt

Use this file to discover all available pages before exploring further.

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
보이스 에이전트나 챗봇과 같은 실시간 환경에서는 전체 처리량보다 **첫 오디오까지의 시간(time-to-first-audio)**이 더 중요합니다. 이 가이드를 따라 해당 시간을 낮게 유지하세요.

​
지연시간 스택

전체 지연시간은 대략 다음과 같이 구성됩니다. 
input → LLM token stream → text buffer → TTS request → first audio chunk → playback
각 계층이 지연시간을 더합니다. 기여도가 가장 큰 계층부터 최적화하세요.

​
1. 품질 기준을 만족하는 가장 빠른 모델을 선택하세요

모델 선택은 보통 가장 영향력이 큰 지렛대입니다.
모델사용 시점
sona_speech_2품질을 최우선으로 두고 지연시간을 일정 부분 감수할 수 있는 경우에 적합합니다. 최고 품질 모델입니다.
sona_speech_2_flash속도와 품질의 균형이 필요한 경우에 적합합니다. sona_speech_2보다 지연시간이 낮으면서 유사한 품질을 제공합니다. voice settings와 normalized_text를 지원합니다.
supertonic_api_3속도를 최우선으로 두는 경우에 적합합니다. 가장 낮은 추론 오버헤드와 최고의 time-to-first-audio를 제공하며, supertonic_api_1 대비 발화 안정성이 대폭 향상되었습니다. voice settings는 speed만 지원합니다.
supertonic_api_1레거시 supertonic 모델입니다. 기존 연동에서 이 모델로 고정되어 있는 경우에만 사용하시고, 신규 프로젝트는 supertonic_api_3를 우선 사용하시기 바랍니다. voice settings는 speed만 지원합니다.
sona_speech_1stream_speech 청크 출력이 특별히 필요하거나, voice settings 전체(similarity, text_guidance, subharmonic_amplitude_control)가 필요한 경우에 적합합니다.
대부분의 인터랙티브 에이전트와 챗봇에서는 sona_speech_2_flash 또는 supertonic_api_3가 sona_speech_1 위에서 스트리밍을 사용하는 것보다 더 좋은 성능을 보입니다. 각 호출 자체가 더 빠르게 반환되기 때문입니다. 전체 기능 매트릭스는 모델을 참고해 주세요.

​
2. 토큰을 문장 단위로 묶으세요

LLM 출력을 TTS로 파이핑할 때는, 한 토큰당 한 요청을 보내지 마세요. 토큰을 문장 크기의 청크로 묶고, 문장당 한 번의 TTS 요청을 보내세요. 실행 가능한 예제는 LLM 응답에서 TTS 스트리밍하기를 참고해 주세요. 합리적인 묶음 전략은 다음과 같습니다.
  • 문장 종결 문장부호(., !, ?, 。, ！, ？)에서 플러시합니다.
  • 버퍼가 약 60자를 초과한 시점에 쉼표 뒤에서 플러시합니다(첫 오디오 지연시간을 짧게 유지하기 위함).
  • 스트림 종료 시점에 플러시합니다.

​
3. 스트리밍은 실제로 도움이 될 때만 사용하세요

stream_speech(sona_speech_1 기반)는 오디오를 청크 단위로 반환하며, 다음과 같은 경우에 유용합니다.
  • 단일 입력이 충분히 길어, 전체 클립을 기다리는 시간이 체감될 정도이고
  • 전체 클립이 준비되기 전에 재생을 시작하고자 하는 경우입니다.
문장 크기의 짧은 입력에는 느린 모델로 스트리밍하는 것보다 빠른 모델로 비스트리밍 호출을 하는 편이 종단 간(end-to-end) 기준으로 더 빠른 경우가 일반적입니다. 각 호출이 더 빠르게 완료되기 때문입니다. 
# Often the fastest option for an interactive agent:
response = client.text_to_speech.create_speech(
    voice_id=VOICE_ID,
    text=sentence,
    language="en",
    model="supertonic_api_3",
)

​
4. 커넥션을 재사용하세요

두 SDK 모두, 단일 클라이언트와 컨텍스트 매니저를 사용하면 호출 간에 HTTPS 커넥션을 재사용합니다. 호출마다 클라이언트를 새로 생성하지 마세요 — TLS 설정에만 100~500 ms가 추가됩니다. 
# Good: one client, reused across requests
with Supertone(api_key=API_KEY) as client:
    for sentence in sentences:
        client.text_to_speech.create_speech(...)

# Bad: constructs a new client (and TCP/TLS handshake) per call
for sentence in sentences:
    with Supertone(api_key=API_KEY) as client:
        client.text_to_speech.create_speech(...)

​
5. 재시도를 지연시간 예산에 맞게 튜닝하세요

느린 커넥션에서의 공격적인 재시도는 체감 지연시간을 오히려 악화시킵니다. maxElapsedTime은 SLO에 비례하게 설정하세요 — 2초 이내에 응답해야 하는 에이전트라면, 60초의 재시도 예산을 설정해선 안 됩니다. 자세한 튜닝 가이드는 재시도와 백오프를 참고해 주세요.

​
6. 시작 시점에 예열(pre-warm)하세요

배포 직후 트래픽이 급증하는 서비스라면, 시작 시점에 단일 TTS 호출을 한 번 보내 DNS, TLS, 커넥션 풀을 예열해 두세요. 이후의 호출은 더 빨라집니다.

​
7. API와 가까운 위치에 배치하세요

Supertone API는 supertoneapi.com에서 호스팅됩니다. 서비스가 멀리 떨어진 리전에서 운영되는 경우, 짧은 클립에서는 네트워크 라운드트립 자체가 지연시간의 대부분을 차지할 수 있습니다. 서비스를 같은 리전에 배치하거나 필요에 따라 엣지 프록시를 추가하세요.

​
첫 오디오까지의 시간 측정

호출을 다음과 같이 감싸면 어느 구간에서 시간이 소요되는지 정확히 측정할 수 있습니다. 
import time

start = time.perf_counter()
response = client.text_to_speech.create_speech(
    voice_id=VOICE_ID,
    text="Hello!",
    language="en",
    model="supertonic_api_3",
)
audio = response.result.read()
end = time.perf_counter()

print(f"Total time: {end - start:.3f}s   audio bytes: {len(audio)}")
이 지표를 프로덕션에서 추적하세요. 지표가 악화되었다면 원인은 보통 다음 중 하나입니다 — 모델 변경, 네트워크 변경, 재시도 튜닝, 또는 자체 서비스 내 큐잉.

​
관련 문서

모델

모델별 트레이드오프를 자세히 확인하세요.

LLM 스트리밍 TTS

저지연 보이스 에이전트를 위한 종단 간 레시피를 확인하세요.