Guides

Structured output

Request parseable JSON or enforce a JSON Schema on capable models.

View Markdown

Use structured output when downstream code needs machine-readable data. Check that the model advertises json_mode or structured_outputs.

JSON mode¶

{
  "model": "qwen/qwen3.8-27b",
  "messages": [{"role": "user", "content": "Return JSON with keys name and purpose for a load balancer."}],
  "response_format": {"type": "json_object"},
  "max_completion_tokens": 240
}

JSON mode guarantees parseable JSON, not a particular shape. State the desired fields in the prompt and validate the result.

JSON Schema¶

{
  "model": "qwen/qwen3.8-27b",
  "messages": [{"role": "user", "content": "Describe a circuit breaker."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "pattern",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "benefits": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["name", "benefits"],
        "additionalProperties": false
      }
    }
  },
  "max_completion_tokens": 320
}

The router validates schemas before forwarding. Unsupported models return a 400 capability error. Parse and validate output in the client even in strict mode; network truncation and terminal stream failures can still make an otherwise valid generation incomplete.

In Responses, place the format under text.format. Structured output can disable model reasoning to improve schema adherence. Streaming delivers JSON as fragments, so buffer the complete text before parsing.