API de OpenAI: Guía de especificación e implementación de la Responses API y Structured Outputs

Introducción

Entrando en 2025, la API de OpenAI ha alcanzado un punto de inflexión importante. En marzo de 2025, la Responses API fue lanzada oficialmente (GA), consolidando las capacidades de conversación de la Chat Completions API y las funciones de integración de herramientas de la Assistants API en un único endpoint. La API de Assistants (legacy) está programada para ser retirada el 26 de agosto de 2026.

Además, Structured Outputs, que garantiza que las salidas del modelo se adhieren estrictamente a un esquema JSON, demuestra su verdadero potencial cuando se combina con la Responses API. Desde su lanzamiento en agosto de 2024, ha mejorado significativamente la fiabilidad de los flujos de trabajo agénticos y los pipelines de extracción de datos.

Este artículo primero describe el panorama general de la API de OpenAI a partir de 2025, y luego profundiza en las especificaciones y detalles de implementación de estos dos temas clave.

Información de fuentes
Las especificaciones y datos de rendimiento en este artículo hacen referencia a la Documentación Oficial de OpenAI (developers.openai.com/api), la Guía de Migración Oficial (developers.openai.com/api/docs/guides/migrate-to-responses) y el Blog Oficial (openai.com/index/introducing-structured-outputs-in-the-api).

1. Panorama de la API

Las principales categorías de la API de OpenAI a partir de 2025 se organizan de la siguiente manera:

OpenAI ha posicionado la Responses API como el destino principal para nuevas funcionalidades, y la retirada de la Assistants API el 26 de agosto de 2026 ha sido confirmada oficialmente (Fuente: Guía de Migración Oficial). Aunque la Chat Completions API seguirá siendo soportada sin una fecha de retirada, la Responses API es la recomendación actual para nuevos proyectos.

Structured Outputs no es un endpoint independiente como los de la tabla anterior, sino una opción de control de formato de salida disponible tanto para la Responses API como para la Chat Completions API. Se especifica usando el parámetro text.format en la primera y el parámetro response_format en la última. Este artículo se enfoca particularmente en su combinación con la Responses API.

2. Responses API

2.1 Descripción general

La Responses API es un nuevo primitivo que sucede a la Chat Completions API e integra las funciones de la Assistants API. Alcanzó Disponibilidad General (GA) en marzo de 2025.

El cambio más significativo es la capacidad de persistir el estado de la conversación en el lado del servidor. A diferencia de las Chat Completions tradicionales, que requerían incluir todo el historial de la conversación en cada solicitud, la Responses API te permite continuar una conversación simplemente pasando un previous_response_id.

2.2 Solicitud básica

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Dime el clima en Tokio.",
});

console.log(response.output_text); // Recupera el texto directamente usando el helper output_text

2.3 El helper output_text

output_text es una propiedad de conveniencia proporcionada por el SDK de OpenAI, no es parte de la especificación de la API en sí.

En la respuesta sin procesar de la Responses API, el texto está anidado dentro de la siguiente estructura:

response.output[0].content[0].text

output_text resume el proceso de recorrer esta ruta. Internamente, devuelve el texto del primer elemento en el array output que tiene type: "message" y un bloque content con type: "output_text".

// Ambos producen el mismo resultado
console.log(response.output_text);
console.log(response.output[0].content[0].text);

Sin embargo, puede no funcionar como se espera si el primer elemento en el array output no es un mensaje de texto — por ejemplo, cuando ocurre una llamada a herramienta. Para código agéntico robusto que usa herramientas, es mejor recorrer el array output y verificar el type.

for (const item of response.output) {
  if (item.type === "message") {
    for (const block of item.content) {
      if (block.type === "output_text") {
        console.log(block.text);
      }
    }
  }
}

2.4 role en los mensajes de entrada

Al pasar un array a input, puedes especificar un role para cada mensaje. El role le dice al modelo "quién está haciendo esta declaración", y hay tres tipos.

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    {
      role: "system",
      content: "Eres un asistente útil en español. Por favor, responde de forma concisa.",
    },
    {
      role: "user",
      content: "Cuéntame sobre los métodos de array de JavaScript.",
    },
  ],
});

Si pasas una cadena directamente a input (como en el ejemplo en 2.2), esa cadena se trata como un mensaje con role: "user". Usa el formato de array si quieres un control detallado sobre el comportamiento del modelo o si quieres proporcionar instrucciones system.

2.5 Estructura de la respuesta

A diferencia de choices de Chat Completions, los resultados se devuelven en un array output.

{
  "id": "resp_68af4030...",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-4o",
  "output": [
    {
      "id": "msg_68af4033...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "El clima en Tokio es soleado."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 12,
    "total_tokens": 27
  }
}

2.6 Conversación multipaso

Hay dos formas de lograr conversaciones multipaso con la Responses API.

1. Pasar el historial como un array en input

Este es el método tradicional de la Chat Completions API. Mantienes y gestionas el historial de la conversación en el lado del cliente e incluyes todos los mensajes en cada solicitud.

const history = [
  { role: "system", content: "Eres un asistente útil." },
  { role: "user", content: "Dime el clima en Tokio." },
  { role: "assistant", content: "Hoy está soleado en Tokio." },
];

const response = await client.responses.create({
  model: "gpt-4o",
  input: [...history, { role: "user", content: "¿Y mañana?" }],
});

Dado que el estado no se mantiene en el servidor, la ventaja es que puedes manipular libremente el historial, como eliminar o resumir mensajes específicos. Sin embargo, a medida que la conversación se alarga, aumenta el número de tokens de entrada, impactando tanto el costo como la latencia.

2. Pasar previous_response_id (exclusivo de Responses API)

Este es el método de gestión de estado del lado del servidor introducido con la Responses API. Simplemente pasando el ID de la respuesta anterior, los servidores de OpenAI continuarán el historial de la conversación.

// Primer turno
const response1 = await client.responses.create({
  model: "gpt-4o",
  input: "Dime el clima en Tokio.",
});

// Segundo turno: El contexto se hereda usando solo previous_response_id
const response2 = await client.responses.create({
  model: "gpt-4o",
  input: "¿Y mañana?",
  previous_response_id: response1.id,
});

El cliente no necesita mantener ni enviar todo el historial, manteniendo pequeño el tamaño de la solicitud. Además, al usar modelos de razonamiento como o1 u o3, los tokens de pensamiento se preservan entre turnos, lo cual es una ventaja significativa ya que mejora la precisión para tareas que requieren razonamiento continuo.

Para usar este método, la respuesta debe guardarse en el servidor. Ten en cuenta que aunque el parámetro store por defecto es true, establecerlo a store: false hará imposible la referencia por ID.

Criterios de selección

Si se requiere gestión de conversación persistente, también es posible la integración con la Conversations API.

2.7 Herramientas integradas

Uno de los mayores beneficios de la Responses API es el conjunto de herramientas integradas disponibles sin infraestructura adicional.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Busca las últimas noticias de OpenAI y resúmelas.",
  tools: [
    { type: "web_search_preview" },
    { type: "file_search" },
    { type: "code_interpreter" },
  ],
});

Integración MCP (Model Context Protocol)

Los Connectors son wrappers MCP mantenidos por OpenAI para servicios populares como Google Workspace o Dropbox, mientras que los servidores MCP remotos son cualquier servidor en la internet pública que implemente el protocolo MCP remoto (Fuente: Guía de Connectors y MCP de OpenAI).

La Responses API puede integrarse con servidores MCP remotos que soporten los protocolos de transporte Streamable HTTP o HTTP/SSE. Cuando se especifica una herramienta, la API primero recupera la lista de herramientas disponibles del servidor (mcp_list_tools), y el modelo luego llama a las herramientas necesarias de esa lista.

Ejemplo de conexión básica (Fuente: Guía de Using tools de OpenAI)

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Tira 2d6 y dime el resultado.",
  tools: [
    {
      type: "mcp",
      server_label: "dice_server",           // Identificador para el servidor (arbitrario)
      server_url: "https://example.com/mcp", // URL del servidor MCP
      require_approval: "never",             // Aprobar automáticamente las llamadas a herramientas
    },
  ],
});

console.log(response.output_text);

Control de aprobación con require_approval

Por defecto, todas las llamadas a herramientas requieren aprobación explícita del desarrollador. Puedes controlar este comportamiento con require_approval (Fuente: Guía de Connectors y MCP de OpenAI).

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Cuéntame sobre los protocolos de transporte de la especificación MCP.",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: {
        never: {
          // Estas dos herramientas no requieren aprobación; las demás sí
          tool_names: ["ask_question", "read_wiki_structure"],
        },
      },
    },
  ],
});

Conexión a servidores que requieren autenticación

Si el servidor MCP requiere autenticación, pasa el token usando el parámetro headers.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Obtén algunos datos.",
  tools: [
    {
      type: "mcp",
      server_label: "my_server",
      server_url: "https://my-mcp-server.example.com/mcp",
      require_approval: "never",
      headers: {
        Authorization: `Bearer ${process.env.MCP_ACCESS_TOKEN}`,
      },
    },
  ],
});

Caché de lista de herramientas: Aunque la recuperación de la lista de herramientas del servidor MCP (mcp_list_tools) ocurre por solicitud, en conversaciones multipaso que usan previous_response_id, la lista de herramientas se incluye en la respuesta anterior, por lo que se omite la re-recuperación (Fuente: OpenAI Cookbook: Guía de herramientas MCP).

2.8 Parámetros clave de la solicitud

2.9 Comparación con Chat Completions

2.10 Modelos de razonamiento (serie o)

Distintos de la serie GPT, OpenAI ofrece un grupo de modelos llamados Modelos de Razonamiento. Estos modelos ejecutan un proceso de pensamiento paso a paso interno (Chain-of-Thought) antes de generar una respuesta. Este pensamiento interno se cuenta como tokens de razonamiento, que no se incluyen en la salida final.

Demuestran una precisión significativamente mayor que GPT-4o para tareas que requieren razonamiento de múltiples pasos, como matemáticas, codificación, inferencia lógica y análisis complejos. Por otro lado, la latencia y los costos son mayores porque el pensamiento lleva tiempo.

Modelos principales a partir de 2025:

La profundidad del razonamiento se puede ajustar con el parámetro reasoning_effort (ver 2.8). low es un razonamiento ligero que reduce la latencia y el costo, mientras que high es un razonamiento profundo para máxima precisión.

const response = await client.responses.create({
  model: "o3",
  input: "Encuentra el término general para esta secuencia: 1, 1, 2, 3, 5, 8, 13, ...",
  reasoning_effort: "high",
});

Además, en conversaciones multipaso que usan previous_response_id (ver 2.6, método 2), los tokens de razonamiento se preservan entre turnos. Al profundizar en el mismo problema durante múltiples turnos, la precisión y eficiencia mejoran porque el modelo hereda el razonamiento del turno anterior en lugar de comenzar desde cero.

3. Structured Outputs

3.1 Descripción general y contexto

Forzar de manera confiable las salidas de LLM en formato JSON ha sido un desafío clave para la integración de aplicaciones. OpenAI ha resuelto esto de manera incremental:

Modo JSON (función legacy) garantiza JSON sintácticamente correcto, pero no garantiza la adherencia a un esquema. Existía el riesgo de que faltaran campos requeridos o hubiera campos adicionales no deseados.

Structured Outputs, lanzado en agosto de 2024, garantiza el 100% de adherencia a un esquema JSON especificado por el desarrollador (Fuente: Blog Oficial de OpenAI).

Las evaluaciones internas (evals) en OpenAI muestran que gpt-4o-2024-08-06 logra una adherencia del 100% a esquemas JSON complejos usando Structured Outputs, un salto enorme respecto al menos del 40% de gpt-4-0613 (Fuente: Blog Oficial de OpenAI).

3.2 Cómo funciona

La API de OpenAI logra salidas estructuradas convirtiendo el JSON Schema especificado en una Gramática Libre de Contexto (CFG). Esta gramática restringe los tokens que se pueden generar durante el muestreo, haciendo cumplir el esquema. Debido a esto, la primera vez que se envía un nuevo esquema, hay latencia adicional para el pre-procesamiento de la gramática, pero las solicitudes posteriores con el mismo esquema no incurren en esta penalización.

Nota (Modelos fine-tuned): Para los modelos fine-tuned, ocurre latencia adicional en la primera solicitud usando un nuevo esquema. Las solicitudes posteriores con el mismo esquema no tienen esto. Otros modelos no tienen esta limitación. (Fuente: Guía de Structured Outputs)

3.3 Dos formas de usar

Structured Outputs se proporciona en dos formas en la API.

La primera es mediante Function calling (tools), habilitado al establecer strict: true dentro de la definición de función. Está disponible en todos los modelos desde gpt-4-0613 en adelante y es adecuado para conectar las capacidades del modelo con aplicaciones (por ejemplo, acceder a una función de consulta de base de datos).

La segunda es mediante el parámetro response_format / text.format, donde especificar un json_schema es adecuado para que el modelo responda al usuario en un formato estructurado (por ejemplo, mostrar diferentes partes por separado en una UI de tutorial matemático).

3.4 Ejemplo de implementación (Responses API)

En la Responses API, el parámetro ha pasado de response_format a text.format (Fuente: Guía de Migración Oficial).

Sobre description en el esquema

Se recomienda encarecidamente incluir una description para cada campo en tu JSON Schema. La description actúa como una instrucción para el modelo, proporcionando pistas para ayudarlo a determinar correctamente qué debe ir en ese campo. Los nombres de campo generales como explanation o output son particularmente propensos a ser malinterpretados por el modelo sin una description.

Al usar Zod, usa .describe("..."). Al escribir el JSON Schema directamente, especifícalo con la clave "description" dentro del objeto de propiedad.

Definición de esquema usando Zod (Recomendado)

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

const Step = z.object({
  explanation: z.string().describe("Explicación de lo que se está haciendo en este paso de cálculo."),
  output: z.string().describe("El resultado del cálculo para este paso (fórmula o valor numérico)."),
});

const MathResponse = z.object({
  steps: z.array(Step).describe("Una lista de pasos para la solución."),
  final_answer: z.string().describe("La respuesta final a la ecuación (por ejemplo, x = -3.75)."),
});

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [
    { role: "system", content: "Eres un tutor de matemáticas. Explica paso a paso." },
    { role: "user", content: "Resuelve 8x + 7 = -23" },
  ],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

const result = response.output_parsed;
console.log(result.final_answer);
for (const step of result.steps) {
  console.log(step.explanation, "->", step.output);
}

Especificación directa del JSON Schema

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    { role: "system", content: "Eres un tutor de matemáticas." },
    { role: "user", content: "Resuelve 8x + 7 = -23" },
  ],
  text: {
    format: {
      type: "json_schema",
      name: "math_response",
      strict: true,
      schema: {
        type: "object",
        description: "Una respuesta que muestra la solución paso a paso de una ecuación.",
        properties: {
          steps: {
            type: "array",
            description: "Una lista de pasos para la solución.",
            items: {
              type: "object",
              properties: {
                explanation: {
                  type: "string",
                  description: "Explicación de lo que se está haciendo en este paso de cálculo.",
                },
                output: {
                  type: "string",
                  description: "El resultado del cálculo para este paso (fórmula o valor numérico).",
                },
              },
              required: ["explanation", "output"],
              additionalProperties: false,
            },
          },
          final_answer: {
            type: "string",
            description: "La respuesta final a la ecuación (por ejemplo, x = -3.75).",
          },
        },
        required: ["steps", "final_answer"],
        additionalProperties: false,
      },
    },
  },
});

Nota: El campo correcto en la Responses API es text.format. La clave antigua response_format está deprecada en la Responses API (Fuente: OpenAI Developer Community).

3.5 Structured Outputs en Function Calling

Para aplicar Structured Outputs a una llamada de herramienta, añade strict: true a la definición de función.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Dime la fecha de entrega del pedido #12345",
  tools: [
    {
      type: "function",
      name: "get_delivery_date",
      description: "Obtener la fecha de entrega programada para un pedido.",
      strict: true,
      parameters: {
        type: "object",
        properties: {
          order_id: { type: "string" },
        },
        required: ["order_id"],
        additionalProperties: false,
      },
    },
  ],
});

Restricción: Al usar Structured Outputs para Function Calling, parallel_tool_calls debe establecerse a false.

3.6 Qué garantiza Structured Outputs (y qué no)

Ejemplo de manejo de refusal:

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [/* ... */],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

if (response.output[0].content[0].type === "refusal") {
  console.log("El modelo rechazó:", response.output[0].content[0].refusal);
} else {
  const result = response.output_parsed;
}

3.7 Restricciones del esquema en modo strict

En modo strict: true, algunas características de JSON Schema están restringidas (Fuente: Guía de Structured Outputs).

• additionalProperties: false es requerido.
• Todas las propiedades deben incluirse en el array required.
• El uso directo de anyOf en el objeto raíz no está permitido.
• Se aplican restricciones a combinaciones como oneOf, anyOf, etc.

Para evitar discrepancias entre esquemas y definiciones de tipos, OpenAI recomienda oficialmente y con firmeza usar el SDK con soporte nativo de Zod.

4. Realtime API

La Realtime API, que alcanzó Disponibilidad General (GA) en 2025, es una API especializada para streaming de voz y texto bidireccional de baja latencia vía WebRTC, WebSocket o SIP. Está diseñada para casos de uso de interacción en tiempo real como agentes de voz conectados directamente desde un navegador o integración con sistemas de telefonía (PBX), distinguiéndose claramente en su uso de la Responses API. Para más detalles, consulta la Guía Oficial de la Realtime API.

5. Streaming

La Responses API soporta streaming en formato Server-Sent Events (SSE), permitiéndote recibir respuestas largas de forma incremental.

const stream = await client.responses.stream({
  model: "gpt-4o",
  input: "Cuéntame en detalle sobre el inicio del universo.",
});

for await (const event of stream) {
  if (
    event.type === "response.output_text.delta" &&
    event.delta
  ) {
    process.stdout.write(event.delta);
  }
}

Structured Outputs también puede combinarse con streaming, en cuyo caso se devuelve un JSON completo que cumple el esquema al final.

6. Cabeceras de respuesta HTTP

Las respuestas de la API incluyen cabeceras útiles para depuración y monitoreo de límites de tasa.

Si quieres especificar un ID de solicitud desde el lado del cliente, añade la cabecera X-Client-Request-Id.

7. Límites de tasa

Los límites de tasa se aplican por Organización y Proyecto (no por usuario).

• RPM (Solicitudes Por Minuto): Número de solicitudes por minuto.
• TPM (Tokens Por Minuto): Número de tokens por minuto.

Los niveles de uso se actualizan automáticamente según los pagos acumulados y el historial de uso. Si se devuelve 429 Too Many Requests, se recomienda reintentar con backoff exponencial (Fuente: Guía de Límites de Tasa).

import retry from "async-retry";

async function callApiWithBackoff(params) {
  return retry(
    async () => {
      return await client.responses.create(params);
    },
    {
      retries: 6,
      minTimeout: 1000,
      maxTimeout: 60000,
      randomize: true,
    }
  );
}

8. Estabilidad de versiones y fijación de modelos

Los alias como gpt-4o se actualizan periódicamente a nuevos snapshots, lo que puede cambiar la salida incluso para el mismo prompt. En producción, se recomienda fijar un nombre de snapshot como gpt-4o-2024-08-06 y siempre realizar evaluación (eval) al actualizar.

Resumen

Enlaces útiles

• Guía de Migración a Responses API — Guía de Migración Oficial.
• Guía de Structured Outputs — Guía Oficial de Structured Outputs.
• Introducing Structured Outputs in the API — Blog de lanzamiento oficial.
• Guía de Realtime API — Detalles sobre voz y texto bidireccional en tiempo real.
• Guía de Límites de Tasa — Detalles sobre límites de tasa.
• OpenAI Changelog — Historial de actualizaciones de la API.