Responses API de OpenAI: qué es y cómo funciona
Responses API es la interfaz de OpenAI
para crear respuestas con modelos GPT y construir aplicaciones
capaces de trabajar con texto, imágenes, archivos,
herramientas, funciones y conversaciones.
Utiliza el endpoint POST /v1/responses
y permite crear desde asistentes sencillos
hasta workflows agentic de varios pasos.
¿Qué es Responses API?
Responses API es una API de OpenAI para enviar entradas a un modelo y recibir una respuesta. A diferencia de una interfaz limitada únicamente a mensajes de chat, puede combinar modelos, texto, imágenes, archivos, herramientas integradas, funciones personalizadas y estado conversacional dentro de un mismo flujo.
Qué permite hacer Responses API
La interfaz está diseñada para algo más amplio que generar una respuesta de texto.
Texto
Generar respuestas, resúmenes, contenido, análisis y explicaciones.
Imágenes
Algunos modelos pueden recibir imágenes como parte del input.
Archivos
Las entradas pueden incorporar archivos y otros elementos de contexto.
Structured Outputs
Generar información estructurada para otros sistemas.
Herramientas
Web Search, File Search, funciones y MCP.
Estado
Crear conversaciones y continuar respuestas entre diferentes turnos.
POST /v1/responses
Una nueva respuesta
se crea enviando una solicitud
HTTP POST al recurso
/v1/responses.
Crear una respuesta
POST https://api.openai.com/v1/responsesLa solicitud debe realizarse desde un entorno seguro utilizando las credenciales correspondientes a tu proyecto de OpenAI API.
Ver guía de OpenAI API →Cómo funciona Responses API
La aplicación envía un input, el modelo procesa la solicitud y puede responder directamente o utilizar herramientas antes de finalizar.
Envías información
Texto, imágenes, archivos e instrucciones.
Modelo + herramientas
El modelo procesa el contexto y puede utilizar herramientas.
Obtienes la respuesta
Texto, JSON, tool calls u otros output items.
Parámetros básicos de Responses API
Una solicitud puede ser muy sencilla o incorporar múltiples configuraciones.
| Parámetro | Función |
|---|---|
model |
Selecciona el modelo que procesará la solicitud |
input |
Contenido que recibe el modelo |
instructions |
Instrucciones de nivel superior para esa respuesta |
tools |
Herramientas que puede utilizar el modelo |
tool_choice |
Controla cómo puede seleccionar herramientas |
max_output_tokens |
Limita tokens de salida y reasoning |
background |
Permite ejecutar determinadas respuestas en segundo plano |
conversation |
Asocia la respuesta a una conversación |
previous_response_id |
Continúa desde una respuesta anterior |
Ejemplo conceptual de una solicitud
Una llamada mínima puede contener solamente un modelo y una entrada.
Solicitud simple
{
"model": "gpt-5.6-sol",
"input": "Explica qué es una API REST."
}En una aplicación real debes incluir autenticación, manejo de errores, validaciones y controles de gasto y uso.
Qué modelo utilizar con Responses API
La interfaz puede trabajar con distintos modelos compatibles.
| Modelo | Uso recomendado |
|---|---|
| GPT-6 Astra | Workflows end-to-end especialmente difíciles |
| GPT-5.6 Sol | Programación, razonamiento y trabajo profesional complejo |
| GPT-5.6 Terra | Equilibrio entre capacidad y costo |
| GPT-5.6 Luna | Alto volumen, velocidad y bajo costo |
La elección debería depender de la dificultad, latencia, costo y volumen de la tarea.
Comparar modelos →Qué puede recibir Responses API
El campo input
puede representar más
que una cadena de texto.
Texto
Preguntas, instrucciones y contexto.
Imágenes
Modelos compatibles pueden interpretar contenido visual.
Archivos
Pueden incorporarse archivos como elementos de entrada.
Separar instrucciones del input
El parámetro
instructions
permite proporcionar
instrucciones de nivel superior.
Instrucción + solicitud
{
"model": "gpt-5.6-sol",
"instructions": "Responde de forma clara y breve.",
"input": "¿Qué es OAuth?"
}
OpenAI indica que las
instructions
de una respuesta anterior
no se trasladan automáticamente
cuando utilizas
previous_response_id.
Cómo devuelve resultados Responses API
La respuesta puede contener diferentes tipos de elementos, no únicamente un mensaje de texto.
output contiene los elementos generados
El array output
puede incluir mensajes,
reasoning items,
llamadas a herramientas
y otros tipos de output.
Los SDK pueden proporcionar
helpers como output_text
para extraer el texto
de una forma más sencilla,
porque el primer elemento
puede corresponder a otro
tipo de output.
Generar datos estructurados con Responses API
Una aplicación puede necesitar datos para procesar mediante código, no una respuesta destinada directamente a una persona.
Texto libre
Adecuado para respuestas humanas, explicaciones y contenido.
Datos estructurados
Útiles para APIs, automatización, bases de datos y otros sistemas.
Herramientas en Responses API
Una de las principales ventajas de Responses API es integrar herramientas dentro del mismo workflow.
Web Search
Permite al modelo recuperar información desde la web.
File Search
Busca información dentro de colecciones de archivos.
Function calling
Conecta el modelo con funciones de tu aplicación.
MCP
Integra sistemas y herramientas externas mediante MCP.
Function calling con Responses API
Puedes declarar funciones que el modelo puede solicitar cuando necesita realizar una acción externa.
Defines el nombre, descripción y parámetros de la función.
El modelo decide cuándo necesita utilizarla.
Tu servidor ejecuta la función real.
Devuelves el resultado al modelo.
El modelo utiliza ese resultado para continuar.
Consultar una base de datos, buscar inventario, calcular un precio, crear una reserva o comunicarse con otra API.
tool_choice y max_tool_calls
La aplicación puede controlar cómo se utilizan las herramientas.
| Parámetro | Función |
|---|---|
tool_choice |
Controla qué herramientas puede seleccionar el modelo |
tools |
Lista las herramientas disponibles |
max_tool_calls |
Limita el total de llamadas a herramientas integradas |
parallel_tool_calls |
Permite llamadas a herramientas en paralelo cuando corresponda |
Cómo mantener una conversación
Responses API ofrece diferentes formas de mantener continuidad entre solicitudes.
previous_response_id
Permite enlazar una nueva respuesta con una respuesta anterior.
conversation
Asocia respuestas a una conversación gestionada como entidad.
previous_response_id
Es una forma sencilla de continuar el contexto desde una respuesta previa.
Continuar una respuesta
{
"model": "gpt-5.6-sol",
"previous_response_id": "resp_123",
"input": "Ahora explícalo con un ejemplo."
}
La referencia
previous_response_id
y el parámetro
conversation
representan mecanismos
diferentes de continuidad
y no se utilizan juntos
en la misma solicitud.
Conversaciones persistentes entre respuestas
Al asociar una respuesta con una conversación, sus elementos de entrada y salida pueden formar parte de ese flujo.
Estado compartido
Los items de la conversación pueden añadirse al contexto de futuras respuestas, facilitando experiencias de varios turnos.
Ejecutar respuestas en segundo plano
Determinados trabajos pueden tardar más de lo apropiado para una conexión síncrona.
Tareas de mayor duración
{
"model": "gpt-6-astra",
"background": true,
"input": "Analiza este conjunto de información..."
}La API permite recuperar una respuesta utilizando su identificador y comprobar su estado.
Estados posibles de una respuesta
Una respuesta puede pasar por diferentes estados durante su ejecución.
| Estado | Significado general |
|---|---|
queued |
Esperando procesamiento |
in_progress |
Respuesta en ejecución |
completed |
Procesamiento finalizado |
failed |
La respuesta terminó con error |
cancelled |
La ejecución fue cancelada |
incomplete |
Terminó sin completar totalmente la generación |
Recuperar una respuesta por ID
Responses API dispone de una operación para obtener una respuesta existente.
Consultar respuesta
GET /v1/responses/{response_id}Recuperar, cancelar y eliminar respuestas
El recurso Responses incluye operaciones adicionales además de crear una respuesta.
| Acción | Operación |
|---|---|
| Crear | POST /responses |
| Obtener | GET /responses/{response_id} |
| Cancelar | POST /responses/{response_id}/cancel |
| Eliminar | DELETE /responses/{response_id} |
Mostrar la respuesta mientras se genera
Las aplicaciones conversacionales pueden utilizar streaming para comenzar a mostrar resultados antes de que termine la respuesta.
Menor latencia percibida
El usuario puede comenzar a leer la respuesta mientras el modelo continúa generándola.
max_output_tokens
Este parámetro permite limitar la cantidad máxima de tokens generados.
Visible output + reasoning
max_output_tokens
establece un límite superior
para la cantidad de tokens
que puede utilizar la respuesta.
No configures un output enorme para respuestas que deberían ser breves.
Ver precios de OpenAI API →Control de truncamiento
Responses API permite definir qué ocurre cuando el input supera la ventana de contexto.
| Valor | Comportamiento |
|---|---|
disabled |
La solicitud falla si excede el contexto permitido |
auto |
Puede eliminar elementos iniciales para ajustar el contexto |
Gestionar el tamaño del contexto ayuda a evitar errores, costos innecesarios y pérdida de información relevante.
Gestionar conversaciones largas
Responses API incorpora controles para manejar el crecimiento del contexto en workflows extensos.
Reducir contexto acumulado
Los mecanismos de gestión de contexto ayudan a mantener conversaciones y workflows prolongados sin enviar información innecesaria en cada interacción.
Optimizar contexto repetido
Las aplicaciones que reutilizan instrucciones o contexto pueden beneficiarse de prompt caching.
Menor costo para contexto reutilizado
Los modelos compatibles pueden aplicar una tarifa inferior a determinados tokens de entrada reutilizados mediante caché.
Comparar precios →Responses API vs Chat Completions
Ambas interfaces pueden trabajar con modelos, pero su diseño y alcance son diferentes.
| Característica | Responses API | Chat Completions |
|---|---|---|
| Endpoint | /v1/responses |
/v1/chat/completions |
| Input principal | Input items | Messages |
| Herramientas integradas | Amplio soporte | Más limitado según workflow |
| Conversation state | Integrado | Normalmente gestionado por la aplicación |
| Background responses | Sí | No es su enfoque principal |
| Workflows agentic | Especialmente orientado | Más tradicional |
Para aplicaciones que necesitan herramientas, modelos de razonamiento, estado y workflows agentic, Responses API ofrece una arquitectura más amplia.
Errores y casos incompletos
Una aplicación no debería asumir que toda respuesta termina correctamente.
Comprueba
status.
Revisa
error
cuando exista.
Comprueba
incomplete_details
en respuestas incompletas.
Implementa reintentos únicamente para errores apropiados.
Controla rate limits y consumo.
Si estás alcanzando RPM, TPM u otros límites, revisa nuestra guía específica.
Ver límites de OpenAI API →Buenas prácticas al utilizar Responses API
Integrar herramientas aumenta la capacidad de una aplicación, pero también requiere más controles.
Mantén las API keys fuera del frontend.
Valida argumentos de function calling antes de ejecutar acciones.
Aplica permisos mínimos a cada herramienta.
Confirma operaciones sensibles antes de producir efectos externos.
Registra errores, tool calls y consumo.
Documentación oficial de Responses API
OpenAI continúa ampliando esta interfaz, por lo que la referencia oficial debe considerarse la fuente final para parámetros y compatibilidad.
Responses API
Revisa los parámetros, tipos de herramientas, objetos de respuesta y ejemplos actualizados.
Consultar documentación oficial →Guías relacionadas con Responses API
Continúa con modelos, límites, precios y herramientas de OpenAI.
FAQ sobre Responses API
Respuestas rápidas sobre endpoint, conversaciones, herramientas y outputs.
Es una interfaz de OpenAI para generar respuestas utilizando modelos, texto, imágenes, archivos y herramientas.
El endpoint principal para crear una respuesta es POST /v1/responses.
Sí. Puede trabajar con herramientas integradas, MCP y funciones personalizadas.
Es el identificador de una respuesta anterior que puede utilizarse para continuar una interacción multi-turn.
No. Representan mecanismos diferentes de continuidad y no se utilizan juntos en la misma solicitud.
Sí. El parámetro background permite ejecutar determinadas respuestas en segundo plano.
Es un límite superior para la cantidad de tokens que puede generar una respuesta.
Son interfaces diferentes. Responses API está especialmente orientada a herramientas, estado y workflows agentic, mientras Chat Completions mantiene una estructura centrada principalmente en mensajes.
La compatibilidad depende del modelo seleccionado y de las capacidades disponibles para ese modelo.
Continúa explorando OpenAI API
Ya conoces Responses API. Revisa ahora modelos, precios y límites para diseñar una integración preparada para producción.
Ver guía de OpenAI API →