Klucz API TTS w Pythonie: konfiguracja, strumieniowanie, tryb JSON, tryb JSON

Sprawdź, co otwiera klucz

Osoby szukające przykładowego klucza API TTS w Pythonie zwykle chcą zamieniać tekst na mowę. Klucz z tej usługi tego nie robi. Uwierzytelnia zapytania do API LLM do tekstu: POST /v1/chat/completions i GET /v1/models, używając modelu uncensored. Nie ma syntezy mowy, przesyłania audio ani embeddingów.

Jeśli pasuje to do Twojego projektu, np. generujesz scenariusze, dialogi lub narrację przekazywane do osobnego narzędzia, reszta tej strony daje Ci działający Python. Jeśli potrzebujesz wyjścia audio z samego API, to nie jest odpowiedni serwis, lepiej wiedzieć o tym teraz. dokumentacja wymienia dokładny zestaw funkcji.

Praktycznym sposobem użycia generowania tekstu w projekcie audio jest traktowanie go jako etapu pisania. Model szkicuje narrację, przepisuje linię, aby pasowała do limitu czasu, lub zamienia notatki w dialog z wieloma rozmówcami. Twój kod Pythona przekazuje następnie końcowy tekst do dowolnego narzędzia do syntezy mowy, którego używasz. Oddzielenie etapów oznacza również, że możesz zamienić dowolny z nich bez dotykania drugiego, i płacisz za to API tylko za słowa, które pisze.

Aby kontynuować, potrzebujesz Pythona 3.9 lub nowszego oraz klucza. Zarejestruj się na stronie klucz API i odbierz jednorazowy kredyt próbny za $0,50; ważny przez 7 dni i nie wymaga karty.

Przechowaj klucz i zainstaluj pakiet

Nigdy nie wpisuj klucza do pliku, który commitujesz. Umieść go w zmiennej środowiskowej i odczytuj w czasie działania.

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

W PowerShell na Windowsie odpowiednikiem jest $env:API_KEY = "paste-your-key-here". Dla projektu plik .env ładowany przez pakiet taki jak python-dotenv jest powszechnym wzorcem, o ile .env jest w Twoim .gitignore.

Jeśli klucz wycieknie do repozytorium, traktuj go jako spalony: usuń go z historii, jeśli możesz, i poproś o nowy. Pamiętaj, że klucze zużywają przedpłacony kredyt, więc wyciek klucza to też wyciek finansowy.

Utwórz klienta i wykonaj pierwsze wywołanie

Oficjalny pakiet akceptuje base_url. Wszystko inne to zwykły kształt wywołania 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)

Obiekt usage pokazuje, ile tokenów zużyło wywołanie, więc możesz obliczyć koszt: tokeny wejściowe razy $0,15 za milion, plus tokeny wyjściowe razy $0,50 za milion. Jeśli powyższe wywołanie użyło 60 tokenów wejściowych i 80 wyjściowych, koszt to $0,000009 plus $0,00004, co daje $0,000049. Nieudane lub odrzucone zapytania nie są rozliczane.

max_tokens jest opcjonalne. Bez niego uzupełnienie może użyć tego, co pozostaje z okna 100 000 tokenów, więc ustaw to, gdy chcesz sztywny limit długości i kosztu.

Strumieniuj odpowiedź

Strumieniowanie zwraca tokeny w miarę ich generowania za pomocą zdarzeń wysyłanych przez serwer. Ustaw stream=True i iteruj.

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)

Ochrona przed pustą listą choices wynika z tego, że ostatnie zdarzenie strumienia może zawierać dane użycia bez tekstu. Pominięcie go zapobiega błędowi indeksu. Szczegół operacyjny: żądanie strumieniowe zajmuje slot współbieżności do końca strumienia. Uruchomienie wielu strumieni w wątkach bez ich odczytu spowoduje przekroczenie limitu współbieżności, mimo niskiego tempa żądań.

Poproś o JSON i wywołaj narzędzia

Tryb JSON

Ustaw response_format na obiekt JSON, aby odpowiedź była możliwa do parsowania. Powiedz też modelowi w promptcie, że chcesz JSON; ustawienie ogranicza format, a prompt mówi o kształcie.

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"]))

Zawijaj json.loads w bloku try i tak. Odpowiedź, która osiągnie max_tokens, może zostać ucięta w środku obiektu.

Wywoływanie funkcji

Przekaż tools i opcjonalnie tool_choice. Gdy model zażąda narzędzia, uruchom je samodzielnie i wyślij wynik z powrotem jako wiadomość z 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)

Utrzymuj rozmowę i pilnuj budżetu tokenów

API jest bezstanowe. Jeśli chcesz rozmowę, która pamięta, co zostało powiedziane, trzymasz listę wiadomości w swoim programie i wysyłasz ją całą z każdym wywołaniem. Mała klasa robi robotę i jest też właściwym miejscem na obcięcie historii, aby koszt nie rósł.

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])

Przycinanie ma znaczenie dla pieniędzy bardziej niż dla okna. Model akceptuje do 100 000 tokenów łącznie, ale jeśli każda tura wysyła z powrotem 30 000 tokenów historii, każde wywołanie kosztuje $0.0045 tylko za wejście (30 000 razy $0.15 za milion). Pięćdziesiąt takich tur sumuje się do $0.225 przed policzeniem pojedynczego tokena wyjściowego. Trzymanie ostatnich kilkunastu tur lub podsumowywanie starszych w krótką notatkę zwykle utrzymuje jakość i ostro obniża rachunek.

Współbieżność to drugi aspekt projektowania. Jeśli program obsługuje wielu użytkowników, semafor o rozmiarze zgodnym z limitem klucza (8 dla pełnego, 2 dla próbnego) zapobiega błędowi concurrency. Wywołania powyżej limitu czekają we własnej kolejce, co jest lepsze niż ponawianie prób po 429.

Testy też warto wspomnieć. Napisz mały skrypt, który wywołuje API z ustalonym seed, niską temperaturą i krótkim max_tokens, i uruchamiaj go przy każdej zmianie promptów lub ustawień. Seed i niska temperatura sprawiają, że wyjście jest bardziej powtarzalne, co pozwala porównać dwie wersje promptów bez szumu. Trzymaj te testy małymi; test kosztujący ułamek centa może działać przy każdym commicie bez zauważenia rachunku.

Na koniec loguj ID zapytania z każdej odpowiedzi. Gdy wywołanie zachowuje się dziwnie, to ID jest najszybszym sposobem wskazania wsparciu dokładnego zapytania.

Obsłuż limity, błędy i saldo

Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Klucz próbny pozwala na 2 i 60. Przekroczenie pierwszego zwraca HTTP 429 z kodem błędu concurrency, a przekroczenie drugiego zwraca 429 z rate_limited. Tymczasowe przeciążenie również zwraca 429 z nagłówkiem Retry-After: 5.

Pakiet OpenAI automatycznie ponawia niektóre błędy, a można to zwiększyć przez max_retries. Dla zadania wsadowego dodaj własny limit równoległej pracy, aby nie przekroczyć limitu współbieżności, zamiast polegać na ponowieniach.

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)

Nagłówki odpowiedzi X-Request-Id i X-Balance-USD są przydatne w logach. Podaj ID żądania przy kontakcie z supportem. Koszty na stronie cenowej: $0.15 za 1M tokenów wejściowych i $0.50 za 1M tokenów wyjściowych. Doładowania od $20 do $500 z bonusami 5%, 10% i 15% przy $50, $100 i $200. Akceptowane karty (Visa, Mastercard, Apple Pay, Google Pay) i kryptowaluty (USDT na TRC20, USDC na Base). Prompty nie są używane do trenowania. Model przeznaczony dla dorosłych; treści seksualne z udziałem nieletnich są zawsze zabronione.

Więcej przewodników

• Darmowe API dla SillyTavern: kredyt próbny i konfiguracja
• Podstawowy URL API TTS: czym jest i co wpisać
• Checklista API Elevenlabs: potok TTS bez cenzury