권장되는 패턴은 컨텍스트 매니저를 사용해 내부 HTTP 연결이 깔끔하게 닫히도록 하는 것입니다.
import osfrom supertone import SupertoneVOICE_ID = "20160a4c5ba38967330c84" # replace with your voice IDwith Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client: response = client.text_to_speech.create_speech( voice_id=VOICE_ID, text="Hello from the Python SDK.", language="en", output_format="wav", ) with open("speech.wav", "wb") as f: f.write(response.result.read())
import asyncioimport osfrom supertone import SupertoneVOICE_ID = "20160a4c5ba38967330c84" # replace with your voice IDasync def main(): async with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client: response = await client.text_to_speech.create_speech_async( voice_id=VOICE_ID, text="Hello from the async Python SDK.", language="en", ) with open("speech.wav", "wb") as f: f.write(response.result.read())asyncio.run(main())
SDK의 모든 리소스 메서드는 두 가지 형태를 갖습니다: create_speech / create_speech_async, stream_speech / stream_speech_async, list_voices / list_voices_async 등.
import osfrom supertone import SupertoneVOICE_ID = "20160a4c5ba38967330c84" # replace with your voice IDwith Supertone(api_key=os.environ["SUPERTONE_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", ) with open("streamed.wav", "wb") as f: for chunk in response.result.iter_bytes(): f.write(chunk)
비동기 버전에서는 async for chunk in response.result.aiter_bytes()를 사용하세요. 스트리밍은 현재 sona_speech_1에서만 지원됩니다.
create_speech, create_speech_async, stream_speech, stream_speech_async는 300자보다 긴 텍스트를 자동으로 분할합니다. create_speech는 최대 3개 세그먼트를 병렬로 실행해 오디오를 병합하며, stream_speech는 순차적으로 세그먼트를 실행해 이터레이터로 청크를 전달합니다.
LONG_TEXT = "..." # any length, including thousands of charactersresponse = 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()) # single merged file
predict_duration은 자동 청크 분할을 수행하지 않습니다. 입력을 300자 이내로 유지하고, 더 긴 스크립트는 직접 길이를 합산하세요.자세한 내용과 튜닝은 긴 텍스트를 참고하세요.
# List voices with paginationresult = client.voices.list_voices(page_size=20)# Search voicesresult = client.voices.search_voices(language="ko,en", style="happy")# Get a single voicevoice = client.voices.get_voice(voice_id=VOICE_ID)# Predict duration (no credits deducted)duration = client.text_to_speech.predict_duration( voice_id=VOICE_ID, text="How long will this be?", language="en",)# Get credit balancebalance = client.usage.get_credit_balance()
오류는 supertone.errors에 있으며 모두 SupertoneError를 상속합니다.
from supertone import Supertone, errorstry: response = client.text_to_speech.create_speech(...)except errors.TooManyRequestsErrorResponse as e: # 429 — back off and retry print("Rate limited:", e.message)except errors.UnauthorizedErrorResponse as e: # 401 — bad or missing API key print("Auth failed:", e.message)except errors.PaymentRequiredErrorResponse as e: # 402 — out of credits print("Buy more credits:", e.message)except errors.SupertoneError as e: # Any other API error print(f"HTTP {e.status_code}: {e.message}")
