Cómo usar salidas estructuradas de OpenAI

Al final de esta guía, podrás llamar a las salidas estructuradas de OpenAI desde tu propio código: entregarle al modelo un esquema JSON, establecer strict: true y obtener una respuesta que garantice coincidir con la forma que solicitaste. Enviarás una primera solicitud, leerás la respuesta, manejarás los casos límite y generarás colecciones de pruebas de API en Apidog que confirmen que la carga útil realmente se ajusta.

button

Lo que necesitas antes de empezar

Las salidas estructuradas restringen la generación del modelo para que la salida se ajuste a un esquema JSON que tú proporcionas. Cuando pasas un esquema con strict: true, el modelo no puede emitir un campo que lo viole. Cada clave requerida está presente, cada tipo coincide y cada valor enumerado es uno de los que listaste. Dejas de escribir código de análisis defensivo y empiezas a confiar en la carga útil.

Eso es una verdadera mejora con respecto a la alternativa. Las indicaciones de texto libre como "responder solo con JSON" funcionan hasta que dejan de hacerlo. Un desvío de razonamiento y obtienes prosa envuelta alrededor de tu objeto, o una fecha donde esperabas un número entero. Las salidas estructuradas mueven el contrato de una instrucción esperanzadora a una restricción aplicada en el momento de la decodificación.

Para seguir los pasos necesitas:

Una clave API de OpenAI establecida como OPENAI_API_KEY.
Un modelo que admita la aplicación estricta del esquema (más sobre qué modelos a continuación).
Un esquema JSON que describa la forma que deseas de vuelta.

Elige el modelo adecuado

Las salidas estructuradas están disponibles en los modelos recientes de OpenAI, comenzando con la familia GPT-4o y continuando con la serie GPT-5. La documentación de OpenAI actualmente recomienda iniciar nuevos proyectos con su último modelo insignia (gpt-5.5 en el momento de escribir esto). Los modelos más antiguos y los modelos de la era gpt-3.5, admiten el modo JSON pero no la aplicación estricta del esquema. Si dependes de strict: true, confirma que el ID del modelo específico lo admite antes de implementarlo, ya que el soporte está vinculado a las versiones del modelo y OpenAI las actualiza constantemente.

Ayuda saber qué característica estás buscando, porque OpenAI ofrece dos relacionadas que son fáciles de confundir.

El modo JSON (response_format: { "type": "json_object" }) garantiza que la salida sea JSON sintácticamente válido. Eso es todo. No conoce tus campos, tus tipos o tus claves requeridas. Todavía tienes que validar la forma tú mismo.

Las salidas estructuradas (response_format con type: "json_schema" y strict: true) garantizan que la salida sea JSON válido y que coincida con tu esquema. OpenAI describe las salidas estructuradas como la evolución del modo JSON: ambos producen JSON válido, pero solo las salidas estructuradas aplican la adherencia al esquema. Para el trabajo nuevo, las salidas estructuradas son las que quieres.

	Modo JSON	Salidas estructuradas (estrictas)
Parámetro	`response_format: {"type":"json_object"}`	`response_format` con `type: "json_schema"`, `strict: true`
JSON válido	Sí	Sí
Coincide con tu esquema	No	Sí
Campos requeridos aplicados	No	Sí
Tipos y enumeraciones aplicados	No	Sí
Todavía validas en el flujo descendente	Siempre	Recomendado (ver abajo)

Una nota sobre las API: el endpoint de Chat Completions usa response_format como se muestra arriba. La API de Responses más reciente expresa lo mismo bajo text.format con type: "json_schema". Las reglas del esquema son idénticas; solo el envoltorio difiere. Consulta la documentación actual para conocer la ruta de campo exacta en el endpoint que llamas.

Haz tu primera solicitud

Digamos que estás extrayendo un ticket de soporte en un registro tipado. Aquí tienes una solicitud de Chat Completions con un esquema estricto.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "system", "content": "Extract the ticket into the schema." },
      { "role": "user", "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary":  { "type": "string" },
            "category": { "type": "string", "enum": ["billing", "bug", "account", "other"] },
            "severity": { "type": "integer" },
            "account_id": {
              "anyOf": [ { "type": "string" }, { "type": "null" } ]
            }
          },
          "required": ["summary", "category", "severity", "account_id"],
          "additionalProperties": false
        }
      }
    }
  }'

Lee la respuesta

El modelo devuelve un mensaje cuyo content es una cadena JSON que coincide con ese esquema, por ejemplo:

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}

Observa que account_id usa anyOf con null. Así es como se modela un campo opcional, lo que nos lleva directamente a las reglas que debes seguir al escribir tus propios esquemas.

Mantente dentro del subconjunto del esquema

Las salidas estructuradas aceptan un subconjunto de JSON Schema. El subconjunto existe para que OpenAI pueda aplicar las restricciones de manera confiable y almacenar en caché el esquema compilado. Las reglas que vale la pena memorizar:

La raíz debe ser un objeto. No puedes hacer que el nivel superior sea una matriz o una cadena simple. Envuelve una lista en una propiedad de objeto.
Cada propiedad debe estar listada en required. No hay "opcional" en el sentido usual. Para hacer un campo anulable, dale anyOf con un tipo null, como en el ejemplo anterior.
additionalProperties debe ser false en cada objeto. Esto bloquea que el modelo invente claves adicionales.
Se aplican límites de tamaño. Un esquema puede contener aproximadamente 100 propiedades de objeto con hasta 5 niveles de anidamiento. Los esquemas profundamente anidados o muy extendidos son rechazados, así que aplana donde puedas.
Algunas palabras clave no se aplican. El modelo no garantiza palabras clave solo de validación como pattern, format, minLength y minimum. Si necesitas que se respete una expresión regular o un rango numérico, aún tendrás que verificarlo tú mismo después de que llegue la respuesta.
Latencia en la primera llamada. La primera solicitud con un nuevo esquema dedica tiempo a compilarlo (generalmente segundos, a veces hasta un minuto para esquemas complejos). Después de eso, se almacena en caché y es rápida.

Debido a que las palabras clave de validación no se aplican, "JSON garantizado" no significa "negocio válido garantizado". La estructura está bloqueada. Los valores internos aún merecen una prueba. Si alguna vez has modelado campos opcionales o de unión con oneOf/anyOf/allOf, el modelo mental es familiar: un esquema restringe la forma, pero tú afirmas los valores reales por separado.

Manejar rechazos y truncamientos

Hay un caso en el que la salida no coincidirá intencionalmente con tu esquema. Si el modelo rechaza una solicitud insegura, devuelve un campo refusal en el mensaje en lugar de contenido con la forma del esquema. Tu código debe bifurcarse en eso antes de analizar:

msg = response.choices[0].message
if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)

Los rechazos ahora son detectables programáticamente, lo cual es más limpio que escanear el texto en busca de una disculpa. Otras dos formas en que una respuesta puede no cumplir con el esquema: alcanzar max_tokens a mitad de un objeto (el JSON se trunca) o usar llamadas a herramientas paralelas, que las salidas estructuradas no admiten. Establece parallel_tool_calls en false cuando combines ambos.

Cómo probarlo en Apidog

El modo estricto aplica el esquema en el momento de la generación. No te exime de las pruebas. Los modelos se intercambian, los esquemas se desvían, un compañero de equipo edita el arreglo required, o una ruta de rechazo cambia. Quieres una prueba que falle ruidosamente cuando la respuesta deje de coincidir con el contrato. Ahí es donde Apidog encaja.

Un equipo discutiendo un problema de la API de OpenAI

Para ser precisos sobre la división del trabajo: el modo estricto de OpenAI es lo que produce JSON válido según el esquema. Apidog no aplica el esquema en el modelo. Lo que hace Apidog es validar la respuesta que recibiste contra el esquema que esperas, para que detectes desviaciones en CI en lugar de en producción.

Aquí está el flujo de trabajo:

Envía la solicitud. Construye la llamada a Chat Completions en Apidog con tu bloque response_format. Guárdala en una colección para que sea repetible.
Verifica la forma. Añade aserciones de respuesta en Apidog. Comprueba que category sea uno de tus valores enumerados, que severity sea un entero, que account_id sea una cadena o nulo. Apidog puede validar la respuesta contra un esquema JSON para que adjuntes el esquema exacto y hagas que la ejecución falle cuando la carga útil se desvíe.
Ejecútalo en CI. Pon la colección en tu pipeline para que cada cambio de modelo o de prompt vuelva a verificar la conformidad. Una ruptura silenciosa del esquema se convierte en una construcción fallida.
Simula el contrato. Antes de que exista la llamada real, o para probar consumidores descendentes sin gastar tokens, levanta una API simulada que devuelva respuestas de ejemplo válidas según el esquema. Tu frontend y tus pruebas se ejecutarán contra una forma estable mientras la integración se consolida.

Ese último punto es el subestimado. Puedes desarrollar y probar todo lo que consume la salida estructurada contra un mock que respeta el mismo esquema, luego intercambiarlo por la llamada en vivo a OpenAI cuando estés listo. Descarga Apidog y podrás construir la solicitud, las aserciones y el mock en un solo lugar.

Preguntas frecuentes

¿El modo JSON está obsoleto ahora que existen las salidas estructuradas? El modo JSON sigue funcionando y sigue garantizando JSON válido. Simplemente no aplica un esquema. Para código nuevo, las salidas estructuradas con strict: true son la opción más sólida. Utiliza el modo JSON simple solo en modelos que no admiten esquemas estrictos, o cuando genuinamente no tienes una forma fija.

¿La raíz de mi esquema puede ser un array? No. El nivel superior tiene que ser un objeto. Envuelve tu lista en una propiedad, como { "items": [...] }, y pon items en required. Esto confunde a mucha gente el primer día.

¿Cómo hago que un campo sea opcional? Las salidas estructuradas requieren que cada propiedad esté en required, por lo que no existe un campo opcional clásico. Modela la "ausencia" como anulable: usa anyOf con un string (o cualquier tipo) y un null. La clave siempre está presente; su valor puede ser null.

¿El modo estricto significa que puedo omitir la validación por completo? La estructura está garantizada, por lo que puedes omitir las comprobaciones de forma. Pero el modelo no aplica palabras clave como pattern, format y rangos numéricos, y los rechazos o el truncamiento aún pueden producir respuestas fuera de especificación. Una prueba de conformidad sigue siendo útil. Si eres nuevo en el formato, esta introducción a JSON Schema cubre los bloques de construcción, y puedes ejecutar la verificación en cada implementación.

¿Qué modelos debo usar? Las salidas estructuradas funcionan en GPT-4o y posteriores, incluida la serie GPT-5. La documentación de OpenAI sugiere para proyectos nuevos su modelo insignia actual. Confirma que el ID exacto del modelo admite el modo estricto antes de confiar en él, ya que el soporte sigue las versiones del modelo.

Conclusión

Ahora tienes el ciclo completo: elige un modelo que admita el modo estricto, envía una solicitud de Chat Completions con json_schema y strict: true, mantén tu esquema dentro del subconjunto compatible, bifurca en refusal y recuerda que las reglas a nivel de valor aún necesitan ser verificadas. Luego, pruébalo con un test: construye la solicitud en Apidog, verifica la respuesta contra tu esquema y simúlala para que el resto de tu pila pueda avanzar mientras la integración se establece. El modelo promete la forma. Tus pruebas demuestran que se mantuvo así.

button