Módulo 2: OpenAI API - Introducción

Primer Request con OpenAI SDK Python

Inicia sesion para marcar tu progreso

Descripción de la cápsula

Es momento de escribir código. En esta cápsula harás tu primer request exitoso a GPT-3.5.

Verás:

Instalación de OpenAI SDK (v1.x)
Request más simple posible (5 líneas)
Respuesta de GPT-3.5
Anatomía de request/response

Al finalizar, entenderás el flujo básico: Mensaje → API → Respuesta

Tiempo: 20 minutos
Dificultad: Baja

🎯 Objetivos

✅ Instalar OpenAI SDK oficial
✅ Hacer primer request (GPT-3.5)
✅ Recibir y mostrar respuesta
✅ Entender formato JSON

📦 Paso 1: Instalar OpenAI SDK

1.1 Versión correcta (v1.x):

⚠️ Importante: OpenAI SDK tuvo breaking changes en 2023:

SDK v0.x (viejo): openai.Completion.create()
SDK v1.x (nuevo): client.chat.completions.create()

Este módulo usa v1.x (2024-2026 estándar).

1.2 Instalación:

pip install openai

Output esperado:

Collecting openai
  Downloading openai-1.12.0-py3-none-any.whl (...)
Installing collected packages: openai
Successfully installed openai-1.12.0

Versión instalada:

pip show openai

Debe ser v1.x:

Name: openai
Version: 1.12.0  # OK (v1.x)

Si ves v0.x: Update con pip install --upgrade openai

1.3 Dependencias adicionales:

pip install python-dotenv  # Para .env (si no instalaste en cápsula 02)

💻 Paso 2: Primer Request (Código Mínimo)

2.1 Estructura del proyecto:

tu-proyecto/
├── .env                 # API key (creado en cápsula 02)
├── .gitignore          # Previene leak
└── first_request.py    # Tu primer código (creamos ahora)

2.2 Código completo (`first_request.py`):

from dotenv import load_dotenv
import os
from openai import OpenAI

# 1. Cargar API key desde .env
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

# 2. Crear cliente OpenAI
client = OpenAI(api_key=api_key)

# 3. Hacer request a GPT-3.5
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "Hola, ¿cómo estás?"}
    ]
)

# 4. Mostrar respuesta
print(response.choices[0].message.content)

¡Solo 5 líneas de lógica! (sin imports y comments)

2.3 Ejecutar:

python first_request.py

Output esperado:

¡Hola! Estoy aquí para ayudarte. ¿En qué puedo asistirte hoy?

Si ves esto: ✅ ¡Felicitaciones! Acabas de hablar con GPT-3.5.

🔍 Paso 3: Anatomía del Request

3.1 Desglose línea por línea:

Línea 1-2: Imports

from dotenv import load_dotenv
import os
from openai import OpenAI

load_dotenv(): Lee archivo .env
os.getenv(): Accede a variables de entorno
OpenAI: Cliente oficial SDK v1.x

Línea 3-5: API Key

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

Carga .env → Busca OPENAI_API_KEY
Almacena en variable api_key

Debugging:

print(f"API Key: {api_key[:10]}...")  # Muestra primeros 10 chars
# Output: sk-proj-ab...

Línea 6-7: Cliente

client = OpenAI(api_key=api_key)

Crea instancia del cliente
Autentica con tu API key
Reutilizable (no crear en cada request)

Línea 8-13: Request

response = client.chat.completions.create(
    model="gpt-3.5-turbo",           # Modelo a usar
    messages=[                        # Array de mensajes
        {"role": "user", "content": "Hola, ¿cómo estás?"}
    ]
)

Parámetros obligatorios:

model: String (ej: "gpt-3.5-turbo", "gpt-4")
messages: Array de objetos con role y content

Parámetros opcionales (verás en cápsula 05):

temperature: 0.0-2.0 (creatividad)
max_tokens: Int (longitud máxima)
top_p, frequency_penalty, etc.

Línea 14-15: Response

print(response.choices[0].message.content)

response.choices: Array (GPT puede dar múltiples respuestas)
[0]: Primera respuesta (por defecto solo una)
.message.content: Texto generado

3.2 Response completo (JSON):

Si imprimes response completo:

print(response)

Output:

ChatCompletion(
  id='chatcmpl-abc123',
  object='chat.completion',
  created=1704123456,
  model='gpt-3.5-turbo-0125',
  choices=[
    Choice(
      index=0,
      message=ChatCompletionMessage(
        role='assistant',
        content='¡Hola! Estoy aquí para ayudarte. ¿En qué puedo asistirte hoy?'
      ),
      finish_reason='stop'
    )
  ],
  usage=CompletionUsage(
    prompt_tokens=15,
    completion_tokens=18,
    total_tokens=33
  )
)

Campos importantes:

id: Identificador único del request
model: Modelo usado (puede variar de lo solicitado)
choices[0].message.content: LA RESPUESTA
usage.total_tokens: Tokens gastados (para calcular costo)

🧪 Paso 4: Experimentos

Experimento 1: Cambiar el mensaje

Modifica línea del request:

messages=[
    {"role": "user", "content": "Explica qué es Python en 20 palabras"}
]

Ejecuta:

python first_request.py

Output esperado:

Python es un lenguaje de programación interpretado, de alto nivel, 
con sintaxis clara, utilizado en ciencia de datos, web y más.

Experimento 2: Usar GPT-4

⚠️ Costo: GPT-4 es 15-20x más caro que GPT-3.5

Cambia modelo:

response = client.chat.completions.create(
    model="gpt-4-turbo",  # Era: gpt-3.5-turbo
    messages=[...]
)

Observa:

Latency: ~3s (vs 1.5s GPT-3.5)
Respuesta: Ligeramente mejor calidad
Costo: 15x mayor

Para aprender: Usa GPT-3.5 (suficiente y económico)

Experimento 3: Token usage

Añade después del print:

print(f"\nTokens usados: {response.usage.total_tokens}")
print(f"  - Prompt: {response.usage.prompt_tokens}")
print(f"  - Completion: {response.usage.completion_tokens}")

Output:

Tokens usados: 33
  - Prompt: 15
  - Completion: 18

Cálculo de costo (GPT-3.5):

Input: 15 tokens × $0.50/1M = $0.0000075
Output: 18 tokens × $1.50/1M = $0.000027
Total: $0.0000345 (~$0.00003 por request)

Para 1000 requests: ~$0.03

🔧 Paso 5: Mejoras al Código

5.1 Error handling básico:

from dotenv import load_dotenv
import os
from openai import OpenAI

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    print("❌ ERROR: OPENAI_API_KEY no encontrada en .env")
    exit(1)

client = OpenAI(api_key=api_key)

try:
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": "Hola, ¿cómo estás?"}
        ]
    )
    print(response.choices[0].message.content)
    
except Exception as e:
    print(f"❌ ERROR: {e}")

Qué previene:

API key faltante
Network errors
Rate limiting
Crashes inesperados

5.2 Función reutilizable:

from dotenv import load_dotenv
import os
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def ask_gpt(prompt: str) -> str:
    """
    Envía prompt a GPT-3.5 y retorna respuesta.
    
    Args:
        prompt: Mensaje del usuario
        
    Returns:
        Respuesta generada por GPT-3.5
    """
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# Uso
respuesta = ask_gpt("¿Qué es Python?")
print(respuesta)

respuesta2 = ask_gpt("Dame un ejemplo de lista en Python")
print(respuesta2)

Ventaja: Reutilizas lógica sin copiar código.

🐛 Troubleshooting

Error: "ModuleNotFoundError: No module named 'openai'"

Causa: SDK no instalado

Solución:

pip install openai

Error: "AuthenticationError: Incorrect API key"

Causa: API key incorrecta o no cargada

Solución:

# Debug: Verifica que key se carga
api_key = os.getenv("OPENAI_API_KEY")
print(f"API Key: {api_key}")

# Si es None: .env no está en directorio correcto
# Si es incorrecta: Regenera en dashboard

Error: "RateLimitError: Rate limit reached"

Causa: Demasiados requests en poco tiempo

Solución:

import time
time.sleep(1)  # Espera 1s entre requests

Free tier limits:

GPT-3.5: 60 requests/min
GPT-4: 3 requests/min

Error: "Timeout"

Causa: Network lento o API slow

Solución:

client = OpenAI(
    api_key=api_key,
    timeout=30.0  # 30 segundos (default: 10min)
)

📊 Resumen

Lo que aprendiste:

Instalación de SDK:
- pip install openai (v1.x)
- Verificar versión correcta

Request básico (5 líneas):

client = OpenAI(api_key=api_key)
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "..."}]
)
print(response.choices[0].message.content)

Anatomía del response:
- choices[0].message.content: La respuesta
- usage.total_tokens: Tokens gastados
- model: Modelo usado
Debugging:
- Verificar API key carga correctamente
- Imprimir response completo para inspeccionar
- Manejar errores con try/except

Checklist:

Si todos ✅: Listo para conversaciones con contexto!

🔗 Recursos adicionales

OpenAI Python SDK Docs - GitHub oficial
Chat Completions API - Reference
Migration Guide v0→v1 - Si usaste SDK viejo

➡️ Próximo paso

Siguiente cápsula: 04-conversaciones-con-contexto.md

Hasta ahora, cada request es independiente (GPT no recuerda). En la próxima cápsula:

Implementarás historial conversacional
GPT recordará mensajes previos
Crearás chatbot real (múltiples intercambios)

Tiempo: 30 minutos
Código: ~30 líneas

Tiempo estimado: 20 minutos
Siguiente: 04-conversaciones-con-contexto.md

← AnteriorSetup de Cuenta OpenAI y API Keys Siguiente →Conversaciones con Contexto

Primer Request con OpenAI SDK Python

Descripción de la cápsula

🎯 Objetivos

📦 Paso 1: Instalar OpenAI SDK

1.1 Versión correcta (v1.x):

1.2 Instalación:

1.3 Dependencias adicionales:

💻 Paso 2: Primer Request (Código Mínimo)

2.1 Estructura del proyecto:

2.2 Código completo (first_request.py):

2.3 Ejecutar:

🔍 Paso 3: Anatomía del Request

3.1 Desglose línea por línea:

3.2 Response completo (JSON):

🧪 Paso 4: Experimentos

Experimento 1: Cambiar el mensaje

Experimento 2: Usar GPT-4

Experimento 3: Token usage

🔧 Paso 5: Mejoras al Código

5.1 Error handling básico:

5.2 Función reutilizable:

🐛 Troubleshooting

Error: "ModuleNotFoundError: No module named 'openai'"

Error: "AuthenticationError: Incorrect API key"

Error: "RateLimitError: Rate limit reached"

Error: "Timeout"

📊 Resumen

Lo que aprendiste:

Checklist:

🔗 Recursos adicionales

➡️ Próximo paso

2.2 Código completo (`first_request.py`):