Endpoints

Structured outputs

Dwing geldige JSON af die past bij een JSON Schema met response_format, voor extractie, classificatie en elk antwoord dat je code parset.

Probeer het in de playground

Structured outputs laten een model JSON teruggeven die past bij een JSON Schema dat jij aanlevert. Gebruik ze voor extractie, classificatie en elk antwoord dat je code parset. Stel response_format in op Chat completions (of text.format op Responses).

Requestparameters

Parameter	Type	Beschrijving
`response_format.type`	string	`"json_schema"` voor schema-gebonden uitvoer. `"json_object"` voor vrije JSON-modus.
`response_format.json_schema.name`	string	Een naam voor het schema.
`response_format.json_schema.strict`	boolean	`true` dwingt het schema exact af waar de provider dat ondersteunt.
`response_format.json_schema.schema`	object	Een JSON Schema. Gebruik bij `strict` `additionalProperties: false` en vermeld elke property 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));

Response

De JSON komt als string binnen 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 }
}

De SDK-helpers werken zoals gewoonlijk, bijvoorbeeld client.chat.completions.parse(...) met Zod in Node of Pydantic in Python.

Modelondersteuning

Om modellen te vinden die dit ondersteunen, controleer je supported_parameters in Modellen op structured_outputs of response_format.
Om te zorgen dat het request alleen naar providers gaat die het schema respecteren, voeg je provider: { "require_parameters": true } toe.
Modellen zonder native ondersteuning kunnen nog steeds JSON produceren als je er in de prompt om vraagt, maar de uitvoer is niet gegarandeerd. Valideer hem altijd.
Als finish_reason "length" is, is de JSON afgekapt. Verhoog max_tokens.

Fouten

Een ongeldig schema geeft meestal een upstream 400 terug met de melding van de provider. Overige fouten zijn dezelfde als bij Chat completions. Zie Fouten.