Endpoint

Output strutturati

Forza il modello a restituire JSON valido conforme a uno JSON Schema con response_format, con parametri, esempio di risposta e supporto dei modelli.

Provalo nel playground

Gli output strutturati fanno restituire al modello un JSON conforme a uno JSON Schema che fornisci tu. Usali per l'estrazione di dati, la classificazione e qualsiasi risposta che il tuo codice analizza. Imposta response_format su Chat completions (o text.format su Responses).

Parametri della richiesta

Parametro	Tipo	Descrizione
`response_format.type`	string	`"json_schema"` per un output vincolato a uno schema. `"json_object"` per la modalità JSON libera.
`response_format.json_schema.name`	string	Un nome per lo schema.
`response_format.json_schema.strict`	boolean	`true` impone lo schema esattamente, dove il provider lo supporta.
`response_format.json_schema.schema`	object	Uno JSON Schema. Con `strict`, usa `additionalProperties: false` ed elenca ogni proprietà in `required`.

{
  "model": "openai/gpt-5-mini",
  "messages": [{ "role": "user", "content": "Extract: Ada Lovelace, born 1815 in London." }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "born": { "type": "integer" },
          "city": { "type": "string" }
        },
        "required": ["name", "born", "city"],
        "additionalProperties": false
      }
    }
  }
}

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const result = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Extract the city and country from: \"I live in Lisbon, Portugal.\""
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "place",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          }
        },
        "required": [
          "city",
          "country"
        ],
        "additionalProperties": false
      }
    }
  }
});
console.log(JSON.parse(result.choices[0].message.content));

Risposta

Il JSON arriva come stringa in message.content:

{
  "id": "gen-1760000000-json1",
  "model": "openai/gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "{\"name\":\"Ada Lovelace\",\"born\":1815,\"city\":\"London\"}" }
    }
  ],
  "usage": { "prompt_tokens": 71, "completion_tokens": 18, "total_tokens": 89, "cost": 0.0000538 }
}

Gli helper degli SDK funzionano come al solito, ad esempio client.chat.completions.parse(...) con Zod in Node o Pydantic in Python.

Supporto dei modelli

Per trovare i modelli che lo supportano, controlla in supported_parameters di Modelli la presenza di structured_outputs o response_format.
Per assicurarti che la richiesta vada solo a provider che rispettano lo schema, aggiungi provider: { "require_parameters": true }.
I modelli senza supporto nativo possono comunque produrre JSON se lo chiedi nel prompt, ma l'output non è garantito. Validalo sempre.
Se finish_reason è "length", il JSON è troncato. Aumenta max_tokens.

Errori

Uno schema non valido di solito restituisce un 400 dell'upstream con il messaggio del provider. Gli altri errori sono gli stessi di Chat completions. Vedi Errori.