La documentación de OpenAI es exhaustiva. También está dispersa en seis referencias de API distintas, tres guías de migración y un changelog que se actualiza mensualmente.
Los tutoriales de 2024 referencian modelos obsoletos y parámetros eliminados. Buscas “OpenAI streaming example” y encuentras cuatro implementaciones diferentes —de las cuales solo dos siguen funcionando.
Este tutorial cubre cada función importante de la API de OpenAI a julio de 2026, en el orden en que deberías aprenderlas, con código que funciona.
Sin parámetros obsoletos. Sin excusas de “revisa la documentación más reciente”. Cada ejemplo fue probado contra la API actual.
El panorama de la API de OpenAI en 2026
OpenAI mantiene actualmente tres APIs activas, y saber cuál usar evita mucha confusión.
Chat Completions API (/v1/chat/completions): el clásico. Sin estado, de request-response. Envías mensajes, recibes una completion. Soporta streaming, function calling, JSON mode y structured outputs. Esto es lo que usan el 90% de las aplicaciones. Si no estás seguro de cuál usar, usa esta.
Responses API (/v1/responses): más nueva, con estado. Mantiene el estado de la conversación del lado del servidor en lugar de exigirte gestionar arreglos de mensajes. Soporta web search, file search y computer use como herramientas integradas. Mejor para flujos de agentes complejos donde el modelo debe orquestar varias herramientas a lo largo de múltiples turnos. El tradeoff: menos control sobre el historial de mensajes, y la API aún está evolucionando.
Agents SDK: la adición más reciente. Un framework para construir agentes de IA persistentes con guardrails integrados, traspaso entre agentes especializados y tracing. Más rígido que las APIs crudas —cambias flexibilidad por un desarrollo más rápido de patrones de agentes comunes. No se cubre en detalle aquí; la guía para construir agentes de IA lo trata a fondo.
Línea de modelos actual (julio de 2026):
| Modelo | Input $/M | Output $/M | Context | Mejor para |
|---|---|---|---|---|
| GPT-5.5 | $5.00 | $30.00 | 1M | Capacidad máxima, razonamiento complejo |
| GPT-5.4 | $2.50 | $15.00 | 1M | Gran capacidad, mejor valor |
| GPT-5.4 Mini | $0.75 | $4.50 | 400K | Tareas cotidianas, buen equilibrio costo/calidad |
| GPT-5.4 Nano | $0.20 | $1.25 | 128K | Tareas simples de alto volumen |
| o4-mini | $1.10 | $4.40 | 200K | Acertijos de matemáticas, lógica y código (especializado en razonamiento) |
Autenticación. Configura tu API key como variable de entorno OPENAI_API_KEY —nunca la hardcodees. Para gestión de keys en producción, rotación, alcance y arquitectura de claves virtuales, consulta nuestra guía de gestión de API keys.
Chat Completions API: la base
Toda integración con OpenAI empieza aquí.
Llamada de chat básica —Python:
from openai import OpenAI
client = OpenAI(
base_url="https://api.tokspan.com/v1",
api_key="ts-your-key-here"
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "You are a software engineer. Answer with code when appropriate."},
{"role": "user", "content": "Write a Python function to check if a string is a palindrome."}
],
temperature=0.3, # Low = deterministic, good for code
max_tokens=500, # Cap output length
top_p=0.95 # Nucleus sampling —usually leave at default
)
print(response.choices[0].message.content)Cada parámetro que importa:
model—qué modelo usar. En producción usa IDs con fecha (gpt-5.5-2025-06-15), no aliases (gpt-5.5). Los aliases se actualizan silenciosamente a snapshots nuevos que pueden cambiar el comportamiento de tu prompt.messages—arreglo de objetos de mensaje conrole(“system”, “user”, “assistant”) ycontent. El mensaje del sistema define el comportamiento. El mensaje del usuario es el request. Los mensajes de assistant son respuestas previas del modelo —inclúyelos para mantener el contexto de la conversación.temperature—de 0 a 2. Usa 0–0.3 para código y tareas factuales. 0.7–1.0 para chat y escritura creativa. 1.0+ para lluvia de ideas.max_tokens—límite duro de la longitud de salida. El modelo se detiene al alcanzar este límite, incluso a mitad de una oración. Configúralo generosamente (500–4,000) para la mayoría de las tareas.top_p—alternativa a temperature. Generalmente déjalo en el default (1.0) y controla la aleatoriedad solo con temperature.
Mensajes de sistema bien hechos. Un buen mensaje de sistema es específico, no filosófico. Malo: “Eres un asistente de IA útil.” Bueno: “Eres un revisor de código Python. Para cada fragmento de código, identifica: (1) bugs potenciales, (2) problemas de rendimiento, (3) violaciones de estilo. Formatea tu respuesta como una lista con viñetas. Mantén cada viñeta por debajo de 30 palabras.”
Conversaciones de múltiples turnos. La API no tiene estado. No recuerda tus llamadas anteriores.
Para tener una conversación, envías todo el historial de mensajes cada vez —mensaje de sistema + todos los mensajes previos de usuario y assistant + el nuevo mensaje del usuario. Cuando el historial se acerca al límite de contexto del modelo, recorta los mensajes más antiguos o resúmelos. Truncar es mejor que un error; resumir es mejor que truncar.
Streaming: respuestas en tiempo real
Modo sin streaming: el usuario espera 3–8 segundos y luego ve la respuesta completa de una vez. Modo streaming: el usuario ve aparecer las palabras en tiempo real desde ~0.4 segundos. La diferencia en la UI es la diferencia entre “esto se siente lento” y “esto se siente instantáneo”.
Implementación de streaming en Python:
stream = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Explain recursion."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)Implementación de streaming en Node.js:
const stream = await client.chat.completions.create({
model: "gpt-5.5",
messages: [{ role: "user", content: "Explain recursion." }],
stream: true
});
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}Casos límite a manejar: Chunks vacíos (los primeros chunks de un stream a menudo no tienen contenido —la API aún está procesando). Caídas de conexión (envuelve el stream en un try/except, reintenta con los mismos mensajes si falla a mitad de camino). Seguimiento del finish reason (el último chunk contiene finish_reason —revísalo para saber si el modelo se detuvo naturalmente o alcanzó un límite).
Function Calling: dale herramientas a tu LLM
El modelo no ejecuta código. Genera JSON que describe qué función llamar y con qué parámetros. Tu código ejecuta la función.
Envías el resultado de vuelta. El modelo usa el resultado para generar su respuesta final. Esta es la arquitectura detrás de cada agente de IA.
Ejemplo completo de un agente de clima:
import json
# Step 1: Define the tool
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city. Returns temperature in Celsius and conditions.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. 'Tokyo'"}
},
"required": ["city"]
}
}
}]
# Step 2: User asks a question that needs the tool
response = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
tools=tools,
tool_choice="auto" # Model decides whether to use a tool
)
# Step 3: Check if model wants to call a tool
msg = response.choices[0].message
if msg.tool_calls:
tool_call = msg.tool_calls[0]
args = json.loads(tool_call.function.arguments)
# Step 4: Execute the function (in reality, call a weather API)
weather_result = get_actual_weather(args["city"])
# Step 5: Send the result back
messages = [
{"role": "user", "content": "What's the weather in Tokyo?"},
msg, # The assistant's tool_call message
{"role": "tool", "tool_call_id": tool_call.id, "content": str(weather_result)}
]
final_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages
)
print(final_response.choices[0].message.content)Function calling en paralelo. Define varias herramientas. El modelo puede pedir varias a la vez si son independientes —“obtén el clima en Tokio Y Osaka.” Tu código debe manejar múltiples tool_calls en la respuesta, ejecutarlos en paralelo (asyncio.gather) y enviar todos los resultados juntos.
Mejores prácticas de function calling. Las descripciones de herramientas son prompts —escríbelas con claridad e incluye ejemplos de cuándo usar cada herramienta. Limita los parámetros con rigor —usa enums en lugar de cadenas de texto libre. La guía de function calling de OpenAI cubre casos límite como tool calls en streaming y ejecución paralela en detalle.
Haz que las herramientas sean idempotentes. Cuando falla la ejecución de una herramienta, envía el mensaje de error de vuelta al modelo —a menudo puede recuperarse probando parámetros diferentes.
Para una comparación entre proveedores de function calling en OpenAI, Anthropic, Google y DeepSeek —incluyendo qué funciones sobreviven la traducción a formato compatible con OpenAI— la comparación de tool calling tiene el desglose completo entre proveedores.
Structured Outputs: JSON garantizado
JSON mode (response_format={"type": "json_object"}) sugiere que quieres JSON. El modelo normalmente cumple. Structured Outputs (response_format={"type": "json_schema", ...}) lo garantiza —el muestreo de tokens del modelo se restringe para producir solo JSON válido que coincida con tu schema.
Cuándo usar cuál. JSON mode: prototipado rápido, herramientas internas, casos donde puedas manejar JSON malformado ocasional. Structured Outputs: APIs de producción, funciones orientadas al cliente, cualquier caso donde un JSON inválido cause una falla en cascada. La documentación de Structured Outputs de OpenAI cubre la sintaxis completa de definición de schemas y los modelos compatibles.
Definir un schema —ejemplo de parser de currículums:
response = client.chat.completions.create(
model="gpt-5.4", # Structured Outputs supported on GPT-5.4+
messages=[{"role": "user", "content": f"Extract information from this resume:\n\n{resume_text}"}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "resume_extraction",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"skills": {"type": "array", "items": {"type": "string"}},
"years_experience": {"type": "integer"},
"current_role": {"type": "string"}
},
"required": ["name", "skills", "years_experience"]
}
}
}
)
resume_data = json.loads(response.choices[0].message.content)
# Guaranteed to match your schema. No try/except json.loads needed.Checklist de despliegue en producción
Gestión del entorno. API keys en una bóveda de secretos (AWS Secrets Manager, HashiCorp Vault, Doppler), no en archivos .env. Rota las keys cada 90 días. Usa keys separadas para desarrollo, staging y producción con diferentes límites de presupuesto y allowlists de modelos.
Manejo de errores para producción. Envuelve cada llamada a la API en un reintento con backoff exponencial y jitter. Aplica circuit breakers a los proveedores que fallan de forma consistente —deja de enrutar hacia ellos durante 30 segundos, sondea y reanuda si está sano. Nunca devuelvas errores crudos de la API a los usuarios —mápealos a mensajes amigables y registra los detalles internamente.
Monitoreo de costos. Haz seguimiento del costo por usuario, por función, por modelo. Configura alertas de anomalías al doble del gasto diario normal.
La factura sorpresa de $500 ocurre cuando nadie estaba vigilando. Los resúmenes diarios de costos se escanean en 10 segundos.
Gestión de límites de rate. Conoce los límites de RPM y TPM de tu nivel. Lee los headers x-ratelimit-remaining-* en cada respuesta. Reduce la velocidad al 30% restante. Detente en el 10%.
Para la arquitectura completa de límites de rate —desde backoff reactivo hasta throttling predictivo— consulta nuestra guía de manejo de rate limits en producción.
El camino alternativo. Una plataforma de agregación maneja autenticación, recuperación de errores, registro de costos y gestión de rate limits a nivel de infraestructura. Tú te concentras en tu lógica de aplicación.
El tradeoff es un menor control sobre la ruta del request. Para la mayoría de los equipos, el tiempo ahorrado supera el control entregado.
FAQ
¿Cuál es la diferencia entre GPT-5.5 y o4-mini?
GPT-5.5 es un modelo de propósito general para chat, código, análisis y generación. o4-mini es un modelo especializado en razonamiento —piensa más tiempo antes de responder, lo que lo hace más fuerte en matemáticas, acertijos lógicos y razonamiento formal, pero más lento y más caro por token.
Usa GPT-5.5 para tareas cotidianas. Usa o4-mini para tareas donde normalmente buscarías una calculadora o una prueba formal.
¿Necesito usar Responses API en lugar de Chat Completions?
Aún no. Chat Completions es estable, ampliamente soportado y maneja el 90% de los casos de uso. Responses API agrega gestión de estado y herramientas integradas (web search, file search) pero es más nueva y está evolucionando.
Empieza con Chat Completions. Migra a Responses API cuando necesites sus funciones específicas.
¿Cómo reduzco mis costos de la API de OpenAI?
Usa GPT-5.4 Mini ($0.75/$4.50) en lugar de GPT-5.5 ($5/$30) para tareas simples. Habilita prompt caching —50% de descuento en la entrada cacheada. Usa la batch API para trabajo no urgente —50% de descuento con un tiempo de entrega de 24 horas.
O usa una plataforma de agregación donde el precio agrupado por volumen y el enrutamiento automático de modelos reduzcan costos sin cambiar de modelo manualmente. La guía de tácticas para recortar la factura recorre cada estrategia.
¿Puedo usar el SDK de OpenAI con modelos que no son de OpenAI?
Sí. La mayoría de los proveedores ofrecen endpoints compatibles con OpenAI.
Cambia base_url y api_key. Tu código permanece igual. Esta es la mayor ventaja del estándar compatible con OpenAI —no estás atado a un solo proveedor.
¿Qué pasa cuando OpenAI deprecia un modelo que estoy usando?
OpenAI normalmente avisa con 1–3 meses de anticipación. Fija tus versiones con IDs con fecha (gpt-5.5-2025-06-15), no aliases (gpt-5.5), para controlar cuándo migrar.
Prueba el modelo de reemplazo con tus prompts antes de la fecha de deprecación. Ten configurado un modelo de respaldo que no sea de OpenAI para que no te veas forzado a migrar en el calendario de OpenAI.
La API de OpenAI es el estándar de la industria por una razón: SDKs maduros, documentación exhaustiva y un ecosistema que la soporta primero. Pero 2026 es el primer año en que ese estándar muestra tensión —el protocolo nativo de Anthropic, el function calling automático de Google y la presión de precios de DeepSeek están atrayendo a los desarrolladores hacia funciones que no sobreviven la traducción a través de /v1/chat/completions. La pregunta que vale la pena seguir: ¿se convertirá el Agents SDK de OpenAI en el próximo estándar de la industria que vuelva a unificar el ecosistema, o acelerará la fragmentación al introducir capacidades disponibles solo en la propia infraestructura de OpenAI?
Empieza a programar —domina la API de OpenAI a tu manera. Luego agrega Claude, Gemini y DeepSeek a través del mismo SDK cuando estés listo —porque la única apuesta segura en 2026 es código que funcione en todos los proveedores.