> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salida estructurada

> Pide a los modelos compatibles que devuelvan JSON válido o JSON que siga un esquema.

La salida estructurada te ayuda a usar las respuestas del modelo directamente en el software. En lugar de pedir texto libre y analizarlo después, puedes solicitar JSON o una forma estricta basada en JSON Schema.

Úsala para extracción, llenado de formularios, generación de configuraciones, decisiones de enrutamiento y cualquier flujo de trabajo donde el código posterior espere campos estables.

## Modo JSON

El modo JSON le pide al modelo que devuelva JSON válido:

```json theme={null}
{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "system", "content": "You extract information and return JSON only."},
    {"role": "user", "content": "Alice is 28 and works as an engineer. Extract name, age, and job."}
  ],
  "response_format": {
    "type": "json_object"
  }
}
```

El modo JSON garantiza JSON válido, pero no garantiza una estructura de campos específica. Describe claramente las claves esperadas en el prompt cuando uses este modo.

## Modo JSON Schema

Usa `json_schema` cuando necesites una forma más estricta:

```json theme={null}
{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "Alice is 28 and works as an engineer."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "job": {"type": "string"}
        },
        "required": ["name", "age", "job"],
        "additionalProperties": false
      }
    }
  }
}
```

Campos importantes:

* `strict: true` le pide al modelo que siga el esquema de cerca.
* `required` enumera los campos que deben estar presentes.
* `additionalProperties: false` evita campos inesperados.

## Ejemplo en Python

Reemplaza todo el valor `sk-your-api-key` en `API_KEY` con tu clave real. Para usar otro modelo, cambia `MODEL`. El ejemplo omite las variables de entorno del proxy del sistema y se conecta directamente a Moxus AI.

```python theme={null}
import json
import httpx
from openai import OpenAI

# Replace the entire value with your actual key before running.
API_KEY = "sk-your-api-key"
# Use the exact name from Model Square. This example uses gpt-5.4-mini.
MODEL = "gpt-5.4-mini"

client = OpenAI(
    api_key=API_KEY,
    base_url="https://moxus.ai/v1",
    # Connect directly to Moxus AI without reading system or terminal proxy variables.
    http_client=httpx.Client(trust_env=False, timeout=60.0),
)

response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "Alice is 28 and works as an engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "job": {"type": "string"},
                },
                "required": ["name", "age", "job"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(data["name"], data["age"], data["job"])
```

## Ejemplo en Node.js

Reemplaza todo el valor `sk-your-api-key` en `API_KEY` con tu clave real. Para usar otro modelo, cambia `MODEL`. El modelo devuelve una cadena JSON; el ejemplo la convierte en un objeto con `JSON.parse`.

```javascript theme={null}
import OpenAI from "openai";

// Replace the entire value with your actual key before running.
const API_KEY = "sk-your-api-key";
// Use the exact name from Model Square. This example uses gpt-5.4-mini.
const MODEL = "gpt-5.4-mini";

const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: "https://moxus.ai/v1",
});

const response = await client.chat.completions.create({
  model: MODEL,
  messages: [
    { role: "user", content: "Alice is 28 and works as an engineer." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          job: { type: "string" },
        },
        required: ["name", "age", "job"],
        additionalProperties: false,
      },
    },
  },
});

const content = response.choices[0].message.content;
if (!content) {
  throw new Error("The model did not return JSON content");
}

const data = JSON.parse(content);
console.log(data.name, data.age, data.job);
```

## Estructuras anidadas

Los esquemas pueden incluir arreglos, objetos anidados y enumeraciones:

```json theme={null}
{
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "status": {
      "type": "string",
      "enum": ["pending", "paid", "shipped", "done"]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "quantity": {"type": "integer"},
          "price": {"type": "number"}
        },
        "required": ["name", "quantity", "price"],
        "additionalProperties": false
      }
    }
  },
  "required": ["order_id", "status", "items"],
  "additionalProperties": false
}
```

## Salida estructurada frente a llamadas a funciones

| Función            | Salida estructurada                                 | Llamadas a funciones                       |
| ------------------ | --------------------------------------------------- | ------------------------------------------ |
| Objetivo principal | Devolver JSON predecible                            | Seleccionar y llamar herramientas externas |
| Uso típico         | Extracción, enrutamiento, configuraciones generadas | Consultas a bases de datos, acciones, API  |
| Ejecuta código     | No                                                  | Sí, en tu aplicación                       |

## Notas

* Prefiere JSON Schema para flujos de trabajo de producción que requieren campos estables.
* Agrega descripciones de campos cuando el esquema sea complejo.
* Aun así, valida y maneja errores de análisis en tu aplicación.
* El soporte de esquemas estrictos depende del modelo seleccionado.

## Próximos pasos

* [Modelos de razonamiento](/es/guide/reasoning)
* [Llamadas a funciones](/es/guide/function-calling)