Structured Outputs

Use response_format: { "type": "json_object" } for most structured outputs in GonkaGate chat completions. Switch to json_schema only when your client depends on a stricter response contract and the selected model/provider pair supports it.

Quick start

Set response_format to json_object, tell the model to return JSON only, then parse choices[0].message.content in your app.

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
  }'

Expected client value after parsing:

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

In the API response, choices[0].message.content is still a string. Parse it in your client before validation.

Choose json_object or json_schema

• Parseable JSON and client-side validation: use json_object.
• Required fields, enums, nested objects, or additionalProperties: false: use json_schema.
• Extra hardening for non-stream structured responses: add response-healing after response_format is already correct.
• The model should call your backend or another external system: use Tool Calling instead of structured outputs.

Switch to json_schema only when the contract matters

Use json_schema for required fields, enums, nested objects, and additionalProperties: false. Stay with json_object when parseable JSON plus client-side validation is enough.

Replace the response_format field in the request above with:

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

If strict schema mode is not supported by the selected model/provider pair, fall back to json_object and validate after parsing.

Validate model output in your client

Treat model output as untrusted input, even when it parses successfully.

from pydantic import BaseModel

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

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

Troubleshooting structured outputs

See also

• Response Healing for extra hardening on non-stream structured responses after response_format is already correct.
• Tool Calling when the model should request work from your backend or another external system.
• Chat Completion Parameters when you need the field-level response_format contract.