Article
Decisions API vs Structured Outputs: When a Single Choice Wins
Structured Outputs enforce a JSON schema; the Decisions API selects one discrete choice. When the decision is categorical, the difference is not just speed — it is the shape of the contract.
The schema mismatch
Structured Outputs guarantee that a model response conforms to a JSON schema. That is powerful, but the contract is still generative: the model writes JSON, and the caller maps values back into business logic. For a categorical decision — escalate, refund, request more info — the schema is overhead, not safety.
What the Decisions API changes
The decision is declared up front as a list of choices, and the response is the choice itself. There is no serialization layer, no field to read, and no invalid-value state to handle. The benchmark direction is clear: a single constrained hop runs around 5x faster than a schema-enforced generation at a fraction of the token cost.
Choosing between them
- Use Structured Outputs when the answer is composite: multiple fields, structured data, generated artifacts
- Use the Decisions API when the answer is one of N labels, and the labels are known at call time
- Use neither when the task genuinely needs free text