Leccion 9: API de OpenAI - Primeros pasos

Hasta ahora hemos usado ChatGPT a través de la interfaz web. La API de OpenAI lleva esas capacidades a un nivel completamente diferente: podés integrar GPT-4o, o1, y todos los modelos directamente en tus aplicaciones, flujos de trabajo, y automatizaciones, con control total sobre el comportamiento.

Esta lección está diseñada para ser accesible incluso si nunca usaste una API. Al final, vas a tener tu primera integración funcional corriendo.

Conceptos fundamentales que necesitás entender

¿Qué es una API?

Una API (Application Programming Interface) es como un mesero en un restaurante: vos pedís algo (hacés un request), el mesero lo lleva a la cocina (el servidor de OpenAI), y te trae el resultado (la response). No necesitás saber cómo funciona la cocina, solo cómo hacer el pedido.

Tokens: la unidad de medida

La API de OpenAI cobra por tokens, no por palabras ni por mensajes. Un token es aproximadamente:

• 4 caracteres en inglés
• 3-4 caracteres en español (ligeramente más tokens por la acentuación)
• "ChatGPT" = 2 tokens
• "Hola, ¿cómo estás?" ≈ 8 tokens
• 1,000 tokens ≈ 750 palabras en inglés / 600 en español

Precios actuales de los modelos principales (2026)

Nota de costos reales: Para referencia, $10 USD en la API de gpt-4o-mini permite procesar aproximadamente 66 millones de tokens de input, suficiente para analizar miles de documentos. Los costos son extremadamente bajos para la mayoría de aplicaciones.

Configurar tu cuenta en platform.openai.com

Paso 1: Crear cuenta de developer

1. Ve a platform.openai.com (diferente de chat.openai.com)
2. Crea una cuenta o inicia sesión con tu cuenta existente
3. Completa la verificación de identidad si se requiere
4. Carga crédito: el mínimo típico es $5-10 USD para empezar

Paso 2: Obtener tu API Key

1. En platform.openai.com, ve al menú izquierdo → API Keys
2. Clic en "Create new secret key"
3. Dale un nombre descriptivo (ej: "Mi proyecto de automatización")
4. CRÍTICO: Copia la key INMEDIATAMENTE. Solo se muestra una vez. Si la perdés, hay que crear una nueva.
5. Guárdala en un lugar seguro (un gestor de contraseñas como 1Password o Bitwarden)

Seguridad de tu API Key

Tu API Key es como la contraseña de tu tarjeta de crédito. Reglas obligatorias:

• NUNCA la incluyas en código que subas a GitHub
• NUNCA la compartas en chats, emails o screenshots
• Siempre cárgala desde variables de entorno, no hardcodeada
• Configura límites de gasto en platform.openai.com → Billing → Limits

Tu primera llamada a la API con Python

Instalar el SDK oficial

pip install openai

El "Hello World" de la API

import os
from openai import OpenAI
# Carga la API Key desde variable de entorno (NUNCA hardcodear)
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
# Tu primera llamada
response = client.chat.completions.create(
    model="gpt-4o-mini",  # Modelo más económico para pruebas
    messages=[
        {
            "role": "system",
            "content": "Eres un asistente útil que responde en español."
        },
        {
            "role": "user",
            "content": "¿Cuál es la capital de Argentina y por qué es famosa?"
        }
    ],
    max_tokens=500,
    temperature=0.7
)
# Extraer el texto de la respuesta
print(response.choices[0].message.content)
# Ver cuántos tokens usaste
print(f"\nTokens usados - Input: {response.usage.prompt_tokens}, Output: {response.usage.completion_tokens}")

Cómo configurar la variable de entorno

En macOS/Linux:

export OPENAI_API_KEY="sk-tu-key-aquí"

En Windows (PowerShell):

$env:OPENAI_API_KEY = "sk-tu-key-aquí"

En un archivo .env (recomendado para proyectos):

# Archivo .env en tu proyecto
OPENAI_API_KEY=sk-tu-key-aquí
# En Python, instalar python-dotenv
pip install python-dotenv
# Luego en tu código
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()  # Toma automáticamente la variable de entorno

Los parámetros más importantes de la API

model

Qué modelo usar. Para desarrollo/pruebas: "gpt-4o-mini". Para producción donde calidad importa: "gpt-4o".

messages (el array de mensajes)

Estructura de conversación con 3 roles:

temperature (0 a 2)

• 0: Determinístico, siempre la misma respuesta (ideal para extracción de datos, clasificación)
• 0.7: Balance entre creatividad y consistencia (uso general)
• 1.0: Más variado y creativo (escritura creativa, brainstorming)
• 2.0: Muy aleatorio, generalmente no recomendado

max_tokens

Límite máximo de tokens en la respuesta. Útil para controlar costos y asegurar respuestas de longitud apropiada. Si se omite, el modelo puede responder hasta su límite máximo.

response_format

Para obtener JSON estructurado en lugar de texto libre:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Responde siempre en formato JSON válido."},
        {"role": "user", "content": "Extrae nombre, email y empresa de: Juan García, [email protected], ACME Corp"}
    ]
)
# La respuesta será JSON: {"nombre": "Juan García", "email": "[email protected]", "empresa": "ACME Corp"}

Mantener contexto de conversación

La API es stateless (sin memoria). Para simular una conversación, hay que enviar el historial completo en cada request:

from openai import OpenAI
client = OpenAI()
conversation_history = [
    {"role": "system", "content": "Eres un asistente de soporte técnico para software de contabilidad."}
]
def chat(user_message):
    conversation_history.append({"role": "user", "content": user_message})
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=conversation_history,
        temperature=0.3
    )
    assistant_message = response.choices[0].message.content
    conversation_history.append({"role": "assistant", "content": assistant_message})
    return assistant_message
# Uso
print(chat("Mi balance no cuadra"))
print(chat("El error es de $500"))  # El modelo recuerda el contexto anterior

Manejo de errores: lo que todo desarrollador debe saber

import time
from openai import OpenAI, RateLimitError, APIError
client = OpenAI()
def call_api_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o-mini",
                messages=messages
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
            print(f"Rate limit alcanzado. Esperando {wait_time}s...")
            time.sleep(wait_time)
        except APIError as e:
            print(f"Error de API: {e}")
            if attempt == max_retries - 1:
                raise
    raise Exception("Máximo de reintentos alcanzado")

Casos de uso prácticos con código

Clasificador de emails para soporte

def classify_email(email_text):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        response_format={"type": "json_object"},
        temperature=0,  # Determinístico para clasificación
        messages=[
            {
                "role": "system",
                "content": """Clasifica el email en: 
                categoria: [soporte_tecnico, facturacion, consulta_ventas, queja, otro]
                urgencia: [alta, media, baja]
                resumen: máximo 20 palabras
                Responde solo JSON."""
            },
            {"role": "user", "content": f"Email: {email_text}"}
        ]
    )
    import json
    return json.loads(response.choices[0].message.content)
# Uso
result = classify_email("Hola, mi factura del mes pasado tiene un cobro extra que no reconozco")
print(result)
# Output: {"categoria": "facturacion", "urgencia": "alta", "resumen": "Cobro no reconocido en factura"}

Vamos a crear un script que resuma automáticamente correos o textos largos:

1. Instala Python (si no lo tenés) y el SDK: pip install openai python-dotenv
2. Crea un archivo .env con tu API Key
3. Crea un script summarizer.py:

from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()
def summarize(text,):
    styles = {
        "ejecutivo": "3 puntos clave en bullets, máximo 50 palabras total",
        "detallado": "resumen párrafo de 100-150 palabras",
        "simple": "explicación en lenguaje simple, sin jerga técnica, máximo 80 palabras"
    }
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Eres un experto en síntesis. Crea: {styles[style]}."},
            {"role": "user", "content": f"Resume esto:\n{text}"}
        ],
        temperature=0.3
    )
    return response.choices[0].message.content
# Prueba con un texto largo
texto = """[Pega aquí un email, artículo, o documento largo]"""
print(summarize(texto,))

4. Ejecuta el script y verifica que funcione. Experimenta con los 3 estilos de resumen.