La API de OpenAI te da acceso directo a modelos como GPT-4o, GPT-4o mini y o3 desde tu propio código. Esto significa que puedes integrar inteligencia artificial en cualquier aplicación Python: automatizar la generación de texto, crear asistentes conversacionales, analizar documentos, generar código, clasificar contenido o construir cualquier herramienta que aproveche el lenguaje natural.
En esta guía aprenderás a configurar el entorno, hacer tus primeras llamadas a la API, construir un chatbot con historial de conversación, trabajar con streaming, analizar imágenes y gestionar los costes de forma responsable.
Paso 1: Obtener tu API key
Para usar la API de OpenAI necesitas una cuenta en platform.openai.com. Una vez dentro, ve a API Keys en el menú lateral y crea una nueva clave. Cópiala en ese momento porque no podrás verla de nuevo.
La API tiene coste por uso según el número de tokens procesados. OpenAI ofrece créditos gratuitos al registrarse, suficientes para aprender y experimentar. Puedes configurar un límite de gasto mensual en la sección de facturación para evitar sorpresas.
Nunca incluyas tu API key directamente en el código, especialmente si vas a subir el proyecto a GitHub. Usa variables de entorno:
# Linux / macOS: añade esta línea a tu ~/.bashrc o ~/.zshrc
export OPENAI_API_KEY="sk-proj-..."
# Windows (PowerShell)
$env:OPENAI_API_KEY = "sk-proj-..."
# O crea un archivo .env en la raíz del proyecto (y añádelo al .gitignore)
OPENAI_API_KEY=sk-proj-...Paso 2: Instalar la librería oficial
OpenAI mantiene una librería oficial para Python que simplifica todas las llamadas a la API. Instálala con pip:
pip install openaiSi usas un archivo .env para gestionar las variables de entorno, instala también python-dotenv:
pip install openai python-dotenvVerifica la instalación:
python -c "import openai; print(openai.__version__)"
# 1.x.xPaso 3: Tu primera llamada a la API
El punto de entrada principal es el endpoint chat.completions.create(). Envías una lista de mensajes y el modelo devuelve una respuesta.
# primera_llamada.py
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv() # carga las variables del archivo .env
cliente = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini", # modelo rápido y económico, ideal para empezar
messages=[
{
"role": "system",
"content": "Eres un asistente experto en programación Python. Responde siempre en español."
},
{
"role": "user",
"content": "¿Cuál es la diferencia entre una lista y una tupla en Python?"
}
],
max_tokens=500,
temperature=0.7
)
# Acceder al texto de la respuesta
texto = respuesta.choices[0].message.content
print(texto)
# Ver el uso de tokens de la llamada
print(f"\nTokens usados: {respuesta.usage.total_tokens}")
print(f" - Prompt: {respuesta.usage.prompt_tokens}")
print(f" - Respuesta: {respuesta.usage.completion_tokens}")
Los parámetros más importantes:
model: el modelo a usar.gpt-4o-minies el más económico y rápido para tareas generales.gpt-4oes más capaz pero más caro.o3-minidestaca en razonamiento lógico y código.messages: lista de mensajes que forman la conversación. Cada mensaje tiene unrole(system,useroassistant) y uncontent.max_tokens: límite de tokens en la respuesta. Un token equivale aproximadamente a 0,75 palabras en español.temperature: controla la creatividad de la respuesta.0produce respuestas más deterministas y predecibles.1produce respuestas más variadas y creativas. Para tareas técnicas o de extracción de datos usa valores bajos (0.1–0.3). Para escritura creativa usa valores altos (0.7–1.0).
Paso 4: Los roles de los mensajes
La API de OpenAI funciona con un modelo de conversación donde cada mensaje tiene un rol que define quién lo emite y con qué propósito.
# roles_mensajes.py
# SYSTEM: define el comportamiento, personalidad y restricciones del modelo
# Se pone al inicio y persiste durante toda la conversación
sistema = {
"role": "system",
"content": """Eres un asistente de soporte técnico para una tienda de software.
Tu nombre es Sofía.
Responde siempre en un tono amable y profesional.
Si no sabes la respuesta, dilo con honestidad.
No inventes información sobre productos."""
}
# USER: mensajes del usuario
usuario = {
"role": "user",
"content": "Hola, ¿cómo puedo recuperar mi licencia?"
}
# ASSISTANT: respuestas previas del modelo (para construir historial)
asistente = {
"role": "assistant",
"content": "Hola, soy Sofía. Para recuperar tu licencia necesito tu email de compra."
}
# La conversación completa
mensajes = [sistema, usuario, asistente, {
"role": "user",
"content": "Mi email es usuario@mail.com"
}]
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=mensajes
)
print(respuesta.choices[0].message.content)
Paso 5: Construir un chatbot con historial
La API de OpenAI no guarda el historial de conversación entre llamadas: cada llamada es independiente. Para que el modelo "recuerde" los mensajes anteriores tienes que enviar toda la conversación en cada petición. Esta es la arquitectura estándar de cualquier chatbot.
# chatbot.py
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
cliente = OpenAI()
def chatbot():
print("Chatbot iniciado. Escribe 'salir' para terminar.\n")
historial = [
{
"role": "system",
"content": "Eres un asistente de programación útil y conciso. Responde en español."
}
]
while True:
entrada = input("Tú: ").strip()
if not entrada:
continue
if entrada.lower() in ("salir", "exit", "quit"):
print("¡Hasta luego!")
break
# Añadir el mensaje del usuario al historial
historial.append({"role": "user", "content": entrada})
try:
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=historial,
max_tokens=800,
temperature=0.7
)
texto = respuesta.choices[0].message.content
# Añadir la respuesta al historial para la siguiente vuelta
historial.append({"role": "assistant", "content": texto})
print(f"\nAsistente: {texto}\n")
except Exception as e:
print(f"Error: {e}")
break
if __name__ == "__main__":
chatbot()
Gestionar el tamaño del historial
Cada modelo tiene un límite de tokens en el contexto. Si la conversación es muy larga, el historial puede superar ese límite y la llamada fallará o costará mucho. Hay que implementar una estrategia de truncado:
# Estrategia simple: mantener solo los últimos N mensajes de usuario/asistente
def truncar_historial(historial, max_mensajes=20):
"""
Mantiene siempre el mensaje de sistema y los últimos max_mensajes
mensajes de conversación.
"""
sistema = [m for m in historial if m["role"] == "system"]
conversacion = [m for m in historial if m["role"] != "system"]
if len(conversacion) > max_mensajes:
conversacion = conversacion[-max_mensajes:]
return sistema + conversacion
# Estrategia por tokens: más precisa
def contar_tokens_aproximados(mensajes):
"""Estimación rápida: ~4 caracteres por token"""
total_chars = sum(len(m["content"]) for m in mensajes)
return total_chars // 4
def truncar_por_tokens(historial, limite_tokens=3000):
sistema = [m for m in historial if m["role"] == "system"]
conversacion = [m for m in historial if m["role"] != "system"]
while contar_tokens_aproximados(sistema + conversacion) > limite_tokens:
if len(conversacion) <= 2: # mantener al menos 1 intercambio
break
conversacion.pop(0) # eliminar el mensaje más antiguo
return sistema + conversacion
Paso 6: Streaming para respuestas en tiempo real
Por defecto, la API espera a generar toda la respuesta antes de devolverla. Con streaming, los tokens llegan uno a uno mientras el modelo los genera, igual que en ChatGPT. Esto mejora mucho la experiencia de usuario en interfaces interactivas.
# streaming.py
import os
from openai import OpenAI
cliente = OpenAI()
def preguntar_con_streaming(pregunta):
print("Asistente: ", end="", flush=True)
stream = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Responde en español de forma clara y detallada."},
{"role": "user", "content": pregunta}
],
stream=True # activar streaming
)
respuesta_completa = ""
for chunk in stream:
# Cada chunk contiene un fragmento del texto generado
if chunk.choices[0].delta.content is not None:
fragmento = chunk.choices[0].delta.content
print(fragmento, end="", flush=True)
respuesta_completa += fragmento
print() # salto de línea al terminar
return respuesta_completa
respuesta = preguntar_con_streaming("Explícame qué es la recursión en programación")
En aplicaciones web (Flask, FastAPI), el streaming se implementa con respuestas de tipo Server-Sent Events:
# streaming_fastapi.py
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import OpenAI
app = FastAPI()
cliente = OpenAI()
@app.post("/chat/stream")
async def chat_stream(pregunta: str):
def generar():
stream = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": pregunta}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield chunk.choices[0].delta.content
return StreamingResponse(generar(), media_type="text/plain")
Paso 7: Analizar imágenes con GPT-4o
Los modelos multimodales como GPT-4o pueden analizar imágenes junto con texto. Esto abre posibilidades como describir fotos, leer texto en imágenes, analizar gráficos o revisar capturas de pantalla de código.
# vision.py
import os
import base64
from openai import OpenAI
cliente = OpenAI()
# Opción 1: imagen desde URL pública
def analizar_imagen_url(url_imagen, pregunta):
respuesta = cliente.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {"url": url_imagen}
},
{
"type": "text",
"text": pregunta
}
]
}
],
max_tokens=500
)
return respuesta.choices[0].message.content
# Opción 2: imagen local codificada en base64
def analizar_imagen_local(ruta_imagen, pregunta):
with open(ruta_imagen, "rb") as archivo:
imagen_base64 = base64.b64encode(archivo.read()).decode("utf-8")
extension = ruta_imagen.split(".")[-1].lower()
tipo_mime = f"image/{extension}" # image/jpeg, image/png, image/webp
respuesta = cliente.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": f"data:{tipo_mime};base64,{imagen_base64}"
}
},
{
"type": "text",
"text": pregunta
}
]
}
],
max_tokens=500
)
return respuesta.choices[0].message.content
# Uso
descripcion = analizar_imagen_url(
"https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/Python-logo-notext.svg/115px-Python-logo-notext.svg.png",
"¿Qué muestra esta imagen? Descríbela en español."
)
print(descripcion)
Paso 8: Salidas estructuradas con JSON
Cuando necesitas que la respuesta del modelo tenga un formato fijo (para procesar los datos en tu aplicación), puedes forzar una salida JSON. Desde la versión 1.40 de la librería, el modo json_object garantiza que la respuesta es siempre JSON válido.
# json_output.py
import json
from openai import OpenAI
cliente = OpenAI()
def extraer_datos_producto(descripcion_texto):
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
response_format={"type": "json_object"},
messages=[
{
"role": "system",
"content": """Eres un extractor de datos de productos.
Extrae la información del texto y devuelve SOLO un JSON con esta estructura:
{
"nombre": "string",
"precio": number,
"moneda": "string",
"disponible": boolean,
"caracteristicas": ["string"]
}
Si un campo no se menciona, usa null."""
},
{
"role": "user",
"content": descripcion_texto
}
]
)
texto_json = respuesta.choices[0].message.content
return json.loads(texto_json)
# Uso
descripcion = """
El teclado mecánico TechType Pro está disponible por 89,99 euros.
Tiene switches Cherry MX Red, retroiluminación RGB, diseño compacto TKL
y compatibilidad con Windows y macOS. Actualmente en stock.
"""
datos = extraer_datos_producto(descripcion)
print(json.dumps(datos, ensure_ascii=False, indent=2))
# Resultado:
# {
# "nombre": "TechType Pro",
# "precio": 89.99,
# "moneda": "EUR",
# "disponible": true,
# "caracteristicas": [
# "Switches Cherry MX Red",
# "Retroiluminación RGB",
# "Diseño compacto TKL",
# "Compatible con Windows y macOS"
# ]
# }
Para estructuras más complejas con validación de tipos, usa la librería pydantic junto con el método parse() del cliente:
from pydantic import BaseModel
from typing import Optional, List
from openai import OpenAI
cliente = OpenAI()
class Producto(BaseModel):
nombre: str
precio: float
moneda: str
disponible: bool
caracteristicas: List[str]
valoracion: Optional[float] = None
completion = cliente.beta.chat.completions.parse(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Extrae los datos del producto como JSON estructurado."},
{"role": "user", "content": descripcion}
],
response_format=Producto
)
producto = completion.choices[0].message.parsed
print(f"Nombre: {producto.nombre}")
print(f"Precio: {producto.precio} {producto.moneda}")
print(f"Disponible: {producto.disponible}")
Paso 9: Embeddings para búsqueda semántica
Los embeddings son representaciones numéricas (vectores) del significado de un texto. Dos textos con significados similares tendrán vectores cercanos entre sí, independientemente de si comparten palabras exactas. Son la base de la búsqueda semántica, los sistemas de recomendación y los chatbots con documentos.
# embeddings.py
import numpy as np
from openai import OpenAI
cliente = OpenAI()
def obtener_embedding(texto):
respuesta = cliente.embeddings.create(
model="text-embedding-3-small", # pequeño y muy eficiente
input=texto
)
return respuesta.data[0].embedding # lista de 1536 números
def similitud_coseno(vec_a, vec_b):
a = np.array(vec_a)
b = np.array(vec_b)
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
# Base de conocimiento: preguntas frecuentes
faq = [
"¿Cómo puedo cancelar mi suscripción?",
"¿Cuáles son los métodos de pago aceptados?",
"¿Ofrecéis soporte técnico por teléfono?",
"¿Cuánto tarda el envío a España?",
"¿Puedo devolver un producto comprado online?"
]
# Calcular embeddings de la FAQ (en producción los guardarías en una BD vectorial)
print("Calculando embeddings de la FAQ...")
embeddings_faq = [(pregunta, obtener_embedding(pregunta)) for pregunta in faq]
# Búsqueda semántica: encontrar la pregunta más similar
def buscar_pregunta_similar(consulta_usuario):
embedding_consulta = obtener_embedding(consulta_usuario)
resultados = []
for pregunta, embedding in embeddings_faq:
similitud = similitud_coseno(embedding_consulta, embedding)
resultados.append((pregunta, similitud))
resultados.sort(key=lambda x: x[1], reverse=True)
return resultados[0] # la más similar
consulta = "Me gustaría darme de baja del servicio"
mejor_match, puntuacion = buscar_pregunta_similar(consulta)
print(f"\nConsulta: '{consulta}'")
print(f"Mejor match: '{mejor_match}'")
print(f"Similitud: {puntuacion:.3f}")
# Similitud: 0.912 → muy alta, correctamente identificada
Paso 10: Manejo de errores y reintentos
Las llamadas a APIs externas pueden fallar por múltiples razones: límite de tasa alcanzado, error temporal del servidor, timeout de red o créditos agotados. Es fundamental manejar estos casos correctamente en producción.
# manejo_errores.py
import time
import os
from openai import OpenAI, RateLimitError, APITimeoutError, APIConnectionError, AuthenticationError
cliente = OpenAI()
def llamar_con_reintentos(mensajes, max_reintentos=3, espera_inicial=1):
"""
Llama a la API con reintentos exponenciales para errores transitorios.
"""
for intento in range(max_reintentos):
try:
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=mensajes,
timeout=30 # timeout de 30 segundos
)
return respuesta.choices[0].message.content
except RateLimitError:
# Límite de peticiones por minuto alcanzado: esperar y reintentar
if intento < max_reintentos - 1:
espera = espera_inicial * (2 ** intento) # backoff exponencial
print(f"Límite de tasa alcanzado. Esperando {espera}s...")
time.sleep(espera)
else:
raise
except APITimeoutError:
# Timeout: reintentar inmediatamente
print(f"Timeout en intento {intento + 1}. Reintentando...")
if intento == max_reintentos - 1:
raise
except APIConnectionError as e:
# Error de conexión: reintentar con espera
print(f"Error de conexión: {e}")
if intento < max_reintentos - 1:
time.sleep(2)
else:
raise
except AuthenticationError:
# API key inválida: no tiene sentido reintentar
print("Error: API key inválida. Verifica OPENAI_API_KEY.")
raise
return None
# Uso
try:
respuesta = llamar_con_reintentos([
{"role": "user", "content": "¿Cuál es la capital de Francia?"}
])
print(respuesta)
except Exception as e:
print(f"Error definitivo tras reintentos: {e}")
Ejemplo completo: asistente con documentos (RAG básico)
El patrón RAG (Retrieval-Augmented Generation) consiste en buscar información relevante en tus propios documentos e incluirla en el prompt para que el modelo responda basándose en ella. Es la base de los chatbots que responden preguntas sobre documentación, manuales o bases de conocimiento internas.
# rag_basico.py
from openai import OpenAI
cliente = OpenAI()
# Base de conocimiento (en producción esto vendría de una BD vectorial)
documentos = {
"politica_devolucion": """
Política de devoluciones: Los clientes pueden devolver cualquier producto
en un plazo de 30 días desde la recepción. El producto debe estar en su
estado original con el embalaje intacto. Los gastos de envío de la
devolución corren a cargo del cliente, salvo en caso de producto defectuoso.
El reembolso se procesa en 5-7 días hábiles.
""",
"envios": """
Plazos de envío: Los pedidos realizados antes de las 14:00h se envían
el mismo día. El plazo de entrega es de 24-48h para península y 3-5 días
para Canarias, Baleares, Ceuta y Melilla. El envío gratuito aplica a
pedidos superiores a 49 euros.
""",
"garantia": """
Garantía: Todos nuestros productos tienen 2 años de garantía legal.
Para productos electrónicos ofrecemos adicionalmente 1 año de garantía
extendida gratuita. Las averías por mal uso no están cubiertas.
El servicio técnico está disponible de lunes a viernes de 9:00 a 18:00.
"""
}
def encontrar_contexto_relevante(pregunta):
"""Búsqueda simple por palabras clave (en producción usa embeddings)"""
pregunta_lower = pregunta.lower()
contextos = []
if any(p in pregunta_lower for p in ["devolu", "devolv", "reembols", "retorn"]):
contextos.append(documentos["politica_devolucion"])
if any(p in pregunta_lower for p in ["envio", "envío", "entrega", "plazo", "recib"]):
contextos.append(documentos["envios"])
if any(p in pregunta_lower for p in ["garantia", "garantía", "avería", "roto", "defect"]):
contextos.append(documentos["garantia"])
return "\n\n".join(contextos) if contextos else ""
def asistente_rag(pregunta):
contexto = encontrar_contexto_relevante(pregunta)
if contexto:
system_prompt = f"""Eres un asistente de atención al cliente.
Responde la pregunta del usuario basándote ÚNICAMENTE en la siguiente información:
{contexto}
Si la información no está en el contexto, dilo claramente.
No inventes datos. Sé conciso y amable."""
else:
system_prompt = """Eres un asistente de atención al cliente.
No tienes información específica sobre esta consulta.
Indica al usuario que contacte con soporte para más detalles."""
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": pregunta}
],
temperature=0.3 # baja temperatura para respuestas más fieles al contexto
)
return respuesta.choices[0].message.content
# Pruebas
preguntas = [
"¿Cuánto tiempo tengo para devolver un producto?",
"¿Cuándo llega mi pedido si lo hago ahora?",
"Mi televisor se estropeó, ¿está cubierto por la garantía?",
"¿Aceptáis criptomonedas como pago?"
]
for pregunta in preguntas:
print(f"\nPregunta: {pregunta}")
print(f"Respuesta: {asistente_rag(pregunta)}")
print("-" * 60)
Buenas prácticas y gestión de costes
Elige el modelo adecuado para cada tarea. gpt-4o-mini cuesta mucho menos que gpt-4o y para la mayoría de tareas de texto su calidad es más que suficiente. Usa los modelos más potentes solo cuando la tarea realmente lo requiere.
Controla el número de tokens. El coste depende del número de tokens enviados y recibidos. Mantén los prompts concisos, usa max_tokens para limitar la respuesta y trunca el historial de conversación como se mostró antes.
# Calcular el coste aproximado de una llamada
def estimar_coste(uso, modelo="gpt-4o-mini"):
# Precios en dólares por millón de tokens (consulta los actuales en platform.openai.com)
precios = {
"gpt-4o-mini": {"entrada": 0.15, "salida": 0.60},
"gpt-4o": {"entrada": 5.00, "salida": 15.00},
}
if modelo not in precios:
return None
precio = precios[modelo]
coste = (uso.prompt_tokens / 1_000_000 * precio["entrada"] +
uso.completion_tokens / 1_000_000 * precio["salida"])
return round(coste, 6)
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hola, ¿cómo estás?"}]
)
coste = estimar_coste(respuesta.usage)
print(f"Coste de esta llamada: ${coste}")
Implementa caché para respuestas repetidas. Si tu aplicación hace las mismas preguntas frecuentemente, guarda las respuestas en caché para no pagar por la misma llamada varias veces.
import hashlib
import json
cache = {}
def llamada_con_cache(mensajes, **kwargs):
# Generar una clave única para esta combinación de mensajes y parámetros
clave = hashlib.md5(json.dumps(mensajes + [kwargs], sort_keys=True).encode()).hexdigest()
if clave in cache:
print("[CACHE] Respuesta recuperada del caché")
return cache[clave]
respuesta = cliente.chat.completions.create(
model="gpt-4o-mini",
messages=mensajes,
**kwargs
)
texto = respuesta.choices[0].message.content
cache[clave] = texto
return texto
Configura alertas de gasto en el panel de facturación de OpenAI para recibir un email cuando el gasto mensual supere un umbral que definas. Establece también un límite de gasto mensual máximo para que la API se detenga automáticamente si lo superas.
Resumen
- Instala la librería oficial con
pip install openaiy guarda la API key en una variable de entorno, nunca en el código. - El endpoint principal es
chat.completions.create(). Los tres roles de los mensajes sonsystem(comportamiento del asistente),user(mensajes del usuario) yassistant(respuestas anteriores del modelo). - Para construir un chatbot con memoria, envía el historial completo en cada llamada y trunca los mensajes más antiguos cuando el contexto sea demasiado largo.
- Activa
stream=Truepara recibir los tokens en tiempo real y mejorar la experiencia de usuario en interfaces interactivas. - GPT-4o analiza imágenes: pasa la URL o el base64 de la imagen junto con tu pregunta en el contenido del mensaje.
- Usa
response_format={"type": "json_object"}o Pydantic para obtener respuestas estructuradas y predecibles. - Los embeddings (
text-embedding-3-small) son la base para búsqueda semántica y el patrón RAG. - Implementa reintentos con backoff exponencial para errores de tasa y maneja cada tipo de excepción de forma apropiada.
- Controla los costes eligiendo el modelo adecuado, limitando tokens e implementando caché para llamadas repetidas.
No hay comentarios todavía. Sé el primero en compartir tu opinión.