ES ▾
Obtener clave de API

Bot de Telegram de Uncensored Endpoint: Cómo construirlo en Python

Para construir un bot de Telegram de endpoint sin censura necesitas tres piezas: un token de bot de BotFather, una clave de API y unas 80 líneas de Python que pasen cada mensaje de Telegram a la ruta de completions de chat. Este recorrido proporciona el código completo, luego añade memoria, streaming y control de límites.

Actualizado

Puntos clave

  1. El bot usa python-telegram-bot para Telegram y el SDK estándar de OpenAI para el modelo.
  2. Mantén un historial corto por chat y recórtalo para que cada petición se mantenga pequeña y económica.
  3. Haz streaming editando un mensaje aproximadamente una vez por segundo, no en cada token.
  4. Limita las llamadas paralelas al modelo a 8 con un semáforo y reintenta las respuestas 429.
Burbuja de chat de avión de papel que sale de un terminal hacia una fila de burbujas de diálogo, representando un bot de Telegram

Lo que estás construyendo

El bot tiene un solo trabajo: tomar un mensaje de texto de un chat de Telegram, añadirlo al historial de ese chat, enviar el historial al modelo uncensored y devolver la respuesta. Cada chat de Telegram tiene su propia memoria, así que dos personas hablando con el bot nunca ven el contexto del otro.

El proyecto terminado es un solo archivo con estas partes:

  1. Un cliente para la API, usando el SDK de OpenAI apuntado a https://api.uncensoredendpoint.com/v1.
  2. Diccionario de historiales de chat, recortado para que no crezca indefinidamente.
  3. Un controlador de mensajes que transmite la respuesta editando un mensaje de Telegram.
  4. Un semáforo que te mantiene por debajo de las 8 peticiones concurrentes que permite una clave completa.

Nada de esto necesita una base de datos. Cuando el bot se reinicia, los historiales se reinician, lo cual está bien para una primera versión. Una sección posterior cubre dónde añadir persistencia.

Prerrequisitos

Necesitas Python 3.10 o superior y dos credenciales.

  • Un token de bot de Telegram. Abre un chat con BotFather dentro de Telegram, envía el comando para crear un nuevo bot, elige un nombre y un nombre de usuario, y copia el token que devuelve. Trata el token como una contraseña.
  • Una clave de API. Regístrate en la página de claves con Google o con correo electrónico y contraseña. Los nuevos usuarios pueden reclamar $0,50 de crédito de prueba con un clic, lo cual es suficiente para probar este bot muchas veces. La clave de prueba permite 2 peticiones concurrentes y 60 peticiones por minuto.

Instala las dos librerías y exporta los secretos como variables de entorno para que nunca lleguen a tu código fuente:

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

Si más tarde pasas de la prueba al tráfico real, el crédito proviene de una recarga con cripto (USDT en TRC20 o USDC en Base) de $20 a $500. La página de precios lista los niveles de bonificación.

Un bot mínimo funcional

Empieza con la versión más pequeña que responde mensajes. No tiene streaming ni recorte aún, así que puedes confirmar el funcionamiento primero.

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

Ejecútalo, abre tu bot en Telegram y di hola. El slice answer[:4000] existe porque Telegram limita un solo mensaje a 4096 caracteres. Una respuesta larga del modelo haría que la llamada de envío fallara. Más tarde puedes dividir respuestas largas en varios mensajes en lugar de cortarlas.

El SDK de OpenAI reintenta algunos fallos por su cuenta, incluidas las respuestas 429, con una breve espera. Establecer max_retries=3 te da un poco de margen sin escribir un bucle de reintento aún.

Memoria que no crece para siempre

Las completaciones de chat son sin estado. El modelo solo sabe lo que envías en cada petición, así que el bot reenvía el historial en cada turno. Por eso, un historial ilimitado es la principal trampa de coste y latencia. La ventana de contexto es de 100.000 tokens, lo cual es mucho, pero pagas por cada token de entrada en cada turno, y la mayoría de los bots de chat no necesitan ni de cerca tanto.

Una política simple funciona bien: mantén el prompt del sistema y mantén solo las últimas N mensajes. Veinte mensajes, diez del usuario y diez del bot, son adecuados para un chat casual.

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]

Cortar en un punto arbitrario puede dejar un historial que comienza con un mensaje del asistente. Eso es inofensivo para este modelo, pero si quieres que esté limpio, elimina un mensaje más cuando el primer mensaje restante no sea del usuario.

Para personajes o historias largas donde el modelo debe recordar hechos desde el principio, el recorte los pierde. Dos soluciones comunes son una nota fijada y un resumen rotativo. Una nota fijada es un bloque corto de hechos que mantienes en el prompt del sistema, como nombres y la escena actual. Un resumen rotativo pide al modelo, cada treinta mensajes más o menos, que comprima la mitad más antigua del historial en un párrafo, que luego almacenas en lugar de esos mensajes.

Añade un comando /reset que borre history[chat_id]. A la gente le gusta tener una pizarra limpia y eso no te cuesta nada.

Transmitiendo la respuesta editando un mensaje

Esperar diez segundos por una respuesta larga se siente lento en una app de chat. El streaming permite que la respuesta crezca en pantalla. Telegram no acepta un token de mensaje por token, así que el truco es enviar un marcador de posición y luego editarlo a medida que llega el texto. Edita como máximo una vez por segundo. Telegram aplica sus propios límites de tráfico a los bots y golpear la llamada de edición en cada token te ralentiza y frena el 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

Dos detalles importan. Primero, siempre haz una edición final después del bucle, porque los últimos fragmentos suelen llegar entre ediciones temporizadas. Segundo, Telegram rechaza una edición que no cambia el texto, así que salta la llamada cuando no hay nada nuevo. La librería lanza un error para ese caso, y un try/except alrededor de la edición mantiene el streaming vivo.

Recuerda que una petición en streaming mantiene su ranura de concurrencia hasta que termina el stream. Un bot con muchos chats hablando a la vez alcanzará el límite antes con streaming que sin él, lo que lleva a la siguiente sección.

Manteniéndose dentro de los límites de peticiones

Una clave completa permite 8 peticiones concurrentes y 300 peticiones por minuto. Una clave de prueba permite 2 y 60. Un chat grupal ocupado puede exceder fácilmente 2 a la vez, así que ajusta tu límite a la clave que estás usando.

La protección más limpia es un semáforo alrededor de la llamada al modelo. Las peticiones más allá del tope esperan en fila dentro de tu proceso en lugar de rebotar contra la 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)

Si aún obtienes un HTTP 429, lee el código de error. concurrency significa demasiadas llamadas a la vez, rate_limited significa demasiadas por minuto, y un 429 con Retry-After: 5 significa sobrecarga temporal; espera los cinco segundos. El reintento del SDK maneja la mayoría de estos. Las solicitudes fallidas o rechazadas no se cobran, así que los reintentos no añaden a la factura.

Otra protección es el control de velocidad por usuario. Si una sola persona envía diez mensajes en diez segundos, serializa sus peticiones con un bloqueo por chat para que las respuestas lleguen en orden y un solo chat no use las ocho ranuras.

Persona, reglas y chats grupales

El prompt del sistema es donde el bot obtiene su personalidad. Escríbelo como un breve resumen: quién es el bot, cómo habla, qué longitud deben tener las respuestas y cualquier cosa que no deba hacer. Para un bot de rol o compañero para adultos, describe el entorno y el tono en unas pocas líneas y deja que el usuario dirija la conversación a partir de ahí. Los prompts específicos superan a los largos; el modelo sigue mejor una personalidad clara de cinco líneas que una página de reglas.

Algunas reglas están fuera del prompt. El modelo responde sin rechazos de contenido para uso adulto lícito, pero el contenido sexual que involucra a menores de edad nunca está permitido, y deberías hacer cumplir eso también por tu lado. Si tu bot es abierto al público, dilo en su descripción, añade un aviso de edad en el mensaje de inicio, y recuerda que Telegram tiene sus propios términos para bots que también debes seguir. Las conversaciones de tus usuarios van a la API, y los prompts no se usan para entrenamiento; dile a tus usuarios qué almacena tu propio bot.

En chats grupales, no respondas a todos los mensajes. Responde solo cuando se mencione al bot o cuando alguien responda a uno de sus mensajes, e ignora los mensajes enviados por otros bots. En python-telegram-bot puedes comprobar update.message.entities para detectar una mención o comparar update.message.reply_to_message.from_user.id con el ID propio del bot.

Cuando algo sale mal, registra el encabezado de respuesta X-Request-Id para cada llamada; puedes leerlo a través de la interfaz de respuesta cruda del SDK. La página de soporte es el lugar para preguntar sobre una petición específica.

Ejecutarlo en producción

El sondeo, como se usa arriba, está bien para un bot pequeño: el proceso pregunta a Telegram por nuevos mensajes en un bucle y no necesita una dirección pública. Ejecútalo bajo systemd o un contenedor con reinicio automático, y mantén las dos credenciales en el entorno del archivo de la unidad o en una tienda de secretos. Una configuración de webhook reduce la carga inactiva, pero necesita HTTPS y una URL pública, así que empieza con sondeo.

Estima el coste antes de invitar a la gente. La API cobra $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida. Un turno típico con un historial recortado de 2.000 tokens de entrada y 500 tokens de salida cuesta 2.000 x $0,15 / 1M = $0,0003 para entrada más 500 x $0,50 / 1M = $0,00025 para salida, lo que suma $0,00055. Mil turnos cuestan $0,55. Si un chat crece a 10.000 tokens de entrada por turno, solo la parte de entrada se convierte en $0,0015, por lo que el recorte de tokens se paga solo rápidamente.

Cuando necesites persistencia, almacena el historial de cada chat como JSON en SQLite o Redis, cárgalo en el primer mensaje después de un reinicio y escríbelo de nuevo después de cada respuesta. Añade un límite diario de mensajes por usuario si el bot es público, para que un usuario entusiasta no pueda vaciar el saldo. La documentación de la API lista cada parámetro que puedes ajustar, y la lista de verificación de producción de claves cubre rotar claves y vigilar el encabezado de saldo.

Preguntas y respuestas

¿Qué librería debo usar para la parte de Telegram?

Cualquier librería funciona porque el lado del modelo es una API HTTP básica. Esta guía usa python-telegram-bot versión 20 o superior, que es asíncrono y se combina bien con el cliente asíncrono de OpenAI.

¿Por qué mi bot se responde a sí mismo o a todos en un grupo?

En grupos, restringe el controlador a los mensajes que mencionan al bot o le responden, e ignora los mensajes de otros bots. De lo contrario, cada mensaje en el grupo activa una llamada al modelo.

¿Cuánto cuesta una conversación con un bot?

Un intercambio breve de 2.000 tokens de entrada y 500 tokens de salida cuesta $0,00055, por lo que mil de ellos cuestan $0,55. Los historiales largos cuestan más porque se vuelven a enviar en cada turno.

¿Se puede usar el bot para juegos de roles para adultos?

El modelo está ajustado para responder sin rechazos de contenido para uso adulto lícito, y los bots para chat de ficción y compañía son un caso típico. El contenido sexual que involucre a menores de edad nunca está permitido, y Telegram tiene sus propias reglas que debes seguir.

Tu clave está a un formulario de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.

Obtener clave de APILeer la documentación