Clé API TTS en Python : configuration, streaming, mode JSON

Vérifiez ce que la clé permet d'ouvrir

Les personnes qui recherchent un exemple de clé API TTS en Python souhaitent généralement convertir du texte en audio parlé. La clé de ce service ne fait pas cela. Elle authentifie les requêtes vers un LLM textuel : POST /v1/chat/completions et GET /v1/models, en utilisant le modèle uncensored. Il n'y a pas de synthèse vocale, pas de téléchargement d'audio et pas d'embeddings.

Si cela convient à votre projet, par exemple parce que vous générez des scripts, des dialogues ou des narrations que vous transmettez à un outil de synthèse vocal séparé, la suite de cette page vous donne du Python fonctionnel. Si vous avez besoin d'une sortie audio directement depuis l'API, ce n'est pas le bon service, et il vaut mieux le savoir maintenant. La documentation liste les fonctionnalités exactes.

Une façon pratique d'utiliser la génération de texte dans un projet audio est de le considérer comme l'étape d'écriture. Le modèle rédige une narration, réécrit une ligne pour s'adapter à une limite de temps, ou transforme des notes en dialogue avec plusieurs locuteurs. Votre code Python transmet ensuite le texte final à l'outil de synthèse vocale que vous utilisez. Garder les étapes séparées signifie également que vous pouvez remplacer l'un ou l'autre sans toucher à l'autre, et vous ne payez cette API que pour les mots qu'elle écrit.

Pour suivre le tutoriel, vous avez besoin de Python 3.9 ou plus récent et d'une clé. Inscrivez-vous sur la page Clé API et réclamez le crédit d'essai gratuit de 0,50 $ en un clic ; il dure 7 jours et ne nécessite pas de carte.

Stockez la clé et installez le package

N'écrivez jamais la clé dans un fichier que vous commitez. Placez-la dans une variable d'environnement et lisez-la au moment de l'exécution.

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

Sous Windows PowerShell, l'équivalent est $env:API_KEY = "paste-your-key-here". Pour un projet, un fichier .env chargé par python-dotenv est courant, à condition que .env soit dans votre .gitignore.

Si une clé fuit dans un dépôt, traitez-la comme consumée : supprimez-la de l'historique si vous le pouvez, et demandez-en une nouvelle. Rappelez-vous que les clés dépensent du crédit prépayé, donc une clé fuite est aussi une fuite financière.

Créez le client et effectuez un premier appel

Le package officiel accepte un base_url. Tout le reste est la forme d'appel OpenAI habituelle.

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'objet usage indique combien de tokens l'appel a utilisés, afin que vous puissiez calculer le coût : tokens d'entrée fois 0,15 $ par million, plus tokens de sortie fois 0,50 $ par million. Si l'appel ci-dessus a utilisé 60 tokens d'entrée et 80 tokens de sortie, le coût est de 0,000009 $ plus 0,00004 $, soit 0,000049 $. Les requêtes échouées ou refusées ne sont pas facturées.

max_tokens est optionnel. Sans lui, la complétion peut utiliser tout ce qui reste de la fenêtre de 100 000 tokens, donc définissez-le lorsque vous voulez un plafond strict sur la longueur et le coût.

Diffuser la réponse

Le streaming renvoie les tokens au fur et à mesure de leur génération via des événements envoyés par le serveur. Définissez stream=True et itérez.

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)

La vérification pour une liste choices vide est présente car l'événement final d'un flux peut contenir des données d'utilisation et aucun texte. Le sauter permet d'éviter une erreur d'index. Un détail opérationnel : une requête en streaming occupe son slot de concurrence jusqu'à la fin du flux. Si vous lancez de nombreux flux dans des threads et que vous ne les lisez jamais jusqu'au bout, vous atteindrez la limite de concurrence même si votre taux de requêtes est faible.

Demandez du JSON et appelez des outils

Mode JSON

Définissez response_format sur un objet JSON pour rendre la réponse analysable. Indiquez également au modèle dans le prompt que vous voulez du JSON ; le paramètre contraint le format, et le prompt indique la forme souhaitée.

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

Enveloppez toujours json.loads dans un bloc try. Une réponse qui atteint max_tokens peut être coupée au milieu d'un objet.

Appel de fonctions

Passez tools et éventuellement tool_choice. Lorsque le modèle demande un outil, exécutez-le vous-même et renvoyez le résultat en tant que message avec 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)

Gardez une conversation et surveillez le budget de tokens

L'API est sans état. Si vous voulez une conversation qui se souvient de ce qui a été dit, conservez la liste des messages dans votre programme et envoyez-la entièrement à chaque appel. Une petite classe fait l'affaire, et c'est aussi le bon endroit pour limiter l'historique afin que le coût n'augmente pas.

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

Le rognage est important pour l'argent plus que pour la fenêtre. Le modèle accepte jusqu'à 100 000 tokens au total, mais si chaque tour renvoie 30 000 tokens d'historique, chaque appel coûte 0,0045 $ rien qu'en entrée (30 000 fois 0,15 $ par million). Cinquante tours comme cela s'accumulent à 0,225 $ avant qu'un seul token de sortie ne soit compté. Garder les douze derniers tours, ou résumer les plus anciens dans une note courte, maintient généralement la qualité et réduit fortement la facture.

La concurrence est l'autre point à concevoir. Si votre programme sert plusieurs utilisateurs à la fois, un sémaphore de taille égale à la limite de votre clé (8 pour une clé complète, 2 pour une clé d'essai) vous empêche de déclencher l'erreur concurrency. Les appels au-delà de la limite attendent dans votre propre file d'attente au lieu d'échouer, ce qui est plus convivial que de réessayer sur un 429.

Les tests valent aussi la peine d'être mentionnés. Écrivez un petit script qui appelle l'API avec un seed fixe, une température faible et un court max_tokens, et exécutez-le chaque fois que vous modifiez des prompts ou des paramètres. Un seed et une température faible rendent la sortie plus reproductible, ce qui vous permet de comparer deux versions de prompt sans bruit. Gardez ces tests minuscules ; un test qui coûte une fraction de centime peut s'exécuter à chaque commit sans que personne ne remarque la facture.

Enfin, journalisez l'ID de requête de chaque réponse. Lorsqu'un appel se comporte de manière étrange, cet ID est le moyen le plus rapide de pointer le support vers la requête exacte.

Gérez les limites, les erreurs et le solde

Une clé complète permet 8 requêtes simultanées et 300 requêtes par minute. La clé d'essai permet 2 et 60. Dépasser la première renvoie HTTP 429 avec le code d'erreur concurrency, et dépasser la seconde renvoie 429 avec rate_limited. Une surcharge temporaire renvoie également 429 avec un en-tête Retry-After: 5.

Le package OpenAI retry automatiquement certains échecs, et vous pouvez augmenter cela avec max_retries. Pour un travail par lots, ajoutez votre propre limite de travail parallèle, afin de rester sous la limite de concurrence au lieu de compter sur les nouvelles tentatives.

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)

Les en-têtes de réponse X-Request-Id et X-Balance-USD sont utiles dans les journaux. Citez l'ID de requête lorsque vous contactez le support. Les coûts sont listés sur la page tarifaire : 0,15 $ par 1M de tokens d'entrée et 0,50 $ par 1M de tokens de sortie, avec des recharges de 20 $ à 500 $ et des bonus de 5 %, 10 % et 15 % à 50 $, 100 $ et 200 $. Les cartes (Visa, Mastercard, Apple Pay, Google Pay) et la crypto (USDT sur TRC20, USDC sur Base) sont acceptées. Les prompts ne sont pas utilisés pour l'entraînement. Le modèle est destiné à un usage adulte légal, et le contenu sexuel impliquant des mineurs est toujours interdit.

Plus de guides

• API gratuite pour SillyTavern : Crédit d'essai et configuration
• URL de base de l'API TTS : ce que c'est et quoi saisir
• Checklist API Elevenlabs : Pipeline TTS sans censure