DEV Community

Cover image for ¿Cómo usar la API de Respuestas de OpenAI?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Cómo usar la API de Respuestas de OpenAI?

Esta guía muestra cómo implementar y probar la API de respuestas de OpenAI con POST /v1/responses: enviar la primera solicitud, leer la salida anidada, activar herramientas integradas, continuar conversaciones con estado y validar el contrato HTTP en Apidog. La API de respuestas es la interfaz más reciente de OpenAI para generar salidas de modelo; la guía oficial de migración a Responses explica por qué OpenAI recomienda usarla en proyectos nuevos. Si ya probaba el endpoint anterior, puede reutilizar gran parte del flujo, igual que en esta guía para probar la API de ChatGPT con Apidog.

Prueba Apidog hoy

Lo que necesita primero

Antes de llamar a POST /v1/responses, prepare lo siguiente:

  • Una clave de API de OpenAI con acceso a un modelo actual de propósito general.
  • Una variable de entorno para la clave. No la pegue en comandos, repositorios ni colecciones compartidas.
  • Un nombre de modelo disponible para su cuenta. Verifíquelo en el panel de OpenAI o con el endpoint correspondiente antes de codificarlo.
  • Una herramienta para enviar HTTP sin procesar e inspeccionar JSON. Puede empezar con curl y luego usar Apidog para pruebas, aserciones y mocks.

La API de respuestas expone un endpoint principal: POST /v1/responses. Usted envía un model y una input; OpenAI devuelve un objeto de respuesta que puede incluir texto, llamadas a funciones y resultados de herramientas alojadas como búsqueda web, búsqueda de archivos o ejecución de código.

Una sola llamada puede cubrir un turno completo de varios pasos. Por ejemplo:

  1. El modelo recibe una pregunta.
  2. Decide usar una herramienta como web_search.
  3. Lee los resultados.
  4. Devuelve una respuesta final.
  5. El objeto response registra los pasos ejecutados.

Hay dos diferencias importantes frente a un endpoint de texto simple:

  • Puede ejecutar herramientas integradas del lado de OpenAI.
  • Mantiene estado por defecto mediante un id de respuesta que puede reutilizar en llamadas posteriores.

OpenAI describe Responses como la evolución de Chat Completions y la recomienda para proyectos nuevos, incorporando aprendizajes de la beta de la API de Asistentes.

Cómo difiere de las finalizaciones de chat

Si ya usó POST /v1/chat/completions, el cambio principal está en la estructura de entrada, la estructura de salida y el manejo del estado.

Chat Completions recibe una matriz messages y devuelve choices. Usted gestiona la transcripción completa y reenvía el historial en cada llamada.

Responses recibe una input, que puede ser una cadena o una lista de elementos tipados, y devuelve una matriz output con elementos tipados. Además, puede guardar el turno y continuar la conversación con previous_response_id.

Aspecto Finalizaciones de chat API de respuestas
Endpoint POST /v1/chat/completions POST /v1/responses
Cuerpo de solicitud Matriz messages input + instructions
Forma de salida choices[].message Lista output de elementos tipados
Estado de conversación Usted reenvía todo el historial store + previous_response_id
Herramientas integradas Usted las implementa web_search, file_search, code_interpreter y más
Estado del producto Compatible, sin depreciación anunciada Recomendado para proyectos nuevos

Chat Completions no desaparece por ahora. OpenAI indica que seguirá siendo compatible, así que puede migrar flujo por flujo. La API de Asistentes sí tiene un plazo: fue deprecada el 26 de agosto de 2025, con fin de vida declarado para el 26 de agosto de 2026. Para trabajo nuevo con agentes, conviene empezar en Responses.

Haga su primera solicitud

Use esta llamada mínima como prueba inicial. Cambie el modelo por uno disponible para su cuenta.

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
  }'
Enter fullscreen mode Exit fullscreen mode

En esta solicitud:

  • model define el modelo que ejecutará la respuesta.
  • input contiene la instrucción del usuario.
  • instructions define comportamiento de nivel superior.
  • store: true permite guardar la respuesta para continuar el hilo después.

Lea la respuesta

Una respuesta recortada puede verse 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
  }
}
Enter fullscreen mode Exit fullscreen mode

La parte importante es la ruta del texto. En HTTP sin procesar, el texto no está en un campo plano de nivel superior. Está anidado en:

output[0].content[0].text
Enter fullscreen mode Exit fullscreen mode

Los SDK oficiales pueden exponer un helper como output_text, que concatena los elementos de texto, pero esa comodidad pertenece al SDK. Si trabaja directamente con HTTP, lea la estructura anidada.

También debe guardar estos campos:

  • id: úselo como previous_response_id en una llamada posterior.
  • status: confirme que sea completed.
  • usage.total_tokens: úselo para observar consumo y costos.

Añada herramientas integradas

Responses permite pasar herramientas en una matriz tools. El modelo decide cuándo llamarlas.

Tipos integrados verificados:

  • web_search: búsqueda en internet con citas. El tipo anterior web_search_preview sigue funcionando en integraciones heredadas, pero no tiene los controles más nuevos.
  • file_search: recuperación de información desde archivos subidos.
  • code_interpreter: ejecución y análisis de código en un sandbox.
  • computer_use: interacción con una interfaz de computadora.
  • image_generation: generación de imágenes en línea.

Ejemplo con búsqueda web:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}
Enter fullscreen mode Exit fullscreen mode

Cuando el modelo usa una herramienta, output incluye elementos adicionales que documentan el paso. Por ejemplo, puede aparecer un elemento con type igual a web_search_call, además del mensaje final.

Esto es útil para pruebas: no solo valida que haya texto, también puede validar que la herramienta se ejecutó.

Continúe la conversación entre llamadas

El estado se controla con dos campos:

  • store: indica si OpenAI guarda la respuesta. Por defecto es true y la retención predeterminada es de 30 días.
  • previous_response_id: vincula una nueva solicitud con una respuesta anterior.

Ejemplo:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

Con esto, no necesita reenviar toda la conversación. OpenAI continúa el hilo del lado del servidor.

Si necesita comportamiento sin estado o tiene requisitos de retención cero, use:

{
  "model": "gpt-5.5",
  "input": "Write one sentence describing what an API mock server does.",
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

Para voz, audio en tiempo real y baja latencia, OpenAI usa otra superficie. Ese caso está cubierto en la guía de la API en tiempo real de GPT. Si además orquesta agentes de varios pasos, los patrones se alinean con el SDK de Agentes de OpenAI.

Cómo probarlo en Apidog

Apidog es una plataforma de diseño, prueba y simulación de API. No es un SDK de OpenAI ni una biblioteca de código. Su función aquí es validar el contrato HTTP:

  1. Construir la solicitud a /v1/responses.
  2. Enviarla con headers y body reales.
  3. Inspeccionar el JSON de respuesta.
  4. Crear aserciones sobre los campos que su aplicación necesita.
  5. Simular la respuesta para desarrollo local o pruebas sin conexión.

Captura de Apidog

1. Guarde la clave en una variable de entorno

En Apidog, cree un entorno, por ejemplo:

OpenAI Producción
Enter fullscreen mode Exit fullscreen mode

Agregue una variable:

OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Luego cree una solicitud:

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

Agregue el header:

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Así evita guardar la clave directamente en la solicitud.

2. Configure el cuerpo JSON

Pegue un body como este:

{
  "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
}
Enter fullscreen mode Exit fullscreen mode

Envíe la solicitud y revise el objeto completo. Verifique especialmente:

id
status
output
usage.total_tokens
Enter fullscreen mode Exit fullscreen mode

3. Añada aserciones sobre la respuesta

Un 200 OK no garantiza que la respuesta tenga la forma esperada. Agregue aserciones para fallar rápido ante cambios de contrato.

Verificaciones útiles:

  • status es igual a completed.
  • output[0].content[0].text existe.
  • output[0].content[0].text no está vacío.
  • usage.total_tokens es mayor que 0.
  • Si envía tools, al menos un elemento de output tiene type igual a web_search_call.

Ejemplo de rutas a validar:

$.status
$.output[0].content[0].text
$.usage.total_tokens
$.output[*].type
Enter fullscreen mode Exit fullscreen mode

El constructor visual de aserciones de Apidog permite apuntar a esas rutas JSON sin escribir scripts. Esta plantilla de caso de prueba de API muestra cómo organizar esas verificaciones.

Guarde la solicitud en una colección para ejecutarla de forma repetible, incluso dentro de CI.

4. Simule la respuesta para desarrollo sin conexión

Las llamadas a OpenAI consumen tokens y requieren red. Eso puede ser un problema cuando:

  • Está desarrollando una interfaz que consume la respuesta.
  • Ejecuta pruebas automatizadas.
  • Quiere resultados deterministas.
  • No quiere que una pipeline dependa de una API externa de pago.

La simulación de Apidog resuelve ese flujo:

  1. Guarde una respuesta representativa de /v1/responses.
  2. Cree un mock con esa carga JSON.
  3. Apunte su aplicación a la URL mock de Apidog.
  4. Ejecute el frontend o las pruebas contra la misma estructura de respuesta.

Ejemplo de respuesta mock mínima:

{
  "id": "resp_mock_123",
  "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 for development and testing."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}
Enter fullscreen mode Exit fullscreen mode

La explicación de API simulada detalla este enfoque.

La división práctica es simple:

  • Pruebe contra OpenAI en vivo para validar el contrato real.
  • Use mocks para desarrollo rápido, sin red y sin gasto de tokens.

Ambos flujos pueden vivir en el mismo proyecto de Apidog.

Preguntas frecuentes

¿La API de respuestas reemplazará a las finalizaciones de chat?

No de forma forzada. OpenAI describe Responses como la evolución de Chat Completions y la recomienda para proyectos nuevos, pero Chat Completions sigue siendo compatible y no tiene una fecha de depreciación anunciada. Puede migrar un flujo a la vez.

La API de Asistentes sí tiene fecha de retiro, con finalización declarada 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, con retención predeterminada de 30 días.

previous_response_id conecta una nueva solicitud con una respuesta almacenada para que el modelo continúe la conversación del lado del servidor.

Úselos juntos para conversaciones con estado. Use store: false cuando quiera manejar el contexto usted mismo.

¿Qué modelos soportan la API de respuestas?

Los modelos actuales de propósito general de OpenAI están diseñados para funcionar con Responses, pero la disponibilidad depende de su cuenta y del modelo elegido.

No codifique un nombre sin verificarlo. Revise la lista de modelos en el panel de OpenAI y confirme con una llamada real. En Apidog, puede enviar una solicitud rápida y revisar el campo:

model
Enter fullscreen mode Exit fullscreen mode

en la respuesta.

¿Puedo probar herramientas integradas sin escribir código?

Sí. En Apidog, agregue tools al body JSON, envíe la solicitud y valide que el elemento de herramienta aparezca en output.

Ejemplo:

{
  "model": "gpt-5.5",
  "input": "Search for the latest OpenAPI release and summarize it.",
  "tools": [{ "type": "web_search" }]
}
Enter fullscreen mode Exit fullscreen mode

Luego afirme que existe:

web_search_call
Enter fullscreen mode Exit fullscreen mode

en la matriz output.

Está probando el comportamiento mediante HTTP, así que no necesita SDK. Para pruebas más amplias de llamadas de herramientas en agentes, consulte cómo generar colecciones de pruebas de API a partir de especificaciones OpenAPI.

Conclusión

La API de respuestas centraliza texto, herramientas integradas y estado de conversación en un solo endpoint:

POST /v1/responses
Enter fullscreen mode Exit fullscreen mode

El flujo básico es:

  1. Enviar model, input e instructions.
  2. Leer el texto en output[0].content[0].text.
  3. Revisar usage.total_tokens.
  4. Agregar tools cuando necesite búsqueda, archivos o ejecución de código.
  5. Encadenar llamadas con previous_response_id.
  6. Validar el contrato con pruebas HTTP.

Como la forma de respuesta difiere de Chat Completions, no confíe en rutas antiguas como choices[].message. Valide explícitamente la estructura que consume su aplicación.

En Apidog puede construir la solicitud, guardar la clave como variable de entorno, crear aserciones sobre output, simular respuestas y ejecutar pruebas repetibles. Descargue Apidog y apunte una prueba a /v1/responses para ver exactamente qué recibirá su integración. También puede configurar todo desde Apidog sin escribir código de prueba.

Top comments (0)