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.

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
Supertone TTS API는 text요청당 300자로 제한합니다. 이를 초과하면 400 Bad Request가 반환됩니다. 더 긴 스크립트를 합성하려면 다음 두 가지 방법이 있습니다.
  1. SDK 사용하기. Python과 TypeScript SDK는 긴 입력을 자동으로 분할하여 각 세그먼트를 생성하고 오디오를 병합합니다. 입력이 2,000자라도 최종 클립 하나로 받게 됩니다.
  2. 직접 분할하기. REST API를 직접 호출하는 경우, 문장 경계에서 텍스트를 분할하고 반환된 오디오를 이어 붙여 주십시오.

300자 제한 한눈에 보기

LayerBehavior on >300 characters
REST API (POST /v1/text-to-speech/{voice_id})400 Bad Request를 반환합니다.
Python SDK (create_speech, stream_speech)300자에서 자동 분할하며, create_speech는 병렬로 생성합니다(스트리밍은 순차 처리). 이후 오디오를 병합합니다.
TypeScript SDK (createSpeech, streamSpeech)300자에서 자동 분할하며, 순차적으로 생성한 뒤 오디오를 병합합니다.
predict_duration자동 분할되지 않습니다. 동일한 300자 제한이 적용됩니다.
이 임계값은 두 SDK 모두에서 구성할 수 있습니다.
# Python — pass maxTextLength via SDK options
# (the default is 300; lower it to chunk earlier)
// TypeScript — pass maxTextLength in the options object
const response = await client.textToSpeech.createSpeech(
  { voiceId, apiConvertTextToSpeechUsingCharacterRequest: { text, language: "en" } },
  { maxTextLength: 250 },
);

SDK 자동 분할의 전체 흐름

import os
from supertone import Supertone

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

LONG_TEXT = (
    "Once upon a time, in a faraway land, there lived a quiet librarian "
    "who collected stories of forgotten kingdoms. Every evening she would "
    "open a leather-bound notebook and continue writing the next chapter "
    "of a tale she had been telling herself for years. ...continue with "
    "many more sentences spanning over 300 characters..."
)

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    response = client.text_to_speech.create_speech(
        voice_id=VOICE_ID,
        text=LONG_TEXT,
        language="en",
    )

    with open("narration.wav", "wb") as f:
        f.write(response.result.read())
SDK는 내부적으로 LONG_TEXT를 문장 경계(이후 단어 경계, 단어 하나가 너무 길면 문자 경계)에서 분할하고, 최대 3개의 create_speech 요청을 병렬로 실행한 뒤, 중간 파일 헤더를 제거한 WAV/MP3 오디오를 병합합니다.

긴 텍스트 스트리밍

SDK는 stream_speech / streamSpeech에서도 자동 분할을 수행합니다. 오디오는 마치 하나의 연속된 스트림인 것처럼 호출자의 이터레이터로 전달되므로, 몇 개의 세그먼트가 사용되었는지 알 필요가 없습니다. 스트리밍 패턴에 대해서는 Stream speech를 참고해 주십시오.

직접 분할하기 (cURL 또는 원시 HTTP)

REST API를 직접 호출하는 경우, 요청을 보내기 전에 분할해야 합니다. 권장 전략은 다음과 같습니다.
  1. 문장 종결 구두점(., !, ?, , )을 기준으로 분할합니다.
  2. 한 문장이 여전히 300자를 초과한다면 쉼표, 그리고 단어 경계에서 분할합니다.
  3. 각 세그먼트에 대해 POST /v1/text-to-speech/{voice_id}를 호출하고 반환된 오디오를 출력 파일에 이어 붙입니다.
  4. WAV 연결의 경우, 첫 세그먼트를 제외한 모든 세그먼트에서 WAV 헤더(첫 44바이트)를 제거하여 최종 파일이 하나의 클립으로 재생되도록 해야 합니다.
# Pseudo-shell: split a script and concatenate WAV chunks
VOICE_ID="20160a4c5ba38967330c84"

split_into_sentences "$INPUT_TEXT" > sentences.txt
while read -r line; do
  curl -s -X POST "https://supertoneapi.com/v1/text-to-speech/$VOICE_ID" \
    -H "x-sup-api-key: $SUPERTONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \"$line\", \"language\": \"en\"}" \
    >> raw_chunks.bin
done < sentences.txt
# Then merge with your audio tooling (ffmpeg, etc.) and re-attach a single WAV header.
대부분의 프로젝트에서는 SDK 사용을 권장합니다. SDK는 세그먼트 간 타이밍, 헤더 제거, 부분 실패 시 재시도 등의 엣지 케이스를 처리해 주므로 직접 구현할 필요가 없습니다.

  • 구두점이 중요합니다. 자동 분할은 문장 경계를 우선합니다. 구두점이 잘 표시된 입력일수록 더 깔끔한 분할과 자연스러운 전환을 만들어 냅니다.
  • 비용을 먼저 예측하세요. predict_duration은 자동 분할되지 않지만, 직접 텍스트를 분할하고 길이를 합산하여 전체 크레딧을 예측할 수 있습니다.
  • 속도 제한에 주의하세요. 하나의 긴 입력이 여러 TTS 요청으로 분할됩니다. 계정의 속도 제한을 확인하고, 호출 측에서도 트래픽 조절을 고려해 주십시오.

관련 문서

롱폼 내레이션

여러 단락 분량의 내레이션을 생성하는 엔드투엔드 예제입니다.

속도 제한

티어별 분당 요청 제한입니다.