Python용 TTS API 키: 설정, 스트리밍, JSON 모드

키가 제공하는 기능 확인하기

tts api key python 예제를 검색하는 사람들은 보통 텍스트를 음성으로 변환하기를 원합니다. 이 서비스의 키는 그런 작업을 수행하지 않습니다. 이 키는 텍스트 LLM에 대한 요청을 인증합니다. POST /v1/chat/completions 및 GET /v1/models를 사용하며, 모델 uncensored을 사용합니다. 음성 합성도, 오디오 업로드도, 임베딩도 없습니다.

스크립트, 대화, 내레이션을 생성하여 별도의 음성 도구로 전달하는 경우와 같이 프로젝트에 맞는다면, 이 페이지의 나머지 부분에서 작동하는 Python 코드를 제공합니다. API 자체에서 오디오 출력이 필요한 경우 이 서비스는 적합하지 않으므로 지금 알아두시는 것이 좋습니다. 문서에 정확한 기능 목록이 나와 있습니다.

오디오 프로젝트에서 텍스트 생성을 활용하는 실용적인 방법은 이를 작성 단계로 간주하는 것입니다. 모델이 내레이션을 초안으로 작성하거나, 시간 제한에 맞춰 문장을 수정하거나, 여러 화자의 대화로 노트를 변환합니다. Python 코드는 최종 텍스트를 사용하는 음성 도구로 전달합니다. 단계를 분리하면 하나를 변경해도 다른 쪽을 건드리지 않아도 되며, 이 API에는 모델이 작성한 단어만큼만 비용을 지불합니다.

따라하려면 Python 3.9 이상이 필요하며 키가 필요합니다. API 키 페이지에서 가입하고 원클릭 $0.50 체험 크레딧을 받으세요. 유효 기간은 7일이며 카드가 필요하지 않습니다.

키 저장 및 패키지 설치

커밋하는 파일에 키를 절대 작성하지 마세요. 환경 변수에 넣고 런타임에 읽으세요.

Copy# base URL used below: https://api.ttsapihub.com/v1 , model: uncensored
pip install openai
export API_KEY="paste-your-key-here"

Windows PowerShell에서는 $env:API_KEY = "paste-your-key-here"이 해당됩니다. 프로젝트의 경우 python-dotenv와 같은 패키지로 로드하는 .env 파일을 사용하는 것이 일반적입니다. 단, .env이 .gitignore에 있는지 확인하세요.

키가 저장소에 유출된 경우 이를 사용할 수 없게 된 것으로 간주하세요: 가능하면 기록에서 제거하고 새 키를 요청하세요. 키는 선불 크레딧을 사용하므로, 유출된 키는 금전적 유출도 의미합니다.

클라이언트 생성 및 첫 번째 호출

공식 패키지는 base_url을 허용합니다. 나머지는 일반적인 OpenAI 호출 형태입니다.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ttsapihub.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short narration scripts."},
        {"role": "user", "content": "Draft a 40-word intro for a podcast about night trains."},
    ],
    temperature=0.8,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

usage 객체는 호출에 사용된 토큰 수를 보여주므로 비용을 계산할 수 있습니다: 입력 토큰 수 * 백만 토큰당 $0.15 + 출력 토큰 수 * 백만 토큰당 $0.50. 위의 호출이 60개의 입력 토큰과 80개의 출력 토큰을 사용한 경우 비용은 $0.000009 + $0.00004로, 총 $0.000049입니다. 실패하거나 거부된 요청에는 요금이 부과되지 않습니다.

max_tokens은 선택 사항입니다. 이를 설정하지 않으면 완료는 100,000개 토큰 창에 남은 만큼을 사용할 수 있으므로, 길이와 비용에 대한 엄격한 제한이 필요할 때 설정하세요.

응답 스트리밍

스트리밍은 서버 전송 이벤트를 사용하여 생성되는 대로 토큰을 반환합니다. stream=True을 설정하고 반복하세요.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe a rainy station platform in four sentences."}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content or ""
    parts.append(delta)
    print(delta, end="", flush=True)

text = "".join(parts)

빈 choices 목록에 대한 가드는 스트림의 마지막 이벤트가 텍스트 없이 사용 데이터만 포함할 수 있기 때문입니다. 이를 건너뛰면 인덱스 오류를 피할 수 있습니다. 운영상 세부 사항: 스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 유지합니다. 스레드에서 많은 스트림을 시작하고 절대 읽지 않으면 요청률이 낮더라도 동시성 제한에 도달합니다.

JSON 요청 및 도구 호출

JSON 모드

response_format을 JSON 객체로 설정하여 응답을 파싱 가능하게 만드세요. 또한 프롬프트에서 JSON을 원한다고 알려주세요. 설정은 형식을 제한하고 프롬프트는 형태를 지정합니다.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": str, \"beats\": [str]}"},
        {"role": "user", "content": "Outline a three-beat radio drama about a lost key."},
    ],
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], len(data["beats"]))

json.loads을 어쨌든 try 블록으로 감싸세요. max_tokens에 도달한 응답은 객체 중간에서 잘릴 수 있습니다.

함수 호출

tools를 전달하고 선택적으로 tool_choice를 설정하세요. 모델이 도구를 요청하면 직접 실행하고 role: "tool" 메시지로 결과를 보내세요.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "word_count",
        "description": "Count the words in a text",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = len(args["text"].split())
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

대화 유지 및 토큰 예산 모니터링

API는 상태가 없습니다. 대화 기록을 유지하려면 메시지 목록을 프로그램에 저장하고 모든 호출 시 함께 보내야 합니다. 작은 클래스로 처리할 수 있으며, 비용이 증가하지 않도록 기록을 제한하는 것도 좋은 위치입니다.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

history = [{"role": "system", "content": "You are a dialogue writer. Keep replies under 120 words."}]

def say(user_text, keep_last=12):
    history.append({"role": "user", "content": user_text})
    # keep the system message plus the most recent turns
    trimmed = [history[0]] + history[1:][-keep_last:]
    resp = client.chat.completions.create(model="uncensored", messages=trimmed, max_tokens=250)
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply, resp.usage.total_tokens

print(say("Open a scene in a ticket office at closing time.")[0])

다듬기는 창보다 비용에 더 중요합니다. 모델은 총 100,000개 토큰까지 허용하지만, 모든 턴에서 30,000개 토큰의 역사를 다시 보내면 각 호출의 입력 비용만 $0.0045(30,000 * 백만 토큰당 $0.15)입니다. 이러한 턴 50번은 단일 출력 토큰이 계산되기 전에 $0.225에 달합니다. 마지막 12턴을 유지하거나 오래된 턴을 짧은 메모로 요약하면 일반적으로 품질을 유지하고 청구서를 크게 줄입니다.

동시성도 설계해야 할 사항입니다. 여러 사용자를 동시에 처리할 때, 키의 제한(전체 키는 8, 체험 키는 2)에 맞춘 세마포어로 concurrency 오류를 방지하세요. 제한 초과 시 429 오류 대신 큐에서 대기하여 더 나은 경험을 제공합니다.

테스트도 한 줄 정도는 다뤄야 합니다. 고정된 seed, 낮은 온도, 짧은 max_tokens로 API를 호출하는 작은 스크립트를 작성하고, 프롬프트나 설정을 변경할 때마다 실행하세요. 시드와 낮은 온도는 출력을 더 반복 가능하게 만들어, 노이즈 없이 두 프롬프트 버전을 비교할 수 있게 합니다. 이러한 검사는 작게 유지하세요. 1센트 미만의 비용이 드는 테스트는 청구서에 눈에 띄지 않으면서도 모든 커밋에서 실행할 수 있습니다.

마지막으로 각 응답의 요청 ID를 로그에 기록하세요. 호출이 이상하게 동작할 때, 이 ID는 지원팀이 정확한 요청을 찾는 가장 빠른 방법입니다.

제한, 오류 및 잔액 처리

전체 키는 동시 요청 8개, 분당 요청 300개를 허용합니다. 체험 키는 각각 2개와 60개입니다. 첫 번째를 초과하면 concurrency 오류와 함께 HTTP 429가 반환되며, 두 번째를 초과하면 rate_limited와 함께 429가 반환됩니다. 임시 과부하도 Retry-After: 5 헤더와 함께 429를 반환합니다.

OpenAI 패키지는 일부 실패를 자동으로 재시도하며, max_retries로 이를 높일 수 있습니다. 배치 작업의 경우 동시 작업에 자체 제한을 추가하여 재시도에 의존하지 않고 동시성 제한 아래에 머무르세요.

Copyimport os
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"], max_retries=3)

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "One sentence about trains."}],
    max_tokens=60,
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
print(raw.parse().choices[0].message.content)

응답 헤더 X-Request-Id 및 X-Balance-USD는 로그에 유용합니다. 지원팀에 문의할 때 요청 ID를 인용하세요. 비용은 가격 페이지에 나열되어 있습니다: 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50. 충전 금액은 $20부터 $500까지이며, $50, $100, $200에서 각각 5%, 10%, 15% 보너스가 제공됩니다. 카드(Visa, Mastercard, Apple Pay, Google Pay)와 암호화폐(TRC20 USDT, Base USDC)가 허용됩니다. 프롬프트는 학습에 사용되지 않습니다. 모델은 합법적인 성인 사용자를 위해 설계되었으며 미성년자와 관련된 성 콘텐츠는 절대 허용되지 않습니다.

더 많은 가이드

• SillyTavern용 무료 API: 체험 크레딧 및 설정
• TTS API Base URL: 정의 및 입력 방법
• Elevenlabs API 체크리스트: 무검열 TTS 파이프라인