Objetivos
- Entender qué es una API y por qué convierte un script en una app que otros pueden usar.
- Crear un proyecto con uv, instalar FastAPI y arrancarlo con un solo comando: fastapi dev.
- Tener dos direcciones funcionando: /saludo, que responde siempre, y /preguntar, que consulta a Gemini con tu clave de .env.
- Probar tu API desde el navegador, desde la documentación automática /docs y con curl.
- Reconocer los errores típicos (puerto ocupado, módulo no encontrado, 401, 429, 422) y saber qué hacer con cada uno.
Antes de empezar: pe01 (Python y VS Code), pe02 (clave de Google AI Studio en .env), pe03 (localhost y puertos) y pe04 (uv y google-genai).
Prompt de arranque
Esta unidad empieza, como todas, con el prompt que genera el código. Pégalo en ChatGPT, Gemini o Claude tal cual:
Nunca he programado. Tengo Python 3.12 y uv instalados, y una clave de Google
AI Studio guardada en un fichero .env con el nombre GEMINI_API_KEY. Quiero una
API con FastAPI en un único fichero main.py que tenga:
1) GET /saludo, que devuelva {"mensaje": "Hola, <nombre>. Tu API funciona."}
con un parámetro opcional nombre.
2) POST /preguntar, que reciba {"pregunta": "..."} y devuelva la respuesta de
Gemini usando la librería google-genai.
Si falta la clave o Google la rechaza, quiero un error claro en español.
Dame también los comandos de uv para crear el proyecto, instalar
"fastapi[standard]" y arrancarlo con fastapi dev, y explícame en una frase
qué hace cada parte del código.
Esto lo escribe la IA, tú compruebas que funciona. Más abajo tienes el código ya probado (11-10-2026) para comparar lo que te dé la IA con lo que funciona de verdad.
Explicación
De un script a una app
En pe04 escribiste un script: lo ejecutas, pregunta a la IA, guarda la respuesta y termina. Funciona, pero solo para ti y solo cuando tú lo lanzas. Una app es otra cosa: está encendida, esperando, y cualquiera (una web, un móvil, una automatización de n8n, otro programa) puede pedirle algo en cualquier momento.
La pieza que hace ese cambio se llama API. Piensa en la ventanilla de una oficina de correos. Tú no entras al almacén ni sabes cómo se organizan los paquetes: te acercas a la ventanilla, pides algo con un formato concreto («quiero enviar esto a esta dirección») y te devuelven una respuesta («aquí tiene su resguardo»). Una API es exactamente eso para los programas: una ventanilla con reglas claras sobre qué se puede pedir y qué se recibe.
Cada ventanilla tiene un rótulo. En una API, los rótulos son las rutas o endpoints: /saludo, /preguntar. Recuerda de pe03 que una URL como http://127.0.0.1:8000/saludo tiene tres partes: la máquina (127.0.0.1, tu propio ordenador), el puerto (8000, la puerta por la que escucha tu app) y la ruta (/saludo, la ventanilla concreta).
Qué es FastAPI y por qué lo usamos
FastAPI es una librería de Python para montar APIs escribiendo muy poco. Es la más usada hoy en proyectos con IA por tres motivos que te importan como principiante:
- Se lee casi como una frase.
@app.get("/saludo")significa «cuando alguien pida la ventanilla /saludo, ejecuta esta función». - Comprueba los datos por ti. Si alguien envía una petición sin el campo
pregunta, FastAPI responde un error 422 explicando qué falta, sin que tú escribas nada. - Te regala la documentación. Visita
/docsy tendrás una página web donde ver todas tus rutas y probarlas con un botón. Es tu panel de control.
FastAPI no se ejecuta solo: necesita un servidor que escuche en el puerto y le pase cada petición. Ese servidor se llama uvicorn. La analogía: FastAPI es el empleado que sabe atender cada ventanilla; uvicorn es el edificio con la puerta abierta. Al instalar fastapi[standard] (los corchetes significan «con sus extras habituales») viene todo junto: FastAPI, uvicorn y el comando fastapi, que arranca tu app con una sola orden.
GET y POST: mirar o entregar
Las peticiones HTTP llevan un verbo. Para empezar te bastan dos:
- GET es «dame algo». Es lo que hace el navegador cuando escribes una dirección.
/saludoes GET: no envías nada, solo pides. - POST es «toma esto y haz algo con ello».
/preguntares POST porque le entregas un paquete con tu pregunta en formato JSON (el idioma común de las APIs: llaves, comillas y pares"nombre": valor).
El navegador solo hace GET desde la barra de direcciones. Para POST usarás /docs o curl, la herramienta de terminal que conoces de pe03.
La clave sigue en .env, nunca en el código
Tu app llama a Gemini igual que el script de pe04, con el mismo cliente google-genai y la clave que guardaste en .env en pe02. La línea load_dotenv() lee ese fichero al arrancar y os.getenv("GEMINI_API_KEY") recupera la clave. El código nunca la contiene: si mañana compartes el proyecto o lo subes a GitHub (pe06), la clave se queda en tu ordenador.
Hemos añadido comprobaciones que te ahorrarán sustos. Si falta la clave, la API responde «Falta GEMINI_API_KEY en el fichero .env» en lugar de un fallo incomprensible. Si Google la rechaza, devuelve un 401 con una frase clara. Un buen error dice qué pasa y qué hacer; lo aprovecharás en pe06.
Un detalle curioso: cuando la clave es incorrecta, Google contesta con el texto «API key not valid», con un código 401 si la clave es de las nuevas (AQ.) y 400 si es de las antiguas (AIza). Nuestra API mira ese texto y responde siempre 401, que es el código estándar para «no sé quién eres». Así, si un día cambias de proveedor, el significado se mantiene.
El modelo y la alternativa
Usamos Google AI Studio porque no pide tarjeta. El modelo por defecto es gemini-flash-latest, el mismo alias que en pe04: Google lo apunta siempre al Flash más reciente. Los nombres y los límites gratuitos cambian: si un día la API dice que el modelo no existe, añade a tu .env una línea MODELO= con otro nombre de la página oficial de modelos, sin tocar el código.
Alternativa: Groq. Si prefieres Groq (pe02), el script de pe04 con
httpxte sirve de base: pide a la IA que adapte/preguntarpara usarGROQ_API_KEYy la URL compatible con OpenAI de Groq. El resto de la unidad es idéntico.
Qué significa «está en localhost»
Al arrancar, la terminal dice Server started at http://127.0.0.1:8000. Tu API solo es visible desde tu ordenador. Nadie en Internet puede llegar a ella, y eso es perfecto para aprender: puedes romper lo que quieras. Llevarla a Internet es otra historia (pe07, opcional).
Lab paso a paso
Objetivo del lab: una API en http://127.0.0.1:8000 con /saludo y /preguntar funcionando, probada desde el navegador, /docs y la terminal.
Trabajamos en ~/lab/mi-api (en Windows, C:\Users\<tu usuario>\lab\mi-api). Abre la terminal: PowerShell en Windows, Terminal en macOS o Ubuntu. En Codespaces valen los pasos de macOS y Linux.
Paso 1. Crear el proyecto e instalar FastAPI
Igual en los tres sistemas:
cd ~
mkdir lab
cd lab
uv init mi-api
cd mi-api
uv add "fastapi[standard]" google-genai python-dotenv
Si mkdir lab dice que la carpeta ya existe, sigue con cd lab. Salida esperada (las versiones pueden ser más nuevas):
Initialized project `mi-api` at `.../lab/mi-api`
Resolved 68 packages in ...
+ fastapi==0.143.0
+ google-genai==2.29.0
+ python-dotenv==1.2.4
+ uvicorn==0.54.0
uv init creó la carpeta con un pyproject.toml (la lista de ingredientes) y, según tu versión de uv, un main.py de ejemplo (hasta la 0.12) o una carpeta src/mi_api (desde la 0.13, verificado el 12-10-2026); uv add instaló las librerías en el entorno virtual .venv de la carpeta. La carpeta src no estorba: no hace falta tocarla.
Paso 2. Copiar la clave al proyecto
Abre la carpeta en VS Code (Archivo > Abrir carpeta > mi-api), crea un archivo .env y escribe:
GEMINI_API_KEY=pega_aquí_tu_clave
Sin espacios alrededor del = y sin comillas. En Windows, comprueba que se llama .env y no .env.txt (Explorador: Vista > Mostrar > Extensiones de nombre de archivo).
Paso 3. Escribir main.py
Si ya tienes un main.py, borra lo que trae; si no lo tienes (uv 0.13 o posterior), créalo en VS Code dentro de mi-api, al lado de pyproject.toml. Pega esto (o lo que te dio la IA, si coincide en lo esencial):
import os
from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException
from google import genai
from google.genai import errors
from pydantic import BaseModel
load_dotenv() # lee el fichero .env de esta carpeta
MODELO = os.getenv("MODELO", "gemini-flash-latest")
app = FastAPI(title="Mi primera API con IA", version="0.1.0")
class Pregunta(BaseModel):
pregunta: str
@app.get("/saludo")
def saludo(nombre: str = "builder"):
return {"mensaje": f"Hola, {nombre}. Tu API funciona."}
@app.post("/preguntar")
def preguntar(datos: Pregunta):
clave = os.getenv("GEMINI_API_KEY")
if not clave:
raise HTTPException(500, "Falta GEMINI_API_KEY en el fichero .env. Revisa la unidad pe02.")
cliente = genai.Client(api_key=clave)
try:
respuesta = cliente.models.generate_content(model=MODELO, contents=datos.pregunta)
except errors.APIError as error:
if "API key" in str(error.message):
raise HTTPException(401, "Google ha rechazado tu clave. ¿Está bien copiada en .env?")
if error.code == 429:
raise HTTPException(429, "Has superado el límite gratuito (por minuto o del día). Espera un minuto; si sigue, prueba mañana.")
if error.code == 404:
raise HTTPException(404, f"El modelo {MODELO} no existe. Cambia MODELO en .env.")
raise HTTPException(502, f"Google respondió {error.code}: {error.message}")
return {"modelo": MODELO, "respuesta": respuesta.text}
Guarda con Ctrl+S (Cmd+S en macOS).
Paso 4. Arrancar la API
Igual en los tres sistemas, desde mi-api:
uv run fastapi dev main.py
Salida esperada (resumida):
⚡️ Starting FastAPI in development mode
🌐 Server started at http://127.0.0.1:8000
Documentation at http://127.0.0.1:8000/docs
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Application startup complete.
fastapi dev arranca uvicorn en modo desarrollo: reinicia la API sola cada vez que guardas un .py. Deja esta terminal abierta: mientras esté encendida, tu API responde. Para las pruebas con curl abre una segunda terminal.
Paso 6. Probar desde la terminal
En la segunda terminal.
macOS y Linux:
curl http://127.0.0.1:8000/saludo
curl -X POST http://127.0.0.1:8000/preguntar \
-H "Content-Type: application/json" \
-d '{"pregunta": "Dime tres usos de una API, una frase cada uno"}'
Windows (PowerShell). Ahí curl a secas es un alias de Invoke-WebRequest. Usa curl.exe para GET e Invoke-RestMethod para POST, que evita los problemas de comillas:
curl.exe http://127.0.0.1:8000/saludo
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/preguntar `
-ContentType "application/json" `
-Body '{"pregunta": "Dime tres usos de una API, una frase cada uno"}'
Salida esperada del POST (el texto cambia cada vez):
{"modelo":"gemini-flash-latest","respuesta":"1. Conectar una web con una base de datos..."}Paso 7. Ver qué pasa sin clave
Cambia en .env el nombre de la variable a GEMINI_API_KEY_X y guarda. Para la API con Ctrl+C y arráncala de nuevo (el .env solo se lee al arrancar). Repite el POST con curl -i (en Windows, la respuesta se ve en /docs):
HTTP/1.1 500 Internal Server Error
{"detail":"Falta GEMINI_API_KEY en el fichero .env. Revisa la unidad pe02."}
Deja .env como estaba, reinicia y comprueba que vuelve a funcionar.
Paso 8. Parar la API
En la terminal del servidor, pulsa Ctrl+C (también en macOS). Si recargas http://127.0.0.1:8000/saludo, el navegador dirá que no puede conectar: ya no hay nadie escuchando en el puerto 8000.
Ruta sin instalar nada: GitHub Codespaces
Haz los pasos 1 a 4 en la terminal del Codespace. Al arrancar, VS Code avisa de que hay una aplicación en el puerto 8000: pulsa Open in Browser y añade /docs a la dirección. Crea el .env desde el explorador de archivos; en pe06 lo excluirás de Git.
Evidencia
Dos capturas: (1) /docs con POST /preguntar ejecutado, Code 200 y la respuesta de Gemini; (2) la terminal con la respuesta a /saludo. Que no se vea la clave ni el contenido de .env.
Criterio de aceptación
URLs de activación
Verificadas el 11-10-2026 (200 OK).
| Para qué | URL oficial |
|---|---|
| Tutorial oficial de FastAPI (primeros pasos, en español) | https://fastapi.tiangolo.com/es/tutorial/first-steps/ |
| Documentación de uv | https://docs.astral.sh/uv/ |
| Clave de Google AI Studio | https://aistudio.google.com/apikey |
| Guía rápida de la API de Gemini (modelo actual) | https://ai.google.dev/gemini-api/docs/quickstart |
| Límites de la API de Gemini | https://ai.google.dev/gemini-api/docs/rate-limits |
| Claves de Groq (alternativa) | https://console.groq.com/keys |
| Tu API en local (con la API encendida) | http://127.0.0.1:8000/docs |
Errores frecuentes
| Síntoma | Qué pasa | Cómo se arregla |
|---|---|---|
ERROR: [Errno 48] Address already in use (macOS; Errno 98 en Linux; WinError 10048 en Windows) | Ya hay algo escuchando en el puerto 8000, casi siempre tu propia API arrancada en otra terminal. | Busca esa terminal y pulsa Ctrl+C. O arranca en otro puerto: uv run fastapi dev main.py --port 8001. Para ver quién lo ocupa: lsof -i :8000 (macOS y Linux) o netstat -ano | findstr :8000 (Windows). |
ModuleNotFoundError: No module named 'fastapi' (o 'google') | Ejecutas fuera del entorno del proyecto, o estás en otra carpeta. | Entra en mi-api y arranca siempre con uv run fastapi dev main.py. uv run usa el .venv correcto. |
fastapi: command not found o El término 'fastapi' no se reconoce | El comando vive dentro de .venv, no en todo el sistema, o instalaste fastapi sin [standard]. | Pon uv run delante. Si sigue, uv add "fastapi[standard]" (con comillas: en macOS, zsh interpreta los corchetes). |
{"detail":"Google ha rechazado tu clave..."} (401) | Clave mal copiada, con espacios o comillas, revocada o de otro proveedor. | Revisa que la línea es GEMINI_API_KEY=AQ... sin espacios ni comillas. Si sigue, crea otra clave (pe02) y reinicia la API. |
{"detail":"Has superado el límite gratuito..."} (429) | Demasiadas preguntas seguidas, o has gastado el cupo del día del nivel gratuito. | Espera un minuto. Si sigue, es el cupo diario: prueba al día siguiente o usa Groq (pe04). Consulta tus límites en AI Studio. |
Falta GEMINI_API_KEY y la clave sí está | El .env está en otra carpeta, se llama .env.txt, o lo cambiaste sin reiniciar. | Comprueba que .env está junto a main.py. Ctrl+C y vuelve a arrancar. |
422 Unprocessable Entity con "msg":"Field required" y "loc":["body","pregunta"] | El JSON no tiene el campo pregunta (por ejemplo, enviaste texto) o está mal formado. | Envía exactamente {"pregunta": "..."}. En /docs el ejemplo ya viene bien formado. |
En PowerShell, curl -X POST ... da un error rojo sobre parámetros | curl es un alias de Invoke-WebRequest, que no entiende -X ni -d. | Usa curl.exe o Invoke-RestMethod, como en el paso 6. |
Quiz
Cinco preguntas para comprobar que lo has entendido. Necesitas un 70 % para aprobar.