Chiave API TTS in Python: configurazione, streaming, modalità JSON

Verifica cosa sblocca la chiave

Le persone che cercano un esempio di chiave api tts python di solito vogliono convertire il testo in audio parlato. La chiave di questo servizio non lo fa. Autentica le richieste a un LLM testuale: POST /v1/chat/completions e GET /v1/models, usando il modello uncensored. Non c'è sintesi vocale, nessun caricamento audio e nessun embedding.

Se serve al tuo progetto, ad esempio per generare script o narrazioni da passare a un altro tool, qui trovi codice Python funzionante. Se cerchi audio dall'API, questo non è il servizio giusto. La docs elenca le funzionalità.

Un modo pratico per usare la generazione di testo in un progetto audio è trattarlo come la fase di scrittura. Il modello stende la narrazione, riscrive una riga per adattarla a un limite di tempo o trasforma le note in dialoghi con più parlanti. Il tuo codice Python passa poi il testo finale allo strumento di sintesi vocale che preferisci. Mantenere le fasi separate significa anche che puoi sostituire l'una senza toccare l'altra e paghi questa API solo per le parole che scrive.

Per seguire la guida ti servono Python 3.9 o superiore e una chiave. Iscriviti alla pagina della chiave API e ottieni il credito di prova da $0,50 con un clic; dura 7 giorni e non richiede carta.

Memorizza la chiave e installa il pacchetto

Non scrivere la chiave in un file che committi. Inseriscila in una variabile d'ambiente e leggila a runtime.

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

Su PowerShell Windows: $env:API_KEY = "paste-your-key-here". Per un progetto, usa un file .env con python-dotenv, assicurando che .env sia in .gitignore.

Se una chiave finisce in un repository, trattala come bruciata: rimuovila dalla cronologia se puoi e richiedine una nuova. Ricorda che le chiavi spendono credito prepagato, quindi una chiave trapelata è anche una perdita finanziaria.

Crea il client e fai una prima chiamata

Il pacchetto ufficiale accetta un base_url. Tutto il resto segue la solita struttura di chiamata 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)

L'oggetto usage mostra quanti token ha utilizzato la chiamata, così puoi calcolare il costo: token di input moltiplicati per $0.15 per milione, più token di output moltiplicati per $0.50 per milione. Se la chiamata sopra ha utilizzato 60 token di input e 80 token di output, il costo è $0.000009 più $0.00004, che fa $0.000049. Le richieste fallite o rifiutate non vengono addebitate.

max_tokens è facoltativo. Senza di esso, il completamento può usare tutto ciò che rimane della finestra da 100.000 token, quindi impostalo quando vuoi un limite rigido su lunghezza e costo.

Attiva lo streaming della risposta

Lo streaming restituisce i token man mano che vengono generati usando gli eventi server-sent. Imposta stream=True e itera.

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)

Il controllo per una lista choices vuota c'è perché l'evento finale di uno streaming può contenere dati di utilizzo e nessun testo. Saltarlo evita un errore di indice. Un dettaglio operativo: una richiesta in streaming occupa la sua slot di concorrenza fino alla fine dello streaming. Se avvii molti streaming in thread e non li leggi mai fino alla fine, raggiungerai il limite di concorrenza anche se il tuo tasso di richieste è basso.

Chiedi JSON e chiama gli strumenti

Modalità JSON

Imposta response_format su un oggetto JSON per rendere la risposta analizzabile. Indica anche al modello nel prompt che vuoi il JSON; l'impostazione vincola il formato e il prompt indica la forma.

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

Avvolgi comunque json.loads in un blocco try. Una risposta che raggiunge max_tokens può essere troncata a metà di un oggetto.

Chiamata di funzioni

Passa tools e opzionalmente tool_choice. Quando il modello richiede uno strumento, eseguilo tu stesso e invia il risultato come messaggio con 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)

Gestisci una conversazione e monitora il budget dei token

L'API è senza stato. Se vuoi una chat che ricorda ciò che è stato detto, mantieni la lista dei messaggi nel tuo programma e invia tutto con ogni chiamata. Una piccola classe fa il lavoro, ed è anche il posto giusto per limitare la cronologia in modo che il costo non aumenti.

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

Il ritaglio è importante per i soldi più che per la finestra. Il modello accetta fino a 100.000 token in totale, ma se ogni turno reinvia 30.000 token di cronologia, ogni chiamata costa $0,0045 solo di input (30.000 volte $0,15 per milione). Cinquanta di questi turni ammontano a $0,225 prima che venga contato un singolo token di output. Mantenere le ultime dodici conversazioni o riassumere quelle più vecchie in una breve nota mantiene solitamente la qualità e riduce drasticamente il conto.

La concorrenza è l'altra cosa da progettare. Se il tuo servizio gestisce più utenti contemporaneamente, un semaforo dimensionato al limite della tua chiave (8 per una chiave completa, 2 per una chiave di prova) ti impedisce di attivare l'errore concurrency. Le chiamate sopra il limite attendono nella tua coda invece di fallire, il che è più amichevole che riprovare su un 429.

I test valgono una parola. Scrivi un piccolo script che chiama l'API con un seed fisso, una temperatura bassa e un breve max_tokens, ed eseguilo ogni volta che cambi prompt o impostazioni. Un seed e una temperatura bassa rendono l'output più ripetibile, permettendoti di confrontare due versioni di prompt senza rumore. Tieni questi controlli minimi; un test che costa una frazione di centesimo può essere eseguito su ogni commit senza che nessuno noti il conto.

Infine, registra l'ID della richiesta da ogni risposta. Quando una chiamata si comporta in modo strano, quell'ID è il modo più veloce per indicare a supporto la richiesta esatta.

Gestisci limiti, errori e saldo

Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. La chiave di prova permette 2 e 60. Superare il primo restituisce HTTP 429 con il codice di errore concurrency, e superare il secondo restituisce 429 con rate_limited. Un sovraccarico temporaneo restituisce anche 429 con un'intestazione Retry-After: 5.

Il pacchetto OpenAI ritenta alcuni errori da solo, e puoi aumentare questo valore con max_retries. Per un lavoro batch, aggiungi anche un tuo limite al lavoro parallelo, in modo da restare sotto il limite di concorrenza invece di affidarti ai ritentativi.

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)

Le intestazioni di risposta X-Request-Id e X-Balance-USD sono utili nei log. Citare l'ID della richiesta quando contatti il supporto. I costi sono elencati nella pagina dei prezzi: $0.15 per 1M token di input e $0.50 per 1M token di output, con ricariche da $20 a $500 e bonus del 5%, 10% e 15% a $50, $100 e $200. Sono accettate carte (Visa, Mastercard, Apple Pay, Google Pay) e cripto (USDT su TRC20, USDC su Base). I prompt non sono utilizzati per l'addestramento. Il modello è destinato a un uso legale da adulti, e i contenuti sessuali che coinvolgono minorenni non sono mai consentiti.

Altre guide

• API gratuita per SillyTavern: Credito di prova e configurazione
• URL di base dell'API TTS: cos'è e cosa inserire
• Checklist API Elevenlabs: pipeline TTS senza censura