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

# Salidas estructuradas

> Devuelve JSON predecible con los formatos de salida json_object o json_schema.

Las salidas estructuradas permiten exigir una respuesta legible por máquina en lugar de texto libre.

## Compatibilidad de endpoints

Usa las salidas estructuradas en:

* `/v1/chat/completions` con `response_format`
* `/v1/responses` con `text.format`
* `/v1/messages` puede seguir devolviendo texto JSON, pero no usa el mismo contrato de `response_format`.

## Solicitud

```bash theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "Return a JSON object with city and weather for London." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "weather_schema",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "weather": { "type": "string" }
          },
          "required": ["city", "weather"],
          "additionalProperties": false
        }
      }
    }
  }'
```

## Respuesta

```json theme={null}
{
  "id": "chatcmpl_...",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"city\":\"London\",\"weather\":\"Cloudy\"}"
      }
    }
  ]
}
```

## Notas sobre el contrato

* `response_format.type` debe ser `text`, `json_object` o `json_schema`.
* Para `json_schema`, incluye un objeto de esquema (`response_format.json_schema.schema` en solicitudes tipo chat o `text.format.schema` en solicitudes tipo Responses).
* Valida el JSON en tu servidor antes de usarlo en otros sistemas.

## Diseña tu esquema

Empieza con un objeto pequeño, marca explícitamente los campos obligatorios y usa enumeraciones para las categorías conocidas. Define `additionalProperties: false` cuando deban rechazarse las claves adicionales. Mantén sincronizados el esquema solicitado y el validador del servidor; versiónalos juntos.

## Valida el resultado

Analiza y valida el resultado completo antes de usarlo posteriormente. Este ejemplo de TypeScript usa Zod y coincide con el esquema meteorológico anterior:

```typescript theme={null}
import { z } from "zod";

const Weather = z.object({
  city: z.string(),
  weather: z.string(),
}).strict();

function parseWeather(content: string) {
  return Weather.parse(JSON.parse(content));
}
```

Gestiona rechazos, contenido ausente y respuestas truncadas antes de analizar. Si falla la validación, permite como máximo un número limitado de reintentos correctivos y después devuelve un fallo seguro. Las generaciones reintentadas pueden generar cargos adicionales. Un JSON válido no demuestra que los valores sean correctos ni autoriza una acción.

Registra los fallos de validación por modelo y versión del esquema. Vuelve a comprobar tus casos de evaluación cuando cambie cualquiera de los dos. Para recuperar JSON mal formado, consulta [reparación de respuestas](../cookbook/response-healing-for-structured-json.mdx).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.