TTS API-sleutel in Python: Instellen, streaming, JSON-modus

Controleer wat de sleutel opent

Mensen die zoeken naar een tts-api-sleutel python-voorbeeld willen meestal tekst omzetten in gesproken audio. De sleutel van deze dienst doet dat niet. Hij authenticeert verzoeken bij een tekst-LLM: POST /v1/chat/completions en GET /v1/models, met het model uncensored. Er is geen spraaksynthese, geen audio-upload en geen embeddings.

Als dat past bij je project, bijvoorbeeld omdat je scripts, dialoog of narratie genereert die je aan een aparte spraaktool doorgeeft, geeft de rest van deze pagina je werkende Python. Als je audio-uitvoer vanuit de API zelf nodig hebt, is dit de verkeerde dienst en is het beter om dat nu te weten. De docs vermelden de exacte functieset.

Een praktische manier om tekstgeneratie in een audioproject te gebruiken, is om het te behandelen als de schrijffase. Het model schrijft een narratie, herschrijft een zin om binnen een tijdsbeperking te passen, of zet notities om in dialoog met meerdere sprekers. Je Python-code geeft de definitieve tekst vervolgens door aan welke spraaktool je ook gebruikt. De fasen apart houden betekent ook dat je de ene zonder de andere kunt vervangen, en je betaalt deze API alleen voor de woorden die het schrijft.

Om mee te doen heb je Python 3.9 of nieuwer en een sleutel nodig. Meld je aan op de API-sleutelpagina en claim het eenmalige proeftegoed van $0,50 met één klik; deze duurt 7 dagen en vereist geen kaart.

Sla de sleutel op en installeer het pakket

Schrijf de sleutel nooit in een bestand dat je commit. Zet hem in een omgevingsvariabele en lees hem tijdens het uitvoeren.

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

Op Windows PowerShell is het equivalent $env:API_KEY = "paste-your-key-here". Voor een project is een .env-bestand dat wordt geladen met een pakket zoals python-dotenv een veelvoorkomend patroon, zolang .env zich in je .gitignore bevindt.

Als een sleutel in een repository terechtkomt, behandel hem dan als verbrand: verwijder hem uit de geschiedenis als dat kan en vraag een nieuwe aan. Onthoud dat sleutels prepaid credit uitgeven, dus een gelekte sleutel is ook een financiële lek.

Maak de client aan en voer een eerste verzoek uit

Het officiële pakket accepteert een base_url. Alles anders is de gebruikelijke OpenAI-aanroepstructuur.

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)

Het usage object toont hoeveel tokens de call heeft gebruikt, zodat je de kosten kunt berekenen: input tokens vermenigvuldigd met $0.15 per miljoen, plus output tokens vermenigvuldigd met $0.50 per miljoen. Als de call hierboven 60 input tokens en 80 output tokens gebruikte, zijn de kosten $0.000009 plus $0.00004, wat $0.000049 is. Mislukte of geweigerde verzoeken worden niet in rekening gebracht.

max_tokens is optioneel. Zonder deze parameter kan de completion het resterende deel van het 100.000-token venster gebruiken, dus stel het in als je een harde limiet wilt voor lengte en kosten.

Stream het antwoord

Streaming retourneert tokens terwijl ze worden gegenereerd via server-sent events. Stel stream=True in en iterereer.

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)

De guard voor een lege choices-lijst is er omdat het laatste event van een stream usage data en geen tekst kan bevatten. Het overslaan ervan voorkomt een indexfout. Een operationeel detail: een gestreamd verzoek houdt zijn concurrency slot vast tot de stream eindigt. Als je veel streams in threads start en ze nooit volledig uitleest, bereik je de concurrency limit, zelfs als je request rate laag is.

Vraag om JSON en roep tools aan

JSON-modus

Stel response_format in op een JSON-object om het antwoord parseerbaar te maken. Vertel het model ook in de prompt dat je JSON wilt; de instelling beperkt de indeling, en de prompt vertelt het model welke vorm.

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

Wikkel json.loads toch in een try-block. Een antwoord dat max_tokens raakt, kan midden in een object worden afgekapt.

Function calling

Geef tools en optioneel tool_choice door. Als het model om een tool vraagt, voer hem dan zelf uit en stuur het resultaat terug als bericht met 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)

Houd een gesprek bij en houd de tokenbudgetten in de gaten

De API is stateless. Als je een chat wilt die zich herinnert wat er gezegd is, houd je de berichtenlijst in je programma bij en stuur je alles mee bij elke aanroep. Een kleine klasse doet het werk, en het is ook de juiste plek om de gespreksgeschiedenis te begrenzen zodat de kosten niet oplopen.

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

Trimmen is belangrijker voor geld dan voor het venster. Het model accepteert maximaal 100.000 tokens in totaal, maar als elke beurt 30.000 tokens van de history opnieuw verzendt, kost elke call $0.0045 aan input alleen (30.000 vermenigvuldigd met $0.15 per miljoen). Vijftig van zulke beurten optellen levert $0.225 op voordat een enkele output token geteld wordt. De laatste tiental beurten bijhouden, of oudere samenvatten tot een korte notitie, houdt de kwaliteit meestal hoog en snijdt de rekening scherp af.

Concurrency is het andere ding waar je voor moet ontwerpen. Als je programma meerdere gebruikers tegelijk bedient, houdt een semaphore die groot is als je key's limiet (8 voor een volledige key, 2 voor een trial key) je tegen het trippen van de concurrency fout. Calls boven de limiet wachten in je eigen queue in plaats van falen, wat vriendelijker is dan retryen op een 429.

Testing is ook het vermelden waard. Schrijf één klein script dat de API aanroept met een vaste seed, een lage temperatuur en een korte max_tokens, en voer het uit telkens als je prompts of instellingen wijzigt. Een seed en lage temperatuur maken de output meer herhaalbaar, wat je in staat stelt twee promptversies te vergelijken zonder ruis. Houd deze checks klein; een test die een fractie van een cent kost kan op elke commit draaien zonder dat iemand de rekening opmerkt.

Log tot slot de verzoek-ID van elke respons. Als een aanroep zich vreemd gedraagt, is die ID de snelste manier om support naar het exacte verzoek te verwijzen.

Behandel limieten, fouten en saldo

Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 verzoeken per minuut toe. De proefsleutel staat 2 en 60 toe. Het overschrijden van de eerste retourneert HTTP 429 met foutcode concurrency, en het overschrijden van de tweede retourneert 429 met rate_limited. Tijdelijke overload retourneert ook 429 met een Retry-After: 5 header.

Het OpenAI-pakket probeert sommige fouten vanzelf opnieuw, en je kunt dat verhogen met max_retries. Voor een batchverwerking, voeg ook je eigen limiet op parallel werk toe, zodat je onder de concurrency limit blijft in plaats van te vertrouwen op herhaalde pogingen.

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)

De response headers X-Request-Id en X-Balance-USD zijn nuttig in logs. Citeer de verzoek-ID als je contact opneemt met support. Kosten worden vermeld op de prijzenpagina: $0,15 per 1M input tokens en $0,50 per 1M output tokens, met opwaarderingen van $20 tot $500 en bonussen van 5%, 10% en 15% bij $50, $100 en $200. Kaart (Visa, Mastercard, Apple Pay, Google Pay) en crypto (USDT op TRC20, USDC op Base) worden geaccepteerd. Prompts worden niet gebruikt voor training. Het model is bedoeld voor wettelijk volwassen gebruik, en seksuele inhoud met minderjarigen is nooit toegestaan.

Meer handleidingen

• Gratis API voor SillyTavern: Proeftegoed en instellen
• TTS API Base URL: Wat het is en wat je moet invullen
• Elevenlabs API Checklist: Ongecensureerd TTS-pijplijn