IT ▾
Ottieni la chiave API

Bot Telegram Uncensored Endpoint: Crealo in Python

Per creare un bot Telegram per un endpoint uncensored servono tre elementi: un token del bot da BotFather, una chiave API e circa 80 righe di Python che inviano ogni messaggio Telegram al percorso di chat completions. Questa guida fornisce il codice completo, poi aggiunge memoria, streaming e gestione dei limiti.

Aggiornato

Punti chiave

  1. Il bot usa python-telegram-bot per Telegram e l'SDK OpenAI standard per il modello.
  2. Mantieni una cronologia breve per chat e tagliala in modo che ogni richiesta rimanga piccola ed economica.
  3. Usa lo streaming modificando un messaggio circa una volta al secondo, non a ogni token.
  4. Limita le chiamate parallele al modello a 8 con un semaforo e riprova le risposte 429.
Bolla di chat a forma di aereo di carta che lascia un terminale verso una fila di bolle di dialogo, che rappresenta un bot Telegram

Quello che stai costruendo

Il bot ha un solo compito: prendere un messaggio di testo da una chat Telegram, aggiungerlo alla cronologia di quella chat, inviare la cronologia al modello uncensored e pubblicare la risposta. Ogni chat Telegram ha la sua memoria, quindi due persone che parlano con il bot non vedono mai il contesto dell'altra.

Il progetto finito è un singolo file con queste parti:

  1. Un client per l'API, usando l'SDK OpenAI puntato a https://api.uncensoredendpoint.com/v1.
  2. Un dizionario delle cronologie di chat, limitato per evitare che cresca all'infinito.
  3. Un gestore di messaggi che trasmette la risposta modificando un messaggio Telegram.
  4. Un semaforo che ti mantiene sotto le 8 richieste concorrenti che una chiave completa permette.

Niente qui richiede un database. Quando il bot si riavvia, le cronologie si resettano, il che va bene per una prima versione. Una sezione successiva copre dove aggiungere la persistenza.

Prerequisiti

Ti servono Python 3.10 o superiore e due credenziali.

  • Un token del bot Telegram. Apri una chat con BotFather dentro Telegram, invia il comando per creare un nuovo bot, scegli un nome e un nome utente e copia il token che restituisce. Tratta il token come una password.
  • Una chiave API. Iscriviti alla pagina delle chiavi con Google o con email e password. I nuovi utenti possono richiedere $0,50 di credito di prova con un clic, sufficiente per testare questo bot molte volte. La chiave di prova permette 2 richieste concorrenti e 60 richieste al minuto.

Installa le due librerie ed esporta i segreti come variabili d'ambiente in modo che non finiscano mai nel tuo codice sorgente:

pip install "python-telegram-bot>=20" openai
export TELEGRAM_TOKEN="123456:your-bot-token"
export API_KEY="your-api-key"

Se in seguito passi dal trial al traffico reale, il credito proviene da una ricarica con cripto (USDT su TRC20, USDC su Base), da $20 a $500. La pagina dei prezzi elenca i livelli di bonus.

Un bot minimale funzionante

Inizia con la versione più piccola che risponde ai messaggi. Non ha ancora streaming né trimming, così puoi confermare prima la connessione.

import os
from collections import defaultdict

from openai import AsyncOpenAI
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, MessageHandler, filters

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

SYSTEM = "You are a friendly, direct assistant. Keep answers short unless asked for detail."
history = defaultdict(list)  # chat_id -> list of messages


async def on_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
    chat_id = update.effective_chat.id
    history[chat_id].append({"role": "user", "content": update.message.text})

    resp = await client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "system", "content": SYSTEM}] + history[chat_id],
        temperature=0.8,
    )
    answer = resp.choices[0].message.content
    history[chat_id].append({"role": "assistant", "content": answer})
    await update.message.reply_text(answer[:4000])


app = ApplicationBuilder().token(os.environ["TELEGRAM_TOKEN"]).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_text))
app.run_polling()

Eseguilo, apri il tuo bot in Telegram e dì ciao. La fetta answer[:4000] esiste perché Telegram limita un singolo messaggio a 4096 caratteri. Una risposta lunga del modello altrimenti farebbe fallire la chiamata di invio. In seguito puoi dividere le risposte lunghe in più messaggi invece di tagliarle.

L'SDK OpenAI riprova alcuni errori da solo, incluse le risposte 429, con un breve backoff. Impostare max_retries=3 ti dà un po' di margine senza scrivere ancora un ciclo di retry.

Memoria che non cresce all'infinito

Le chat completions sono stateless. Il modello sa solo ciò che invii in ogni richiesta, quindi il bot reinvia la cronologia a ogni turno. Ecco perché una cronologia illimitata è la principale trappola di costo e latenza. La finestra di contesto è di 100.000 token, che è tanto, ma paghi per ogni token di input a ogni turno e la maggior parte dei bot di chat non ne ha bisogno così tanta.

Una politica semplice funziona bene: mantieni il system prompt e conserva solo gli ultimi N messaggi. Venti messaggi, dieci dall'utente e dieci dal bot, sono adatti per una chat informale.

MAX_MESSAGES = 20


def remember(chat_id, role, content):
    h = history[chat_id]
    h.append({"role": role, "content": content})
    if len(h) > MAX_MESSAGES:
        del h[: len(h) - MAX_MESSAGES]

Tagliare a un punto arbitrario può lasciare una cronologia che inizia con un messaggio dell'assistente. Questo è innocuo per questo modello, ma se vuoi che sia ordinato, rimuovi un altro messaggio quando il primo rimanente non è dell'utente.

Per personaggi o storie lunghe in cui il modello deve ricordare fatti fin dall'inizio, il trimming li fa perdere. Due soluzioni comuni sono una nota fissata e un riepilogo scorrevole. Una nota fissata è un breve blocco di fatti che mantieni nel prompt di sistema, come i nomi e la scena attuale. Un riepilogo scorrevole chiede al modello, ogni trenta messaggi circa, di comprimere la metà più vecchia della cronologia in un paragrafo, che poi memorizzi al posto di quei messaggi.

Aggiungi un comando /reset che cancella history[chat_id]. Alla gente piace avere una pagina pulita, e questo non ti costa nulla.

Streaming della risposta modificando un messaggio

Aspettare dieci secondi per una risposta lunga sembra lento in un'app di chat. Lo streaming fa crescere la risposta sullo schermo. Telegram non accetta un messaggio token per token, quindi il trucco è inviare un segnaposto, poi modificarlo mentre il testo arriva. Modifica circa una volta al secondo al massimo. Telegram applica i suoi limiti di flood ai bot, e bombardare la chiamata di modifica a ogni token ti fa limitare e rallenta lo streaming.

import time


async def stream_answer(update, chat_id):
    msg = await update.message.reply_text("...")
    stream = await client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "system", "content": SYSTEM}] + history[chat_id],
        stream=True,
    )
    text, last_edit = "", 0.0
    async for chunk in stream:
        if not chunk.choices:
            continue
        piece = chunk.choices[0].delta.content or ""
        text += piece
        if time.monotonic() - last_edit > 1.0 and text.strip():
            await msg.edit_text(text[:4000])
            last_edit = time.monotonic()
    if text.strip():
        await msg.edit_text(text[:4000])
    return text

Due dettagli sono importanti. Primo, fai sempre una modifica finale dopo il ciclo, perché gli ultimi chunk arrivano solitamente tra le modifiche temporizzate. Secondo, Telegram rifiuta una modifica che non cambia il testo, quindi salta la chiamata quando non c'è nulla di nuovo. La libreria genera un errore per quel caso, e un try/except intorno alla modifica mantiene lo streaming attivo.

Ricorda che una richiesta in streaming tiene il suo slot di concorrenza fino alla fine dello stream. Un bot con molte chat che parlano contemporaneamente raggiungerà il limite prima con lo streaming che senza, il che porta alla sezione successiva.

Rimanere dentro i limiti di richiesta

Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di trial permette 2 e 60. Una chat di gruppo occupata può facilmente superare 2 contemporaneamente, quindi dimensiona il limite alla chiave che stai usando.

La guardia più pulita è un semaforo intorno alla chiamata del modello. Le richieste oltre il limite aspettano in coda dentro il tuo processo invece di rimbalzare sull'API:

import asyncio

slots = asyncio.Semaphore(8)  # use 2 with a trial key


async def on_text(update, context):
    chat_id = update.effective_chat.id
    remember(chat_id, "user", update.message.text)
    async with slots:
        text = await stream_answer(update, chat_id)
    remember(chat_id, "assistant", text)

Se ottieni ancora un HTTP 429, leggi il codice di errore. concurrency significa troppe chiamate contemporaneamente, rate_limited significa troppe al minuto, e un 429 con Retry-After: 5 significa sovraccarico temporaneo; aspetta i cinque secondi. Il retry dell'SDK gestisce la maggior parte di questi. Le richieste fallite o rifiutate non vengono addebitate, quindi i retry non aggiungano al conto.

Un'altra guardia è il controllo per utente. Se una singola persona invia dieci messaggi in dieci secondi, serializza le loro richieste con un lock per chat in modo che le risposte arrivino in ordine e una chat non possa usare tutti gli otto slot.

Persona, regole e chat di gruppo

Il prompt di sistema è dove il bot ottiene il suo carattere. Scrivilo come una breve descrizione: chi è il bot, come parla, quanto dovrebbero essere lunghe le risposte e qualsiasi cosa non debba fare. Per un bot di roleplay o di compagnia per adulti, descrivi l'ambientazione e il tono in poche righe e lascia che l'utente guidi da lì. Prompt specifici battono quelli lunghi; il modello segue meglio una persona chiara di cinque righe che una pagina di regole.

Alcune regole sono esterne al prompt. Il modello risponde senza filtri sui contenuti per un uso adulto lecito, ma i contenuti sessuali che coinvolgono minorenni non sono mai consentiti e dovresti far rispettare questa regola anche dal tuo lato. Se il tuo bot è aperto al pubblico, dillo nella sua descrizione, aggiungi un avviso sull'età nel messaggio iniziale e ricorda che Telegram ha i propri termini per i bot che devi anche tu seguire. Le conversazioni dei tuoi utenti vanno all'API e i prompt non vengono utilizzati per l'addestramento; informa i tuoi utenti su cosa memorizza il tuo bot.

Nelle chat di gruppo, non rispondere a ogni messaggio. Rispondi solo quando il bot viene menzionato o quando qualcuno risponde a uno dei suoi messaggi, e ignora i messaggi inviati da altri bot. Con python-telegram-bot puoi controllare update.message.entities per una menzione o confrontare update.message.reply_to_message.from_user.id con l'ID del bot.

Quando qualcosa va storto, registra l'intestazione di risposta X-Request-Id per ogni chiamata; puoi leggerla tramite l'interfaccia della risposta grezza dell'SDK. La pagina support è il luogo dove chiedere informazioni su una richiesta specifica.

Esecuzione in produzione

Il polling, come usato sopra, va bene per un bot piccolo: il processo chiede a Telegram nuovi messaggi in un ciclo e non richiede un indirizzo pubblico. Esegui il processo sotto systemd o in un container con riavvio automatico e conserva i due segreti nell'ambiente del file unit o in un archivio segreti. Una configurazione webhook riduce il carico inattivo, ma richiede HTTPS e un URL pubblico, quindi inizia con il polling.

Stima il costo prima di invitare le persone. L'API carica $0.15 per 1M di token di input e $0.50 per 1M di token di output. Un tipico turno con una cronologia ridotta di 2.000 token di input e 500 token di output costa 2.000 x $0.15 / 1M = $0.0003 per l'input più 500 x $0.50 / 1M = $0.00025 per l'output, per un totale di $0.00055. Mille turni costano $0.55. Se una chat cresce fino a 10.000 token di input per turno, la parte di input diventa da sola $0.0015, quindi il trimming ripaga rapidamente.

Quando hai bisogno di persistenza, memorizza la cronologia di ogni chat come JSON in SQLite o Redis, caricala al primo messaggio dopo un riavvio e scrivila di nuovo dopo ogni risposta. Aggiungi un limite giornaliero di messaggi per utente se il bot è pubblico, così un utente entusiasta non può svuotare il saldo. La documentazione API elenca ogni parametro che puoi regolare, e la checklist di produzione delle chiavi copre il rinnovo delle chiavi e il monitoraggio dell'intestazione del saldo.

Domande e risposte

Quale libreria usare per Telegram?

Qualsiasi libreria funziona perché il lato modello è un'API HTTP semplice. Questa guida usa python-telegram-bot versione 20 o successiva, che è asincrono e si abbina bene con il client OpenAI asincrono.

Perché il bot risponde a se stesso o a tutti in gruppo?

Nei gruppi, limita il gestore ai messaggi che menzionano il bot o gli rispondono, e ignora i messaggi dai bot. Altrimenti ogni messaggio nel gruppo innesca una chiamata al modello.

Quanto costa una conversazione con un bot?

Un breve scambio di 2.000 token di input e 500 token di output costa $0.00055, quindi mille di questi scambi costano $0.55. Le cronologie lunghe costano di più perché vengono reinviate a ogni turno.

Il bot può essere usato per il roleplay per adulti?

Il modello è ottimizzato per rispondere senza rifiuti sui contenuti per un uso adulto lecito, e i bot per chat di finzione e compagnia ne sono un caso tipico. I contenuti sessuali che coinvolgono minorenni non sono mai permessi, e Telegram ha le sue regole che devi seguire.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.

Ottieni chiave APILeggi i documenti