Esta guía le explica cómo usar la API de respuestas de OpenAI de principio a fin: cuando termine, podrá enviar una solicitud a POST /v1/responses, leer la salida anidada que devuelve, activar herramientas integradas, mantener el estado de la conversación entre llamadas y verificar todo el contrato dentro de Apidog. La API de respuestas es la interfaz más reciente de OpenAI para generar la salida del modelo, y la guía oficial de respuestas explica por qué OpenAI ahora dirige los nuevos proyectos hacia ella. Si ya prueba el punto final anterior, puede reutilizar la mayor parte de esa configuración, de manera muy similar al flujo de trabajo en nuestra guía de prueba de la API de ChatGPT con Apidog.
Lo que necesita primero
Antes de enviar una solicitud, asegúrese de tener algunas cosas en su lugar:
- Una clave de API de OpenAI con acceso a un modelo actual de propósito general. Mantenga la clave en una variable de entorno, no pegada en un comando o un archivo compartido.
- Un nombre de modelo al que su cuenta pueda llamar realmente. En lugar de codificar uno, verifique la lista de modelos en su panel de OpenAI y confírmelo con el punto final.
- Una forma de enviar solicitudes HTTP sin procesar e inspeccionar el JSON que regresa. Un terminal con
curlfunciona para una primera llamada, y Apidog es lo que usará para afirmar y simular la respuesta más adelante.
También ayuda saber qué hace el punto final antes de llamarlo. La API de respuestas expone un único punto final, POST /v1/responses. Usted envía un nombre de modelo y una input, y obtiene un objeto de respuesta que puede contener texto sin formato, llamadas a funciones y los resultados de herramientas alojadas por OpenAI como búsqueda web o búsqueda de archivos. Una llamada puede ejecutar un turno completo de varios pasos: el modelo decide buscar en la web, lee los resultados, luego escribe una respuesta, y la respuesta registra cada paso que tomó.
Dos cosas la distinguen de un punto final de texto sin formato. Primero, puede ejecutar herramientas integradas en el lado del servidor, por lo que no tiene que conectar su propia búsqueda o sandbox. Segundo, tiene estado por defecto. Cada respuesta obtiene un id, y puede pasar ese id a la siguiente solicitud para que OpenAI mantenga el historial de la conversación por usted. OpenAI describe la API de respuestas como la evolución de las finalizaciones de chat y la recomienda para nuevos proyectos, incorporando lecciones de la beta de la API de Asistentes. Así que en lugar de tres modelos mentales, obtiene uno.
Cómo difiere de las finalizaciones de chat
Si ha utilizado POST /v1/chat/completions, el cambio es principalmente en la forma y el estado. Las finalizaciones de chat toman una matriz de messages y devuelven choices. Usted mismo gestiona la transcripción completa, reenviando cada turno anterior en cada llamada. Las herramientas son algo que usted implementa por su cuenta.
La API de respuestas toma una input (una cadena o una lista de elementos tipados) y devuelve una output (una lista de elementos tipados). Puede almacenar el turno por usted y ejecutar herramientas alojadas sin necesidad de cableado adicional.
Aquí está la comparación práctica:
| Aspecto | Finalizaciones de chat | API de respuestas |
|---|---|---|
| Punto final | POST /v1/chat/completions |
POST /v1/responses |
| Cuerpo de la solicitud | Matriz de messages |
input (cadena o elementos) + instructions |
| Forma de salida | choices[].message |
Lista de output de elementos tipados |
| Estado de la conversación | Usted reenvía el historial completo | store + previous_response_id |
| Herramientas integradas | Usted las construye | web_search, file_search, code_interpreter y más |
| Estado | Compatible, no se ha anunciado depreciación | Recomendado para nuevos proyectos |
Las finalizaciones de chat no van a desaparecer. OpenAI dice que seguirán siendo compatibles, y usted puede migrar un flujo de usuario a la vez en lugar de reescribir todo a la vez. La API de Asistentes es la que tiene un plazo: OpenAI la ha deprecado el 26 de agosto de 2025, con un fin de vida declarado para el 26 de agosto de 2026, por lo que el nuevo trabajo de agentes debe comenzar en Responses.
Haga su primera solicitud
Aquí hay una llamada mínima. Cambie el nombre del modelo por el que tenga acceso su cuenta y mantenga su clave fuera del comando mismo.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Write one sentence describing what an API mock server does.",
"instructions": "You are a concise technical writer. No marketing language.",
"store": true
}'
Aquí se pasan tres cosas importantes: el model, la input (su instrucción), y las instructions (la dirección a nivel de sistema). Al establecer store en true, le dice a OpenAI que guarde la respuesta para que pueda continuar el hilo más tarde.
Lea la respuesta
Una respuesta recortada se ve así:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "gpt-5.5",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 24,
"total_tokens": 52
}
}
Observe la estructura, porque es la parte que confunde a la gente. El texto que desea se encuentra en output[0].content[0].text, no en un campo de nivel superior. Los SDK oficiales agregan un accesor de conveniencia output_text que agrega todos los elementos de texto en una sola cadena, pero esa propiedad es una ayuda del SDK, no parte del JSON HTTP sin procesar. Cuando llama directamente al punto final, lee la ruta anidada. El id de nivel superior es lo que reutilizará para el estado, y usage.total_tokens le indica el costo de la llamada.
Añada herramientas integradas
La característica principal es que OpenAI ejecuta ciertas herramientas por usted. Las enumera en una matriz tools y el modelo decide cuándo llamarlas. Los tipos integrados verificados incluyen:
web_searchpara búsquedas en internet en tiempo real con citas (el antiguoweb_search_previewsigue funcionando para integraciones heredadas pero carece de controles más nuevos).file_searchpara recuperar información de archivos que ha subido.code_interpreterpara ejecutar y analizar código en un sandbox.computer_usepara manejar una interfaz de computadora.image_generationpara producir imágenes en línea.
Activar una es una pequeña adición al cuerpo:
{
"model": "gpt-5.5",
"input": "What changed in the latest OpenAPI release? Cite sources.",
"tools": [{ "type": "web_search" }]
}
Cuando el modelo utiliza una herramienta, la matriz output gana entradas que documentan el paso, como un elemento web_search_call junto con el message final. Esto es útil más adelante: puede verificar que una herramienta realmente se activó, no solo que regresó texto.
Continúe la conversación entre llamadas
El estado funciona a través de dos parámetros. store se establece en verdadero por defecto, lo que significa que OpenAI guarda el objeto de respuesta (retenido por 30 días por defecto) y devuelve un id. Pase ese id como previous_response_id en su próxima llamada y el modelo continuará el hilo sin que usted reenvíe la transcripción:
{
"model": "gpt-5.5",
"input": "Now rewrite that for a non-technical audience.",
"previous_response_id": "resp_abc123"
}
Si prefiere mantener las cosas sin estado, o si tiene un requisito de retención de datos cero, establezca store en falso y gestione el contexto usted mismo. Para flujos de voz y audio en tiempo real y de baja latencia, OpenAI utiliza una superficie diferente; nuestra guía de la API en tiempo real de GPT cubre ese caso. Y si está orquestando agentes de varios pasos además de todo esto, los patrones se alinean con el SDK de Agentes de OpenAI.
Cómo probarlo en Apidog
Apidog es una plataforma de prueba, diseño y simulación de API. No es un SDK de OpenAI ni una biblioteca de código, por lo que no escribirá Python contra ella. Lo que sí hace: construye la solicitud HTTP sin procesar a /v1/responses, la envía y escribe aserciones sobre el JSON que regresa. Ese es exactamente el tipo de verificación de contrato que detecta una integración rota antes que sus usuarios.
Aquí está la configuración, paso a paso.
Guarde la clave en una variable de entorno
En Apidog, cree un entorno (por ejemplo, "OpenAI Producción") y agregue una variable como OPENAI_API_KEY. Mantenga el valor en el entorno, no en la solicitud, para que el secreto nunca se confirme en una colección compartida. Luego, cree una nueva solicitud POST a https://api.openai.com/v1/responses y agregue el encabezado Authorization: Bearer {{OPENAI_API_KEY}}. Apidog sustituye la variable en el momento del envío.
Establezca el cuerpo en JSON y pegue la solicitud anterior. Presione enviar. Verá el objeto de respuesta completo, formateado, con la matriz output anidada.
Afirmar sobre los campos de la respuesta
Un 200 exitoso no es prueba de que la respuesta tenga la forma que su aplicación espera. Agregue aserciones para que una regresión falle ruidosamente. Verificaciones útiles contra una respuesta a /v1/responses:
statuses igual acompleted.output[0].content[0].textexiste y no está vacío.usage.total_tokenses mayor que 0.- Cuando envía
tools, un elemento enoutputtienetypeigual aweb_search_call.
El constructor de aserciones visuales de Apidog le permite apuntar a esas rutas JSON sin escribir scripts de prueba, y nuestra plantilla de caso de prueba de API muestra cómo estructurar estas verificaciones. Guarde la solicitud en una colección y se convertirá en una prueba repetible que puede ejecutar en CI.
Simule la respuesta para el desarrollo sin conexión
Las llamadas a OpenAI cuestan dinero y necesitan acceso a la red, lo que resulta incómodo cuando está construyendo la interfaz de usuario que consume la respuesta o ejecutando pruebas en una canalización que no debería acceder a una API de pago. La función de simulación de Apidog resuelve eso. Guarde una carga útil representativa de /v1/responses como una simulación, dirija su aplicación a la URL de simulación de Apidog y su frontend obtendrá la forma JSON correcta con cero gasto de tokens. Cuando el punto final real cambia, actualiza una simulación en lugar de perseguir fallos en cada prueba. Nuestro explicación de la API simulada detalla el enfoque general.
Esta división es importante. Usted prueba contra el punto final en vivo para verificar el contrato de OpenAI, y lo simula para un desarrollo rápido, sin conexión y determinista. Ambos se ejecutan desde el mismo proyecto de Apidog.
Preguntas frecuentes
¿La API de respuestas reemplazará a las finalizaciones de chat?
No por la fuerza. OpenAI llama a Responses la evolución de Chat Completions y la recomienda para nuevos proyectos, pero Chat Completions sigue siendo compatible sin una fecha de depreciación anunciada. Puede migrar un flujo a la vez. La API de Asistentes es la que se retirará, con una fecha de finalización en 2026.
¿Cuál es la diferencia entre store y previous_response_id?
store controla si OpenAI guarda el objeto de respuesta (por defecto es true y lo retiene durante 30 días). previous_response_id es cómo vincula una nueva solicitud a una almacenada para que el modelo continúe la conversación en el lado del servidor. Los usa juntos para hilos con estado, y desactiva store cuando desea un comportamiento sin estado.
¿Qué modelos soportan la API de respuestas?
Los modelos de propósito general actuales de OpenAI están diseñados para funcionar con la API de respuestas, pero la disponibilidad depende de su cuenta y del modelo que elija. En lugar de codificar un nombre de modelo, verifique la lista de modelos en su panel de OpenAI y luego confírmela con el punto final. Enviar una solicitud rápida a través de Apidog y leer el campo model en la respuesta es una forma rápida de verificar lo que su clave puede llamar realmente.
¿Puedo probar las herramientas integradas sin escribir código?
Sí. Agregue una matriz tools al cuerpo JSON en Apidog, envíe la solicitud y afirme que el elemento de llamada de herramienta coincidente (como web_search_call) aparece en la matriz output. Está verificando el comportamiento de OpenAI a través de HTTP, por lo que no se requiere ningún SDK. Para probar las llamadas a herramientas de agente de manera más amplia, vea cómo generar colecciones de pruebas de API a partir de especificaciones OpenAPI.
Conclusión
Ahora tiene el ciclo completo: un único punto final, POST /v1/responses, que maneja texto, herramientas alojadas y estado de conversación en el servidor. Envíe una solicitud, lea la output anidada, agregue una matriz tools cuando necesite búsqueda o ejecución de código, y encadene previous_response_id para mantener un hilo de conversación. Dado que la forma es diferente a la de Chat Completions, la medida más segura es verificar el contrato usted mismo en lugar de confiar en su memoria de la API anterior.
Ahí es donde encaja Apidog. Construya la solicitud, almacene su clave como una variable de entorno, afirme sobre los campos output anidados y simule la respuesta para el trabajo sin conexión, todo en un solo proyecto. Descargue Apidog y apunte una prueba a /v1/responses para ver exactamente lo que recibe su integración. Puede realizar toda la configuración en Apidog sin escribir una sola línea de código de prueba.