Objetivos
- Leer un programa corto de Python y entender qué hace cada bloque: variables, textos, diccionarios, condiciones e import.
- Crear y activar un entorno virtual con venv o con uv, y saber por qué cada proyecto lleva el suyo.
- Instalar librerías con pip desde un fichero requirements.txt.
- Ejecutar un script que lee la clave del fichero .env, pregunta a Gemini (Google AI Studio, sin coste) y guarda la respuesta en respuesta.md.
- Reconocer y resolver los errores típicos: directiva de ejecución en Windows, clave inválida (400/401) y límite (429).
Antes de empezar: pe01 (Python funcionando), pe02 (clave de Google AI Studio en .env) y pe03 (qué es una petición HTTP).
Prompt de arranque
Escribe un script de Python llamado pregunta.py para principiantes. Debe: 1) leer mi clave de un fichero .env con python-dotenv (variable GEMINI_API_KEY), 2) enviar una pregunta a Gemini con la librería oficial google-genai y el modelo gemini-flash-latest, 3) si la API devuelve un error (clave inválida, límite superado), mostrar el código y un mensaje claro, y salir, 4) imprimir la respuesta y guardarla en respuesta.md. La pregunta se pasa como argumento al ejecutar el script. Comenta cada bloque en castellano. Dame también el requirements.txt. No escribas mi clave en el código.
Esto lo escribe la IA, tú compruebas que funciona. Abajo tienes la versión ya probada para comparar: si la IA te da algo distinto, no pasa nada, lo importante es que al ejecutarlo veas la respuesta y el fichero
respuesta.md.
Explicación
Programar con IA: tú diriges, la IA escribe
«Sin saber programar» no significa «sin código». El código lo escribe la IA; tú pides con claridad, ejecutas y compruebas que funciona. Para comprobar sí necesitas leer Python a un nivel mínimo, igual que para revisar un contrato no hace falta ser abogado, pero sí saber dónde están el precio y la fecha.
Python en cinco piezas
Un programa de Python es una lista de instrucciones que el ordenador sigue de arriba abajo, como una receta. Con cinco piezas lees el 90 % de lo que vas a ver en el Curso 0.
1. Variables: cajas con etiqueta. Una variable guarda un valor con un nombre para usarlo después.
pregunta = "¿Qué es una API?"
intentos = 3
El = no es «igual» de matemáticas: significa «guarda esto en esta caja».
2. Textos y números. Los textos van entre comillas ("hola"); los números, sin ellas (3). Un truco que verás mucho son los textos con f delante, que rellenan huecos entre llaves:
nombre = "Ana"
print(f"Hola, {nombre}") # muestra: Hola, Ana
3. Diccionarios: fichas con campos. Un diccionario agrupa datos con nombre, como una ficha de cliente. Se escribe con llaves y pares "campo": valor:
ficha = {"nombre": "Ana", "ciudad": "Sevilla"}
print(ficha["ciudad"]) # muestra: Sevilla
Esto es importante porque las API responden con fichas así (en formato JSON, el que viste en pe03), y un programa tiene que saber sacar el campo que le interesa.
4. Condiciones: si pasa esto, haz aquello. Con if el programa decide. Lo que va dentro de la condición se escribe con sangría (cuatro espacios). En Python la sangría no es decoración: indica qué instrucciones dependen de la condición.
if not clave:
print("Falta la clave")
Se lee: «si no hay clave, avisa». Con try y except el programa hace algo parecido con los errores: «intenta esto y, si falla, haz aquello en vez de romperte».
5. import: traer herramientas. Python trae muchas herramientas de serie y otras se instalan aparte. import las pone a mano:
import os # viene con Python: leer variables del sistema
from google import genai # se instala aparte: hablar con Gemini
Con eso, y sabiendo que # marca un comentario (texto para humanos que Python ignora), ya puedes leer el script de esta unidad.
Las librerías: no reinventar la rueda
Una librería (o paquete) es código que otra persona ya escribió y que tú reutilizas. Preparar a mano una petición HTTP a la IA, con su clave, su formato y su manejo de errores, llevaría decenas de líneas; con la librería oficial de Google son tres. Usaremos dos:
- **
google-genai**, la librería oficial de Google para hablar con Gemini. Por dentro hace la petición HTTP (lo que en pe03 hacías concurl). - **
python-dotenv**, para leer la clave del fichero.envque preparaste en pe02.
Las librerías se instalan con **pip**, el gestor de paquetes de Python: la tienda de aplicaciones de pe01, pero solo para piezas de Python.
El entorno virtual: una caja de herramientas por proyecto
Imagina que tienes un único cajón de herramientas para toda la casa. Para montar la estantería necesitas una llave del 10; para la bici, una del 12 «que ya no se fabrica». Si cambias una, rompes la otra. La solución: una caja de herramientas por proyecto.
Eso es un entorno virtual: una carpeta (por convención, .venv) dentro de tu proyecto con su propio Python y sus propias librerías. Lo que instalas ahí no toca el resto del ordenador ni otros proyectos. Y si algo se rompe, borras la carpeta .venv y la vuelves a crear en un minuto.
Para usarlo hay que activarlo. Activar es como decirle a la terminal «a partir de ahora, usa la caja de este proyecto». Sabrás que está activo porque al principio de la línea aparece (.venv). Si cierras la terminal, se desactiva, y la próxima vez hay que activarlo de nuevo.
Por eso el .gitignore de pe02 incluye .venv/: la caja no se sube, se reconstruye.
requirements.txt: la lista de la compra
¿Cómo se reconstruye la caja en otro ordenador? Con un fichero **requirements.txt** que lista las librerías que necesita el proyecto, una por línea. Con un solo comando, pip install -r requirements.txt, se instala todo. Es la lista de la compra del proyecto: la escribes una vez y cualquiera puede repetir la compra.
venv o uv: dos maneras de hacer lo mismo
- **
venv+pip** vienen con Python. No hay que instalar nada más. Es la vía clásica, la que encontrarás en casi todos los tutoriales. - **
uv** es una herramienta moderna que hace lo mismo mucho más rápido y, además, puede ejecutar el script sin activar el entorno (uv run). En Windows esto tiene una ventaja: te ahorra el error de directiva de ejecución al activar.
Las dos llevan al mismo sitio: una carpeta .venv con tus librerías. Elige una y sigue solo esa ruta en el lab.
Qué hace el script, en castellano
El script pregunta.py sigue cinco pasos, los mismos que harías tú a mano:
- Abre la caja fuerte: lee el
.envy carga la claveGEMINI_API_KEY. - Prepara la pregunta: la que escribas al ejecutar el comando, o una de ejemplo.
- Pregunta a Gemini: la librería hace la petición HTTP (
POST, como viste en pe03) y enseña la clave por ti. - Si algo falla, lo dice claro: clave inválida, límite superado u otro error, con su código.
- Si todo va bien, muestra el texto y lo guarda en
respuesta.md.
La clave no aparece en el código, solo el nombre de la variable.
Por qué Google AI Studio
Es el proveedor por defecto del Curso 0 porque su nivel sin coste no pide tarjeta y Gemini responde bien en castellano. Usamos el nombre de modelo gemini-flash-latest, un alias que Google apunta siempre al Flash más reciente, para que el script no se quede viejo cuando salgan versiones nuevas.
Un detalle curioso: si la clave es falsa, Google responde con el mismo 401 de pe03 si es de las nuevas (AQ.), pero con un 400 («API key not valid») si es de las antiguas (AIza). Cada proveedor tiene su estilo; por eso el script trata 400, 401 y 403 como «revisa tu clave». El 429 («demasiadas peticiones») sí es igual en todos.
Lab paso a paso
Objetivo: dentro de la carpeta mi-primera-ia de pe02 (la que ya tiene .env y .gitignore), crear el entorno, instalar las librerías, ejecutar pregunta.py y obtener respuesta.md.
Paso 1. Entrar en la carpeta del proyecto
Windows (PowerShell)
cd $HOME\lab\mi-primera-ia
macOS y Ubuntu
cd ~/lab/mi-primera-iaPaso 2. Escribir requirements.txt
En VS Code, crea requirements.txt con estas dos líneas:
google-genai
python-dotenvPaso 3. Revisar el .env
Abre .env (lo creaste en pe02). Debe tener tu clave de Google AI Studio, sin espacios alrededor del = y sin comillas:
GEMINI_API_KEY=AQ.pega_aqui_tu_clavePaso 4. Crear pregunta.py
En VS Code, crea pregunta.py y pega esto:
import os
import sys
from dotenv import load_dotenv
from google import genai
from google.genai import errors
# 1. Lee el fichero .env y carga tu clave como variable de entorno
load_dotenv()
clave = os.getenv("GEMINI_API_KEY")
if not clave:
sys.exit("Falta GEMINI_API_KEY en el fichero .env")
# 2. La pregunta: la que escribas detrás del comando, o una de ejemplo
pregunta = " ".join(sys.argv[1:]) or "Explícame en dos frases qué es una API."
# 3. La petición a la IA (la librería hace la petición HTTP por ti)
cliente = genai.Client(api_key=clave)
try:
respuesta = cliente.models.generate_content(
model="gemini-flash-latest",
contents=pregunta,
)
except errors.APIError as error:
# 4. Si algo falla, muestra el código y el motivo, y para
if error.code in (400, 401, 403):
sys.exit(f"Error {error.code}: la clave no es válida o no tiene permiso. Revisa GEMINI_API_KEY en .env.")
if error.code == 429:
sys.exit("Error 429: has superado el límite gratuito (por minuto o del día). Espera un minuto; si sigue, prueba mañana.")
sys.exit(f"Error {error.code}: {error.message}")
texto = respuesta.text
print(texto)
# 5. Guarda la respuesta en un fichero
with open("respuesta.md", "w", encoding="utf-8") as fichero:
fichero.write(f"# {pregunta}\n\n{texto}\n")
print("\nRespuesta guardada en respuesta.md")
El paso 5 tiene dos rutas que hacen lo mismo: elige una, la A o la B, no las dos. La A usa lo que trae Python; la B usa uv, más rápido. Si ya creaste .venv con la ruta A, no ejecutes uv venv: avisará de que el entorno ya existe.
Paso 5, ruta A. Entorno con venv y pip (viene con Python)
Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Si al activar aparece el error de «la ejecución de scripts está deshabilitada», ejecuta una vez Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, responde S y repite la activación (lo explicamos en los errores frecuentes).
macOS, Ubuntu y Codespaces
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Qué debe verse: la línea de la terminal empieza por (.venv) y pip termina con Successfully installed ... google-genai-x.x.x ... python-dotenv-1.x.x ....
Paso 5, ruta B. Entorno con uv (más rápido)
Instala uv una vez:
Windows
winget install --id=astral-sh.uv -e
macOS
brew install uv
Ubuntu y Codespaces
curl -LsSf https://astral.sh/uv/install.sh | sh
Cierra y abre la terminal, vuelve a la carpeta del proyecto (paso 1) y ejecuta (igual en los tres sistemas):
uv --version
uv venv
uv pip install -r requirements.txt
Qué debe verse: uv 0.x.x, después Creating virtual environment at: .venv y una lista de paquetes con + google-genai y + python-dotenv, entre otros.
Paso 6. Ejecutar el script
Con venv activado (ruta A)
python pregunta.py "Dame tres ideas de apps sencillas que podría construir con IA"
(Dentro del entorno activado, python funciona también en macOS y Linux).
Con uv (ruta B), sin activar nada
uv run pregunta.py "Dame tres ideas de apps sencillas que podría construir con IA"
Qué debe verse: unos segundos de espera y el texto de la IA en la terminal, terminando con:
Respuesta guardada en respuesta.md
Abre respuesta.md en VS Code: tu pregunta como título y la respuesta debajo.
Paso 7. Provocar un error de clave a propósito
Edita .env, borra el último carácter de tu clave, guarda y ejecuta otra vez el script. Debe verse:
Error 401: la clave no es válida o no tiene permiso. Revisa GEMINI_API_KEY en .env.
Restaura la clave correcta y vuelve a ejecutar. Acabas de leer tu primer error de API: «no te reconozco».
Alternativa: Groq
Si Google AI Studio no te funciona (por ejemplo, con una cuenta del trabajo), usa Groq con la clave GROQ_API_KEY de pe02. Cambia google-genai por requests en requirements.txt y reinstala. En el script, borra las dos líneas from google..., cambia GEMINI_API_KEY por GROQ_API_KEY en el paso 1 y sustituye los pasos 3 y 4 por esto (el paso 5 se queda igual):
import requests # mejor arriba, junto a los demás import
respuesta = requests.post(
"https://api.groq.com/openai/v1/chat/completions",
headers={"Authorization": f"Bearer {clave}"},
json={"model": "llama-3.1-8b-instant",
"messages": [{"role": "user", "content": pregunta}]},
timeout=60,
)
if respuesta.status_code == 401:
sys.exit("Error 401: la clave no es válida. Revisa GROQ_API_KEY en .env.")
if respuesta.status_code == 429:
sys.exit("Error 429: has superado el límite gratuito (por minuto o del día). Espera un minuto; si sigue, prueba mañana.")
if respuesta.status_code != 200:
sys.exit(f"Error {respuesta.status_code}: {respuesta.text[:300]}")
texto = respuesta.json()["choices"][0]["message"]["content"]
Groq también responde 401 ante una clave falsa.
Evidencia
- Captura de la terminal con el comando ejecutado y la respuesta de la IA (sin la clave en pantalla).
- El fichero
respuesta.mdgenerado. - Captura del error de clave provocado en el paso 7.
Criterio de aceptación
URLs de activación
Verificadas el 11-10-2026 (200 OK).
| Para qué | URL oficial |
|---|---|
| Clave de Google AI Studio | https://aistudio.google.com/apikey |
Modelos de Gemini y alias latest | https://ai.google.dev/gemini-api/docs/models |
| Límites del nivel sin coste de Gemini | https://ai.google.dev/gemini-api/docs/rate-limits |
| Librería google-genai | https://pypi.org/project/google-genai/ |
| Librería python-dotenv | https://pypi.org/project/python-dotenv/ |
| Instalar uv | https://docs.astral.sh/uv/getting-started/installation/ |
| Entornos virtuales (venv) | https://docs.python.org/es/3/library/venv.html |
| Alternativa: clave y modelos de Groq | https://console.groq.com/keys · https://console.groq.com/docs/models |
| Directivas de ejecución de PowerShell | https://learn.microsoft.com/es-es/powershell/module/microsoft.powershell.core/about/about_execution_policies |
Errores frecuentes
| Síntoma | Qué pasa | Cómo se arregla |
|---|---|---|
.venv\Scripts\Activate.ps1 no se puede cargar porque la ejecución de scripts está deshabilitada en este sistema | Windows bloquea por defecto los scripts de PowerShell, y activar el entorno es un script. | Ejecuta Set-ExecutionPolicy -Scope CurrentUser RemoteSigned y responde S. Alternativa sin tocar nada: la ruta B con uv run, que no necesita activar. |
ModuleNotFoundError: No module named 'google' (o 'dotenv') | El entorno no está activado, o instalaste las librerías fuera de él. | Comprueba que la línea empieza por (.venv). Si no, actívalo y repite pip install -r requirements.txt. Con uv, usa uv run en lugar de python. |
Falta GROQ_API_KEY en el fichero .env | El script no encuentra la clave: el fichero no se llama exactamente .env, está en otra carpeta o la variable tiene otro nombre. | Ejecuta el script desde la carpeta del proyecto. Comprueba el nombre del fichero (Get-ChildItem -Force o ls -la) y que la línea es GROQ_API_KEY=... sin espacios. |
Error 400 o Error 401: la clave no es válida | Clave mal copiada, con espacios o comillas, de otro proveedor o borrada. Google responde 401 (400 si la clave es antigua, AIza); Groq, 401. | Copia de nuevo la clave desde AI Studio, sin espacios ni comillas. Comprueba que empieza por AQ. (o por AIza, si es antigua). Si dudas, crea una nueva. |
Error 429: límite superado | Has superado el límite de peticiones por minuto o por día del nivel sin coste. | Espera un minuto y vuelve a probar. Si es el límite diario, espera al día siguiente o usa la alternativa Groq con su propia clave. |
Error 402: créditos de prepago agotados | La clave pertenece a un proyecto de Google con facturación de prepago y sin saldo. | Crea la clave en un proyecto sin facturación (nivel sin coste) en AI Studio. |
Error 404 o «model not found» | El nombre del modelo ha cambiado o se ha retirado. | Consulta la lista oficial de modelos y cambia la línea model= del script. |
Quiz
Cinco preguntas para comprobar que lo has entendido. Necesitas un 70 % para aprobar.