Structured Outputs

Для большинства structured outputs в GonkaGate chat completions начинайте с response_format: { "type": "json_object" }. Переходите на json_schema только когда клиент зависит от более жёсткого контракта ответа и выбранная пара model/provider это поддерживает.

Быстрый старт

Установите response_format в json_object, явно попросите модель вернуть только JSON и затем распарсьте choices[0].message.content в приложении.

export GONKAGATE_API_KEY="gp-your-api-key"

curl https://api.gonkagate.com/v1/chat/completions \
  -H "Authorization: Bearer $GONKAGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
    "messages": [
      { "role": "system", "content": "Return JSON only. Output must be valid JSON." },
      { "role": "user", "content": "Extract: name (string) and age (integer). Text: Alice is 30." }
    ],
    "response_format": { "type": "json_object" },
    "temperature": 0
  }'

Что должно получиться после парсинга:

{ "name": "Alice", "age": 30 }

В самом API-ответе choices[0].message.content всё ещё строка. Сначала распарсьте её на клиенте, потом валидируйте.

Когда выбирать json_object или json_schema

• Парсимый JSON, а поля вы уже валидируете в приложении: используйте json_object.
• Обязательные поля, enum, вложенные объекты или additionalProperties: false: используйте json_schema.
• Дополнительное усиление для non-stream structured responses: добавьте response-healing, если response_format уже выбран правильно.
• Модель должна вызывать ваш backend или другую внешнюю систему: используйте Tool Calling вместо structured outputs.

Переходите на json_schema, только если контракт действительно важен

Используйте json_schema для обязательных полей, enum, вложенных объектов и additionalProperties: false. Оставайтесь на json_object, если вам достаточно парсимого JSON и клиентской валидации после парсинга.

Замените поле response_format из запроса выше на:

{
  "type": "json_schema",
  "json_schema": {
    "name": "person",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string", "description": "Person name" },
        "age": { "type": "integer", "description": "Age in years" }
      },
      "required": ["name", "age"],
      "additionalProperties": false
    }
  }
}

Если строгий schema mode не поддерживается выбранной парой model/provider, откатывайтесь к json_object и валидируйте результат после парсинга.

Как валидировать ответ модели на клиенте

Считайте вывод модели недоверенными данными, даже если JSON уже успешно распарсился.

Python (Pydantic)

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

person = Person.model_validate_json(response.choices[0].message.content)
print(person)

TypeScript (Zod)

import { z } from "zod";

const PersonSchema = z.object({
  name: z.string(),
  age: z.number().int()
});

const content = response.choices[0]?.message?.content ?? "{}";
const person = PersonSchema.parse(JSON.parse(content));
console.log(person);

Частые проблемы со structured outputs

См. также

• Response Healing, если нужен дополнительный hardening для non-stream structured responses после того, как response_format уже настроен правильно.
• Tool Calling, когда модель должна запросить работу у вашего backend или другой внешней системы.
• Параметры chat completions, когда нужен точный контракт поля response_format.