Python으로 쓰는 음성 합성 API: 저장, 스트리밍, 재시도
클라우드 음성 합성 API는 Python 스크립트에 목소리를 주는 가장 짧은 길입니다. 모델을 내려받을 필요도, GPU도 없이 HTTP 요청 한 번이면 됩니다. 이 가이드는 requests 라이브러리로 Python에서 SuperClonica 음성 합성 API를 쓰는 방법을 첫 파일부터 긴 텍스트 스트리밍, 운영 스크립트에 맞는 제한 처리까지 보여 줍니다.
키가 필요합니다. Google이나 GitHub로 SuperClonica에 로그인하고 작업 공간의 음성 합성 API 섹션에서 만드세요. 무료 요금제는 하루 1분의 오디오를 줍니다.
mp3 저장하기
키를 환경 변수에 두고 음성과 언어를 지정해 텍스트를 보내세요:
import os, requests; KEY = os.environ["SUPERCLONICA_KEY"]; r = requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": "파이썬에서 안녕하세요!", "voice": "F1", "language": "ko", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)
"format"이 없으면 가장 작은 파일인 Ogg Vorbis로 응답합니다. wav도 쓸 수 있습니다. 요청 하나는 최대 2만 자를 받습니다.
긴 텍스트 스트리밍
"stream": true를 쓰면 서버가 오디오를 만드는 중에도 보내므로, 첫 조각부터 디스크에 쓰거나 플레이어로 넘길 수 있습니다:
with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "ko", "stream": True}, stream=True, timeout=120) as r: r.raise_for_status(); f = open("speech.ogg", "wb"); [f.write(chunk) for chunk in r.iter_content(8192)]; f.close()
측정에서 첫 소리는 텍스트 길이와 관계없이 최소 300ms에 도착했고, 약 1만 6000자가 25.6초 만에 읽혔습니다.
음성과 제한
키가 쓸 수 있는 음성을 나열합니다. 각 항목에는 id, 이름, 종류(stock, own, bought, catalog), 언어가 있습니다:
voices = requests.get("https://superclonica.com/api/v1/voices", headers={"Authorization": "Bearer " + KEY}, timeout=30).json()["items"]
큰 작업 전에 요금제 잔여량을 확인하세요:
usage = requests.get("https://superclonica.com/api/v1/usage", headers={"Authorization": "Bearer " + KEY}, timeout=30).json(); print(usage["plan"], usage["available_seconds"])
오류와 재시도
모든 요청에 Idempotency-Key 헤더(예: 텍스트의 해시)를 보내세요. 그러면 타임아웃 뒤 반복한 요청이 같은 작업을 기다리므로 텍스트를 두 번 읽거나 두 번 계산하지 않습니다.
- 429: 요금제의 10분 창을 다 썼습니다. Retry-After의 초만큼 기다렸다가 다시 보내세요.
- 503: 대기열이 가득 찼습니다. Retry-After 초만큼 기다린 뒤 같은 키로 다시 보내세요.
- 413: 텍스트가 요금제의 한 창에서 허용하는 길이보다 깁니다. 나눠서 보내세요.
- 401: 키가 없거나 틀렸거나 삭제되었습니다.
- 실패한 텍스트는 요금제에 계산되지 않습니다.