Structured output
Request JSON Schema output and handle refusals, truncation, and validation failures.
Choose an output mode
Use a model and line supporting structured output when your application needs fields. JSON mode targets valid JSON; JSON Schema also defines fields and types. A prompt asking for JSON does not replace application validation.
Request and validate
Prepare Python and environment variables with the OpenAI SDK guide. This Chat Completions example uses response_format and requires support for that structure.
import json
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["IROUTER_API_KEY"], base_url="https://gateway.irouter.io/v1")
reply = client.chat.completions.create(
model=os.environ["IROUTER_MODEL"],
messages=[{"role": "user", "content": "Return the product name iRouter as label."}],
response_format={"type": "json_schema", "json_schema": {
"name": "product_label", "strict": True,
"schema": {"type": "object", "properties": {"label": {"type": "string"}},
"required": ["label"], "additionalProperties": False}
}},
)
choice = reply.choices[0]
if choice.finish_reason != "stop" or getattr(choice.message, "refusal", None):
raise ValueError("Response did not complete normally")
result = json.loads(choice.message.content or "")
if not isinstance(result, dict) or set(result) != {"label"} or not isinstance(result["label"], str):
raise ValueError("Invalid result shape")
print(result["label"])Errors and protocol differences
For unsupported parameters, inspect model capabilities instead of silently falling back to unconstrained text in production. Refusals, truncation, empty content, invalid JSON, and schema mismatches must not be accepted as valid business results.
Responses uses text.format rather than the Chat Completions top-level response_format. Support for complex schemas also varies by model.
Field reference: OpenAI structured output.