Tu primer chatbot con una API gratuita

Un modelo de lenguaje como los que hemos usado en el curso es un archivo gigante de números que necesita computadores muy potentes para funcionar. No cabe en tu portátil ni en tu celular. Entonces, ¿cómo lo usas? A través de una API.

API significa Application Programming Interface, "interfaz de programación de aplicaciones". Suena feo, pero la idea es simple: es una ventanilla para que un programa le hable a otro programa. Piensa en la ventanilla de una registraduría. Tú no entras a la bodega a buscar tu documento: llenas un formulario con un formato exacto, lo pasas por la ventanilla, y te devuelven una respuesta. Si llenas mal el formulario, te lo devuelven con un error.

Con una API pasa lo mismo, solo que el formulario es un mensaje que viaja por internet y la ventanilla es una dirección web. Tu programa en Python arma el mensaje ("este es mi texto, este es el modelo que quiero, esta es mi clave"), lo manda a los servidores de Google, y allá el modelo genera la respuesta y te la devuelve en unos segundos.

Esto tiene tres consecuencias prácticas que conviene tener claras desde ya:

• Necesitas internet. Sin conexión, tu chatbot no responde nada.
• Necesitas identificarte. Por eso existe la clave, que veremos ahora.
• La respuesta se demora. No es instantánea como imprimir un texto: hay un viaje de ida y vuelta.

Casi todo lo que usas a diario funciona así por dentro: Rappi le pregunta a una API de mapas, tu banco le pregunta a una API de la TRM. Aprender a llamar una API es aprender a conectar tu código con el resto del mundo.

Vamos a usar la API de Gemini, el modelo de Google, porque tiene un plan gratuito que sirve para aprender y para demos pequeñas, y porque no te pide tarjeta de crédito para empezar. Solo necesitas una cuenta de Google (la misma del correo).

El sitio se llama Google AI Studio. Entras, aceptas los términos y buscas la opción para crear una clave de API (Get API key o Crear clave). El sitio te genera una cadena larga de letras y números, algo como AIzaSy.... Esa cadena es tu clave de API.

Aquí viene lo más importante de toda la lección, y no es técnico: esa clave es una contraseña. Cualquiera que la vea puede hacer llamadas al modelo como si fuera tú, gastarse tus límites gratis y, si algún día activas facturación, generarte cobros. Reglas duras:

• Nunca la pegues dentro del código que vas a compartir, subir a GitHub o mostrar en un video.
• Nunca la mandes por chat a alguien "para que pruebe".
• Si crees que se filtró, vuelve a AI Studio, bórrala y crea otra. Es gratis y toma diez segundos.

¿Y dónde la guardas entonces? En un lugar aparte del código, que se llama secreto o variable de entorno: una gaveta donde el programa busca el valor cuando lo necesita, sin que el valor aparezca escrito en el archivo.

En Google Colab —el cuaderno de Python en el navegador que usamos en la lección 4— esa gaveta es el ícono de la llavecita en la barra izquierda, llamado Secrets. Le pones un nombre, por ejemplo GOOGLE_API_KEY, pegas el valor y activas el acceso para ese cuaderno. Listo: tu clave queda guardada en tu cuenta, no en el código.

Abre un cuaderno nuevo en Google Colab (colab.research.google.com). Un cuaderno es una página con celdas donde escribes Python y le das play; funciona en el navegador, incluso desde el celular, y no tienes que instalar nada en tu computador.

Primera celda, instalar la librería oficial de Google:

!pip install -q google-genai

El signo ! le dice a Colab "esto no es Python, es un comando del sistema". pip es el instalador de librerías de Python; -q es para que no llene la pantalla de texto.

Segunda celda, la llamada:

from google import genai
from google.colab import userdata

cliente = genai.Client(api_key=userdata.get("GOOGLE_API_KEY"))

respuesta = cliente.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explica en dos frases qué es una API, para alguien de 15 años."
)

print(respuesta.text)

Léelo despacio, como aprendiste en la lección 2:

• userdata.get("GOOGLE_API_KEY") va a la gaveta de secretos y trae la clave. La clave nunca aparece escrita.
• genai.Client(...) crea el cliente: el objeto que sabe cómo hablarle a la ventanilla.
• generate_content es la llamada. model dice cuál modelo quieres (los rápidos y baratos suelen tener "flash" en el nombre; los nombres exactos cambian con el tiempo, así que verifica la lista disponible en AI Studio).
• contents es tu mensaje.
• respuesta no es un texto: es un objeto con varias cosas adentro. Por eso pides respuesta.text, que es la parte que te interesa.

Si te sale un error rojo largo, no te asustes: cópialo completo y pégaselo a tu asistente de IA preguntando "¿qué significa este error y cómo lo arreglo?". Eso es exactamente lo que hace un programador con experiencia.

Lo que tienes ahora responde una pregunta y se olvida de todo. Un chatbot de verdad necesita dos cosas más: personalidad y memoria de la conversación.

La personalidad se define con una instrucción de sistema (system instruction): un texto que el modelo lee antes de cada respuesta y que funciona como su manual de trabajo. No se lo muestras al usuario; es el guion detrás de escena. La memoria se logra con un chat, que es un objeto que va guardando los mensajes anteriores y los reenvía cada vez.

from google.genai import types

config = types.GenerateContentConfig(
    system_instruction=(
        "Eres Tutora, una profe de matemáticas de grado 11 en Colombia. "
        "Hablas de tú, en máximo 5 frases, con ejemplos de la vida diaria "
        "(buses, tienda de barrio, pesos colombianos). "
        "Nunca das la respuesta de una: primero haces una pregunta guía. "
        "Si te preguntan algo que no es matemáticas, dices con amabilidad "
        "que solo ayudas con matemáticas."
    ),
    temperature=0.7,
)

chat = cliente.chats.create(model="gemini-2.5-flash", config=config)

print(chat.send_message("Hola, no entiendo las ecuaciones cuadráticas").text)
print(chat.send_message("¿Y eso para qué me sirve?").text)

Fíjate en el segundo mensaje: "¿Y eso para qué me sirve?" no dice de qué está hablando. El bot lo entiende porque el chat recordó el mensaje anterior. Si hubieras usado generate_content dos veces, la segunda respuesta habría sido genérica.

temperature controla qué tan predecible es el modelo: cerca de 0 responde parecido siempre (bueno para datos y resúmenes), cerca de 1 se suelta más (bueno para ideas y conversación).

La clave de una buena personalidad está en ser específico y poner límites. "Sé amable" no sirve de nada. "Máximo 5 frases, con ejemplos colombianos, siempre pregunta antes de responder, no hables de otros temas" sí cambia el comportamiento. Escribe la instrucción, prueba, y ajústala cuando el bot haga algo que no querías.

Un chatbot dentro de un cuaderno de Colab no se lo puedes mandar a tu mamá. Para eso existe Gradio, una librería que convierte una función de Python en una interfaz de chat con caja de texto y burbujas, sin que escribas nada de HTML.

Primero pruébalo dentro de Colab:

!pip install -q gradio
import gradio as gr

def responder(mensaje, historial):
    return chat.send_message(mensaje).text

gr.ChatInterface(fn=responder, title="Tutora de mate").launch(share=True)

Gradio te llama tu función responder cada vez que alguien escribe. Con share=True te genera un enlace temporal que sí puedes abrir en el celular y pasarle a alguien; ese enlace expira a las pocas horas y solo funciona mientras el cuaderno esté prendido.

Para algo permanente y gratis está Hugging Face Spaces: creas una cuenta, creas un Space nuevo, eliges Gradio como tipo, y subes dos archivos.

requirements.txt, que dice qué librerías necesita:

google-genai
gradio

app.py, con el mismo código de arriba, pero leyendo la clave desde el entorno en vez de Colab:

import os
from google import genai
cliente = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])

Y la clave la pegas en la configuración del Space, en la sección de Secrets, con el nombre GOOGLE_API_KEY. Nunca dentro de app.py, porque el código de un Space público lo puede leer cualquiera.

En un par de minutos el Space se construye solo y te queda una página web con tu bot, con dirección propia. Ese es el enlace que compartes: tu primer programa publicado en internet.

Publicar algo en internet trae una responsabilidad chiquita pero real. Tu chatbot tiene cuatro límites que debes conocer y, si otras personas lo van a usar, decirlos en la misma página.

Alucina. El modelo puede afirmar con total seguridad cosas falsas: fechas, artículos de una ley, cifras, nombres. Si tu bot ayuda con tareas o trámites, escribe en la instrucción de sistema que debe reconocer cuando no está seguro, y pon una advertencia visible: "verifica siempre en la fuente oficial".

Tiene sesgos. Aprendió de textos de internet, donde el español de España y el contenido de Estados Unidos pesan mucho más que el contexto colombiano. Puede darte ejemplos que aquí no aplican, o asumir realidades que no son las de tu región.

No es privado. Todo lo que un usuario escriba viaja a los servidores del proveedor. Nunca pongas ahí datos sensibles: cédulas, historias clínicas, direcciones, datos de menores de edad. Si tu bot es para un colegio, dilo claramente y no pidas datos personales.

Tiene límites de uso. El plan gratuito permite cierta cantidad de llamadas; si te pasas, el programa devuelve un error en vez de una respuesta. Es normal y no significa que rompiste nada: espera un rato o baja la frecuencia de las pruebas. Y si algún día activas facturación, cada llamada cuesta, así que revisa antes de dejar un bot abierto al público.

Decir estos límites no hace ver tu proyecto peor. Al contrario: quien los declara demuestra que entiende de verdad la herramienta que está usando.