Uç noktalar

Structured outputs

response_format ile modelin sağladığınız JSON Schema'ya uyan JSON döndürmesini sağlayın; strict modu, model desteği ve doğrulama ipuçları.

Playground’da dene

Structured outputs, modelin sağladığınız bir JSON Schema'ya uyan JSON döndürmesini sağlar. Veri çıkarma, sınıflandırma ve kodunuzun ayrıştırdığı her yanıt için kullanın. Chat completions üzerinde response_format (veya Responses üzerinde text.format) ayarlayın.

İstek parametreleri

Parametre	Tür	Açıklama
`response_format.type`	string	Şemayla kısıtlı çıktı için `"json_schema"`. Serbest biçimli JSON modu için `"json_object"`.
`response_format.json_schema.name`	string	Şema için bir ad.
`response_format.json_schema.strict`	boolean	`true`, sağlayıcının desteklediği yerlerde şemayı tam olarak uygular.
`response_format.json_schema.schema`	object	Bir JSON Schema. `strict` ile `additionalProperties: false` kullanın ve her özelliği `required` içinde listeleyin.

{
  "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));

Yanıt

JSON, message.content içinde bir dize olarak gelir:

{
  "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 }
}

SDK yardımcıları her zamanki gibi çalışır; örneğin Node'da Zod veya Python'da Pydantic ile client.chat.completions.parse(...).

Model desteği

Bunu destekleyen modelleri bulmak için Modeller içindeki supported_parameters alanında structured_outputs veya response_format arayın.
İsteğin yalnızca şemaya uyan sağlayıcılara gitmesini sağlamak için provider: { "require_parameters": true } ekleyin.
Yerel desteği olmayan modeller, prompt'ta istenirse yine de JSON üretebilir, ancak çıktı garanti edilmez. Her zaman doğrulayın.
finish_reason değeri "length" ise JSON kesilmiştir. max_tokens değerini artırın.

Hatalar

Geçersiz bir şema genellikle sağlayıcının mesajıyla bir 400 döndürür. Diğer hatalar Chat completions ile aynıdır. Bkz. Hatalar.