Módulo 2: OpenAI API - Introducción

Setup de Cuenta OpenAI y API Keys

Siguiente →

Descripción de la cápsula

Antes de escribir código, necesitas:

  1. Cuenta OpenAI
  2. API key (token de autenticación)
  3. Método de pago configurado (o $5 credits gratis)

Esta cápsula te guía paso a paso en el setup completo. Al finalizar, tendrás tu API key lista para usar en Python.

Tiempo: 15 minutos
Costo: $0 (usa $5 credits gratis iniciales)

🎯 Objetivos

Al completar esta cápsula:

  • ✅ Tendrás cuenta OpenAI activa
  • ✅ Obtendrás tu primera API key
  • ✅ Configurarás environment variables (.env)
  • ✅ Verificarás que todo funciona

📝 Paso 1: Crear Cuenta OpenAI

1.1 Registro:

  1. Visita: https://platform.openai.com/signup
  2. Opciones de registro:
    • Email + password
    • Google account
    • Microsoft account

Recomendación: Usa Google/Microsoft (menos pasos)

1.2 Verificación de email:

Si registraste con email:

  1. Revisa inbox (check spam también)
  2. Click en link de verificación
  3. Confirma cuenta

1.3 Configuración de perfil:

OpenAI te pedirá:

  • Nombre completo
  • Organización (opcional, puedes poner "Personal")
  • País (para tax compliance)
  • Uso previsto (selecciona "Learning/Education")

Nota: Esta info es para compliance, no afecta funcionalidad.

💳 Paso 2: Configurar Billing

2.1 Free credits ($5):

Nuevos usuarios (2024-2026):

  • OpenAI da $5 credits gratis
  • Válidos por 3 meses
  • Suficiente para este módulo completo

Verifica tus credits:

  1. Ve a: https://platform.openai.com/account/billing/overview
  2. Busca "Free trial credits"
  3. Deberías ver: $5.00 disponibles

2.2 Si NO tienes free credits:

Usuarios existentes o credits expirados:

Necesitas agregar método de pago:

  1. Ve a: https://platform.openai.com/account/billing/payment-methods
  2. Click "Add payment method"
  3. Opciones:
    • Tarjeta de crédito/débito
    • PayPal (algunos países)

⚠️ Importante: Configura spending limit

  1. Ve a: https://platform.openai.com/account/billing/limits
  2. Set "Hard limit": $10/mes (recomendado para aprender)
  3. Set "Soft limit": $5/mes (alerta temprana)

Qué hace esto:

  • Hard limit: OpenAI para requests si llegas a $10
  • Soft limit: Te envía email de alerta a $5
  • Previene: Factura inesperada de $500 por bug

2.3 Verificar billing activo:

Dashboard → Billing → Overview

Deberías ver:

Current balance: $5.00 (free credits)
OR
Current balance: $0.00 (paid, con card configurada)

Si dice "Please add payment method": Completa paso 2.2

🔑 Paso 3: Crear API Key

3.1 Generar API key:

  1. Ve a: https://platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Dale un nombre descriptivo:
    • Ejemplo: "Module 2 - Learning"
    • Ejemplo: "Local Development"
  4. Click "Create secret key"

3.2 Copiar y guardar:

⚠️ CRÍTICO: Solo verás la key UNA VEZ

sk-proj-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Cópiala AHORA a un lugar seguro:

  • Archivo temporal local (no cloud)
  • Password manager (1Password, Bitwarden)
  • Nota en tu máquina

Si la pierdes: Debes regenerar (la anterior queda inválida)

3.3 Verificar formato:

API keys de OpenAI tienen este formato:

sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • Empieza con sk-proj- (project key, nuevo formato 2024)
  • O sk- (user key, formato viejo)
  • ~50-60 caracteres
  • Solo letras, números, guiones

Si tu key NO se ve así: Algo salió mal, regenera.

🔐 Paso 4: Configurar Environment Variables

4.1 ¿Por qué environment variables?

❌ MAL (hardcoded):

import openai
openai.api_key = "sk-proj-abc123..."  # NUNCA HAGAS ESTO

Problemas:

  • Si commiteas a Git → Leak público
  • Si compartes código → Expones tu key
  • Bots scraping GitHub roban keys en minutos

✅ BIEN (environment variable):

import os
openai.api_key = os.getenv("OPENAI_API_KEY")

Beneficios:

  • Key NO está en código
  • .gitignore previene commits
  • Diferentes keys por entorno (dev/prod)

4.2 Crear archivo .env:

En tu proyecto, crea archivo .env:

cd ~/tu-proyecto
touch .env

Contenido de .env:

OPENAI_API_KEY=sk-proj-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Reemplaza sk-proj-abc123... con TU key real.

4.3 Configurar .gitignore:

⚠️ CRÍTICO: Prevenir leak

Crea/edita .gitignore:

# En raíz del proyecto
nano .gitignore

Añade estas líneas:

# Environment variables
.env
.env.local
.env.*.local

# OpenAI specific
openai.key
api_key.txt
secrets/

Verifica que funciona:

git status
# .env NO debe aparecer en "Untracked files"

4.4 Instalar python-dotenv:

Para leer .env desde Python:

pip install python-dotenv

Uso en código:

from dotenv import load_dotenv
import os

# Carga variables de .env
load_dotenv()

# Accede a la key
api_key = os.getenv("OPENAI_API_KEY")
print(f"API Key cargada: {api_key[:10]}...")  # Muestra primeros 10 chars

Output esperado:

API Key cargada: sk-proj-ab...

✅ Paso 5: Verificación Completa

5.1 Test con curl:

Verifica que tu API key funciona SIN escribir Python:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Output esperado (primeras líneas):

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4-turbo",
      "object": "model",
      ...
    },
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      ...
    }
  ]
}

Si ves esto: ✅ API key funciona

Si ves error 401 Unauthorized:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error"
  }
}

❌ Key incorrecta, verifica:

  1. Copiaste completa (sin espacios)
  2. Está en .env correctamente
  3. Usaste export OPENAI_API_KEY=... en terminal

5.2 Test con Python (minimal):

Crea test_api_key.py:

from dotenv import load_dotenv
import os
import requests

# Carga .env
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

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

print(f"✅ API Key cargada: {api_key[:15]}...")

# Test API call (list models)
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get("https://api.openai.com/v1/models", headers=headers)

if response.status_code == 200:
    models = response.json()["data"]
    print(f"✅ API funciona! {len(models)} modelos disponibles")
    print(f"Ejemplos: {models[0]['id']}, {models[1]['id']}")
else:
    print(f"❌ ERROR: {response.status_code} - {response.text}")

Ejecuta:

python test_api_key.py

Output esperado:

✅ API Key cargada: sk-proj-abc123...
✅ API funciona! 50 modelos disponibles
Ejemplos: gpt-4-turbo, gpt-3.5-turbo

🔒 Mejores Prácticas de Seguridad

1. NUNCA commitees API keys:

Check antes de commit:

git diff | grep -i "sk-"
# Si aparece "sk-proj" o "sk-" → DETENTE

Si ya commitaste por error:

  1. Regenera key INMEDIATAMENTE en dashboard
  2. Revoke la key vieja
  3. Update .env con nueva key
  4. Git: git filter-branch o BFG Repo Cleaner (avanzado)

2. Usa keys específicas por proyecto:

En vez de 1 key para todo:

Project A: sk-proj-AAA...
Project B: sk-proj-BBB...
Learning:  sk-proj-LLL...

Beneficio: Si leak una, las demás están seguras.

3. Rotación regular:

Cada 3-6 meses:

  1. Genera nueva key
  2. Update .env en todos los proyectos
  3. Revoke key vieja

Automatizable con:

  • 1Password rotation
  • AWS Secrets Manager
  • HashiCorp Vault (enterprise)

4. Monitoring de uso:

Dashboard → Usage:

Alerta si:

  • Uso > $1/día (cuando esperas $0.10)
  • Spike inesperado (posible leak)

🐛 Troubleshooting

Error: "Invalid API key"

Síntomas:

401 Unauthorized: Invalid API key

Soluciones:

  1. Verifica formato (debe empezar con sk-proj- o sk-)
  2. Check espacios (copia sin espacios al inicio/final)
  3. Regenera key en dashboard
  4. Verifica que .env esté en directorio correcto

Error: "You exceeded your current quota"

Síntomas:

429 Too Many Requests: You exceeded your current quota

Causas:

  1. Gastaste los $5 free credits
  2. No tienes método de pago configurado
  3. Llegaste al hard limit

Solución:

  1. Dashboard → Billing → Add payment method
  2. O espera a que se resetee (si es rate limit temporal)

Error: ".env no se carga"

Síntomas:

api_key = None  # debería ser "sk-proj..."

Causas:

  1. .env NO está en root del proyecto
  2. No ejecutaste load_dotenv()
  3. Typo en variable (case-sensitive)

Solución:

# Verifica ubicación
pwd  # Debe ser root del proyecto
ls -la .env  # Debe existir

# Verifica contenido
cat .env
# Debe tener: OPENAI_API_KEY=sk-proj-...

📊 Resumen

Checklist de completado:

  • Cuenta OpenAI creada y verificada
  • $5 credits visibles O método de pago configurado
  • Spending limits configurados ($5 soft, $10 hard)
  • API key generada y guardada
  • Archivo .env creado con key
  • .gitignore configurado (previene leak)
  • python-dotenv instalado
  • Test con curl exitoso
  • Test con Python exitoso

Si todos están ✅: Listo para escribir código!

🔗 Recursos adicionales

  1. OpenAI Platform Quickstart - Setup oficial
  2. API Keys Best Practices - Security
  3. Billing FAQ - Preguntas comunes
  4. python-dotenv docs - Environment variables

➡️ Próximo paso

Siguiente cápsula: 03-primer-request-sdk-python.md

Ahora que tienes API key funcionando, harás tu primer request a GPT-3.5:

  • Instalarás OpenAI SDK
  • Enviarás mensaje simple
  • Recibirás respuesta
  • Entenderás formato request/response

Tiempo: 20 minutos
Código: ~10 líneas

Tiempo estimado: 15 minutos
Siguiente: 03-primer-request-sdk-python.md

← AnteriorMódulo 2: OpenAI API - IntroducciónSiguiente →Primer Request con OpenAI SDK Python