Structured Outputs

OpenRouter supports structured outputs for compatible models, ensuring responses follow a specific JSON Schema format. This feature is particularly useful when you need consistent, well-formatted responses that can be reliably parsed by your application.

Overview

Structured outputs allow you to:

• Enforce specific JSON Schema validation on model responses
• Get consistent, type-safe outputs
• Avoid parsing errors and hallucinated fields
• Simplify response handling in your application

Using Structured Outputs

To use structured outputs, include a response_format parameter in your request, with type set to json_schema and the json_schema object containing your schema:

The model will respond with a JSON object that strictly follows your schema:

Model Support

Structured outputs are supported by select models.

You can find a list of models that support structured outputs on the models page.

• OpenAI models (GPT-4o and later versions) Docs
• Google Gemini models Docs
• Anthropic models (Sonnet 4.5 and Opus 4.1) Docs
• Most open-source models
• All Fireworks provided models Docs

To ensure your chosen model supports structured outputs:

1. Check the model’s supported parameters on the models page
2. Set require_parameters: true in your provider preferences (see Provider Routing)
3. Include response_format and set type: json_schema in the required parameters

Best Practices

1. Include descriptions: Add clear descriptions to your schema properties to guide the model

2. Use strict mode: Always set strict: true to ensure the model follows your schema exactly

Example Implementation

Here’s a complete example using the Fetch API:

Streaming with Structured Outputs

Structured outputs are also supported with streaming responses. The model will stream valid partial JSON that, when complete, forms a valid response matching your schema.

To enable streaming with structured outputs, simply add stream: true to your request:

Error Handling

When using structured outputs, you may encounter these scenarios:

1. Model doesn’t support structured outputs: The request will fail with an error indicating lack of support
2. Invalid schema: The model will return an error if your JSON Schema is invalid

Response Healing

For non-streaming requests using response_format with type: "json_schema", you can enable the Response Healing plugin to reduce the risk of invalid JSON when models return imperfect formatting. Learn more in the Response Healing documentation.