OpenAI API: guía para integrar GPT, herramientas y agentes
OpenAI API permite integrar los modelos y herramientas de OpenAI dentro de sitios web, aplicaciones, software, agentes y automatizaciones. Puedes generar texto, analizar imágenes y archivos, utilizar modelos GPT, llamar funciones, buscar información, trabajar con documentos y crear workflows de varios pasos mediante código.
¿Qué es OpenAI API?
OpenAI API es la plataforma para desarrolladores que permite utilizar modelos de inteligencia artificial mediante solicitudes desde una aplicación. Su interfaz principal es Responses API, capaz de recibir texto, imágenes y archivos, generar texto o JSON y trabajar con herramientas como búsqueda web, File Search, funciones, MCP y Computer Use.
Qué puedes construir con OpenAI API
La API no está limitada a un chatbot de texto. Puede formar parte de sistemas mucho más amplios.
Asistentes
Chatbots, soporte, asistentes internos y experiencias conversacionales.
Automatización
Procesar información, decidir acciones y ejecutar workflows.
Análisis
Resumir, clasificar, extraer datos y analizar documentos.
Programación
Generar, revisar, explicar y transformar código.
Agentes
Combinar modelos, herramientas y acciones en procesos de varios pasos.
Multimodalidad
Trabajar con texto, imágenes, archivos y modelos especializados.
Responses API
Responses API permite crear respuestas de modelos y coordinar herramientas desde una sola interfaz.
POST /v1/responses
POST /v1/responses
Una solicitud puede incluir texto, imágenes o archivos y producir texto, JSON o llamadas a herramientas.
Responses API puede trabajar con herramientas integradas, funciones propias y servidores MCP, permitiendo construir aplicaciones mucho más agentic.
De una aplicación a un modelo de OpenAI
Tu aplicación envía una solicitud, el modelo procesa el contexto y puede devolver una respuesta o solicitar una herramienta antes de continuar.
Envías datos
Texto, imágenes, archivos, instrucciones y herramientas.
El modelo procesa
Razona sobre el contexto y determina qué hacer.
Recibes el resultado
Texto, JSON o llamadas a herramientas.
Cómo empezar con OpenAI API
El flujo básico consiste en crear un proyecto, generar una API key y realizar una solicitud desde tu backend.
Crea una cuenta: accede a la plataforma de OpenAI para desarrolladores.
Crea o selecciona un proyecto: los proyectos permiten organizar recursos, acceso, gasto y límites.
Genera una API key: crea una clave secreta dentro del proyecto.
Guarda la clave: utiliza una variable de entorno en tu servidor.
Selecciona un modelo: por ejemplo Sol, Terra o Luna.
Realiza la solicitud: utiliza Responses API desde tu backend.
API keys de OpenAI
Las claves API permiten autenticar solicitudes y están asociadas al proyecto correspondiente.
No expongas tu API key en el navegador
La clave debe permanecer en tu servidor o entorno seguro. No la incluyas directamente en HTML, JavaScript público, aplicaciones cliente ni repositorios abiertos.
Una práctica habitual
es guardar la clave
como una variable
denominada
OPENAI_API_KEY.
Claves completas, restringidas y de solo lectura
OpenAI permite controlar qué operaciones puede realizar una clave de proyecto.
| Permiso | Descripción |
|---|---|
| Todos | Acceso completo permitido por el proyecto |
| Restringido | Configura lectura, escritura o bloqueo por endpoint |
| Solo lectura | Permisos de lectura sobre endpoints compatibles |
Para aplicaciones de producción, utiliza únicamente los permisos que realmente necesita cada servicio.
Qué modelo utilizar en OpenAI API
No existe un único modelo adecuado para todos los workloads.
| Modelo | Orientación | Model ID |
|---|---|---|
| GPT-6 Astra | Trabajo end-to-end de máxima dificultad | gpt-6-astra |
| GPT-5.6 Sol | Trabajo profesional y coding complejo | gpt-5.6-sol |
| GPT-5.6 Terra | Equilibrio inteligencia / costo | gpt-5.6-terra |
| GPT-5.6 Luna | Alto volumen y bajo costo | gpt-5.6-luna |
Sol es un buen punto de partida para trabajo complejo. Terra reduce costos manteniendo buena capacidad, mientras Luna está diseñado para escala y economía.
Comparar modelos ChatGPT →Qué necesita una llamada a Responses API
Conceptualmente, una solicitud básica necesita un modelo y una entrada.
Modelo + input
{
"model": "gpt-5.6-sol",
"input": "Explica qué es una API REST."
}En producción debes añadir autenticación, manejo de errores, controles de uso y validación adecuada.
Texto o datos estructurados
Dependiendo del caso, una aplicación puede necesitar contenido para una persona o información para otro sistema.
Texto
Respuestas, explicaciones, resúmenes y contenido.
Structured Outputs
Datos estructurados que pueden ser procesados por una aplicación.
Herramientas de OpenAI API
Los modelos actuales pueden trabajar con herramientas durante una respuesta.
Web Search
Permite recuperar información actual desde la web.
File Search
Recupera información desde archivos incorporados al sistema.
Function calling
Permite que el modelo solicite funciones definidas por tu aplicación.
Computer Use
Permite construir workflows que interactúan con interfaces digitales.
MCP
Integra herramientas y sistemas externos mediante servidores compatibles.
Code Interpreter
Algunos modelos pueden utilizar ejecución de código como herramienta.
Function calling conecta el modelo con tu software
El modelo no tiene por qué limitarse a responder con texto.
Defines las funciones disponibles para el modelo.
El modelo decide cuándo necesita utilizar una función.
Tu aplicación ejecuta la acción real.
Devuelves el resultado para que el modelo continúe.
Consultar inventario, crear una cotización, recuperar información de una base de datos o llamar una API externa.
Proyectos en OpenAI API
Los proyectos ayudan a separar aplicaciones, usuarios, claves, recursos y consumo.
API keys: las claves pueden estar limitadas al proyecto.
Usuarios: puedes controlar quién participa en cada proyecto.
Modelos: puedes configurar qué modelos puede utilizar.
Rate limits: pueden administrarse a nivel de proyecto.
Gasto: puedes supervisar el consumo de cada proyecto.
Cuentas de servicio
En organizaciones, OpenAI permite crear service accounts para aplicaciones y servicios.
Identidad para sistemas
Permite separar el acceso de una aplicación del acceso personal de un usuario humano.
Rate limits de OpenAI API
Las solicitudes están sujetas a límites que dependen del modelo, organización, proyecto y usage tier.
| Concepto | Qué controla |
|---|---|
| RPM | Solicitudes por minuto |
| TPM | Tokens procesados por minuto |
| Batch queue | Capacidad en cola para Batch |
| Usage tier | Nivel de capacidad asignado |
Un error 429 puede indicar que alcanzaste un rate limit, un límite de gasto, un límite de uso o que agotaste saldo prepagado.
Ver límites de OpenAI API →Cómo se cobra OpenAI API
Muchos modelos utilizan tarifas basadas en tokens de entrada y salida.
| Modelo | Entrada / 1M | Salida / 1M |
|---|---|---|
| GPT-6 Astra | US$10 | US$50 |
| GPT-5.6 Sol | US$4 | US$20 |
| GPT-5.6 Terra | US$2 | US$12 |
| GPT-5.6 Luna | US$0,20 | US$1,20 |
No todos los costos se reducen únicamente a tokens. Determinadas herramientas o modelos especializados pueden utilizar otra tarifa.
ChatGPT y OpenAI API no son lo mismo
Utilizar una suscripción de ChatGPT no equivale a consumir la API dentro de una aplicación.
| Aspecto | ChatGPT | OpenAI API |
|---|---|---|
| Tipo | Producto para usuarios | Plataforma para desarrolladores |
| Interfaz | Chat y herramientas | Solicitudes desde código |
| Facturación | Plan de ChatGPT | Uso de API |
| Integración | Producto terminado | Tu propia aplicación |
| Control técnico | Menor | Mayor |
Responses API y Chat Completions
OpenAI mantiene diferentes interfaces para trabajar con modelos.
| Interfaz | Orientación |
|---|---|
| Responses API | Modelos actuales, herramientas y workflows agentic |
| Chat Completions | Interfaz de mensajes compatible con numerosos modelos |
| Realtime API | Experiencias de baja latencia y voz en tiempo real |
| Batch API | Procesamiento asincrónico de grandes cargas |
Responses API puede ejecutar trabajos en background
Para determinadas tareas, una respuesta no necesita mantenerse bloqueando una conexión hasta terminar.
Procesamiento asincrónico
Responses API incluye una opción para ejecutar determinados trabajos en segundo plano y recuperar posteriormente su estado o resultado.
Conversaciones y contexto entre respuestas
Responses API permite asociar una respuesta a una conversación para mantener elementos del contexto.
Continuidad entre turnos
Los elementos de entrada y salida pueden formar parte de una conversación, facilitando experiencias de varios turnos.
Seguridad al utilizar OpenAI API
Una integración en producción debe proteger claves, permisos y gasto.
Nunca expongas una API key en frontend público.
Utiliza permisos restringidos cuando sea posible.
Separa aplicaciones mediante proyectos.
Monitoriza consumo, errores y gasto.
Valida los argumentos antes de ejecutar acciones sensibles.
Implementa controles adicionales cuando una herramienta produce efectos externos.
Controlar el gasto por proyecto
La plataforma permite configurar límites y alertas asociados a proyectos.
Monitorea antes de escalar
Configura alertas, revisa el Usage Dashboard y controla el consumo antes de aumentar el tráfico de producción.
Dependiendo del control configurado, un presupuesto puede funcionar como alerta o como límite aplicado. Comprueba la configuración actual de tu organización o proyecto.
Problemas frecuentes con OpenAI API
Los errores más comunes suelen estar relacionados con autenticación, parámetros, límites o facturación.
| Código | Significado general |
|---|---|
| 400 | Solicitud inválida o parámetros incorrectos |
| 401 | Problema de autenticación |
| 403 | Acceso o permisos insuficientes |
| 429 | Rate limit, cuota, gasto o saldo |
| 5xx | Error temporal del servicio |
Un error temporal puede beneficiarse de exponential backoff, pero un problema de saldo o límite de gasto requiere solucionar primero esa condición.
Documentación oficial de OpenAI API
OpenAI actualiza modelos, endpoints, herramientas y precios, por lo que conviene utilizar la documentación como referencia final.
API Documentation
Consulta guías, referencia de API, modelos y herramientas disponibles actualmente.
Consultar documentación oficial →Guías relacionadas con OpenAI API
Continúa con modelos, costos y límites de la plataforma.
FAQ sobre OpenAI API
Respuestas rápidas sobre claves, modelos, costos, Responses API y límites.
Es la plataforma para integrar modelos y herramientas de OpenAI dentro de aplicaciones mediante código.
Es una interfaz de OpenAI para generar respuestas con modelos y utilizar texto, imágenes, archivos, funciones y herramientas.
Sí. Las solicitudes deben autenticarse mediante credenciales asociadas al proyecto.
No deberías exponer una API key secreta en código frontend visible para los usuarios.
GPT-6 Astra está orientado a máxima capacidad, GPT-5.6 Sol a trabajo complejo, Terra a equilibrio y Luna a alto volumen y bajo costo.
ChatGPT y la plataforma API son productos diferentes. El consumo de API utiliza su propia facturación.
Puede indicar que alcanzaste un rate limit, un límite de gasto o uso, o que existe un problema con el saldo disponible.
Sí. Responses API puede utilizar funciones propias, web search, file search, Computer Use, MCP y otras herramientas compatibles.
Muchos modelos se cobran según tokens de entrada y salida, aunque herramientas y modelos especializados pueden utilizar tarifas propias.
No. Los rate limits varían según el modelo, usage tier, organización y proyecto.
Continúa con los límites de OpenAI API
Ya conoces cómo funciona la plataforma. El siguiente paso es entender RPM, TPM, usage tiers, errores 429 y cómo escalar una aplicación.
Ver límites de OpenAI API →