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.

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
stream_speech는 오디오를 청크 단위로 반환하므로, 전체 클립이 완성되기 전에 재생이나 전달을 시작할 수 있습니다. 경로는 /v1/text-to-speech/{voice_id}/stream입니다.
스트리밍은 현재 **sona_speech_1**에서만 지원됩니다.

언제 스트리밍을 사용하는가

스트리밍은 단일 TTS 클립이 충분히 길어, 전체가 완성될 때까지 기다리는 시간이 체감될 정도일 때 가장 유용합니다. 예를 들어 여러 문장으로 이루어진 단락을 한 번의 호출로 합성하는 경우입니다. 각 발화가 짧은 문장인 인터랙티브 에이전트나 챗봇의 경우, 보통 빠른 논스트리밍 모델을 사용하는 편이 전체 지연시간 면에서 더 유리합니다.
  • sona_speech_2_flash — 속도와 품질의 균형을 잡은 모델입니다.
  • supertonic_api_3 — 추론 속도가 가장 빠르면서도 음성 안정성이 높은 모델입니다. 첫 오디오 도달 시간(time-to-first-audio)이 최우선일 때 사용해 주십시오.
자세한 논의는 지연시간 최적화를 참고해 주십시오. LLM 응답을 TTS로 스트리밍하기에서 소개하는 문장 단위 패턴은 stream_speech를 전혀 사용하지 않으며, 문장마다 빠른 논스트리밍 모델을 호출하는 방식에 의존합니다.

기본 스트리밍

from supertone import Supertone

VOICE_ID = "20160a4c5ba38967330c84"  # replace with your voice ID

with Supertone(api_key=API_KEY) as client:
    response = client.text_to_speech.stream_speech(
        voice_id=VOICE_ID,
        text="This response is streamed chunk by chunk.",
        language="en",
        model="sona_speech_1",
        output_format="wav",
    )

    with open("streamed.wav", "wb") as f:
        for chunk in response.result.iter_bytes():
            f.write(chunk)

요청 필드

Create speech와 동일하며, modelsona_speech_1로 고정됩니다(현재 스트리밍을 지원하는 유일한 모델입니다). 경로는 /v1/text-to-speech/{voice_id}/stream입니다.

응답

기본적으로 응답 본문은 output_format에 일치하는 Content-Type을 가진 바이너리 오디오 스트림입니다.
  • audio/wav — WAV 파일의 청크입니다(첫 번째 청크에 WAV 헤더가 포함됩니다).
  • audio/mpeg — MP3 파일의 청크입니다.
include_phonemes=true인 경우, 응답은 NDJSON으로 전환됩니다. 한 줄에 하나의 JSON 객체가 들어 있으며, 각각 base64 오디오 청크와 대응하는 음소 데이터를 포함합니다.

긴 입력 스트리밍

SDK는 스트리밍 시에도 300자를 초과하는 텍스트를 자동으로 분할합니다. 내부적으로 텍스트를 분할하고 순차적인 스트리밍 요청을 보낸 뒤, 청크를 호출자의 이터레이터로 전달하므로 읽기 루프 코드는 그대로 유지할 수 있습니다. 자세한 내용은 Long text를 참고해 주십시오.

  • 플레이어 버퍼링. 대부분의 플레이어는 재생을 시작하기 전에 초기 버퍼가 필요합니다. 첫 청크가 도착하자마자 재생하는 것보다, 1~2초 분량의 오디오를 버퍼링한 뒤 재생하는 편이 더 매끄럽게 느껴집니다.
  • WAV 대 MP3. WAV 청크는 크기가 크지만 연결이 쉽고, MP3 스트림은 더 작아 느린 네트워크에서 전달하기에 유리합니다.
  • 오류 처리. 스트림 오류는 읽기 도중에 발생할 수 있습니다. 반복 처리를 평소의 오류 핸들러로 감싸고, 특히 일시적인 4295xx 응답에 대비한 재시도를 준비해 주십시오. 재시도 및 백오프를 참고해 주십시오.

관련 문서

LLM 스트리밍 TTS

보이스 에이전트를 위한 문장 단위 패턴입니다.

지연시간 최적화

낮은 지연시간을 위해 적합한 모델과 패턴을 선택하세요.