Structured Outputs

Get reliable, machine-parseable JSON from the GonkaGate API.

Overview

Structured outputs turn model responses into data you can validate, store, and use in code. GonkaGate is OpenAI-compatible, so you use the same request shape and SDKs.

Two ways to get JSON

• JSON mode: guarantees valid JSON, but does not enforce a schema.
• JSON Schema: asks the model to match your schema. When the model/provider supports strict schema mode, output is schema-compliant.

JSON mode (json_object)

Use JSON mode when you need valid JSON quickly and can validate it on your side.

Request example

Set response_format to json_object.

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

See parameters in the Chat Completions API reference .

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.gonkagate.com/v1",
    api_key="gp-your-api-key"
)

response = client.chat.completions.create(
    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
)

data = json.loads(response.choices[0].message.content)
print(data)

JSON Schema structured outputs (json_schema)

Use JSON Schema when you want a specific shape (types, required fields, enums) and fewer parsing edge cases.

Request example

Provide a JSON Schema and set strict=true when supported.

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    { "role": "system", "content": "Return JSON only." },
    { "role": "user", "content": "Extract person fields from: Alice is 30." }
  ],
  "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
      }
    }
  },
  "temperature": 0
}

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gonkagate.com/v1",
    api_key="gp-your-api-key"
)

response = client.chat.completions.create(
    model="qwen/qwen3-235b-a22b-instruct-2507-fp8",
    messages=[
        {"role": "system", "content": "Return JSON only."},
        {"role": "user", "content": "Extract person fields from: Alice is 30."}
    ],
    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
            }
        }
    },
    temperature=0
)

print(response.choices[0].message.content)

Parsing & validation

Even with JSON mode, validate the parsed object before using it. Treat model output as untrusted input.

Recommended pattern

• Parse JSON (handle errors).
• Validate against a schema (Pydantic/Zod).
• On failure, retry with a repair prompt or switch to a stricter mode.

from pydantic import BaseModel

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

# response.choices[0].message.content should be a JSON string
person = Person.model_validate_json(response.choices[0].message.content)
print(person)

Streaming considerations

Structured JSON often arrives incomplete while streaming. Buffer tokens and parse only after the final chunk.

let full = "";

for await (const chunk of stream) {
  const token = chunk.choices[0]?.delta?.content ?? "";
  full += token;
}

// Parse only after stream ends
const data = JSON.parse(full);

Best practices

Make structured outputs reliable in production:

• Keep schemas small and task-specific.
• Set additionalProperties=false to avoid surprise fields (schema mode).
• Use enums for bounded values (status, category, etc.).
• Add field descriptions to reduce ambiguity.
• Use lower temperature for deterministic extraction.
• Have a fallback path: JSON mode + validation + retry.

See parameters in the Chat Completions API reference .

Model compatibility

JSON mode and JSON Schema support depend on the underlying model/provider. Verify before production.

Check the Models page or query GET /models to confirm current capabilities.

Troubleshooting

Common issues and fixes:

• Output is not JSON — tighten system instructions and ensure response_format is set.
• JSON.parse fails — retry with a repair prompt and validate before use.
• Schema mismatch — simplify schema, set required fields carefully, or fall back to JSON mode.
• Truncated JSON — increase max_tokens or reduce the required output size.