Structured Outputs guarantee the model returns JSON that conforms to a JSON Schema you provide. Pass a response_format with type: "json_schema" and the output is constrained to your schema — no regex cleanup, no "please return valid JSON" prompts.
Chat Completions
from openai import OpenAIfrom pydantic import BaseModel
client = OpenAI( base_url="https://spro.hridaai.com/v1", api_key="YOUR_SPRO_API_KEY",)
class MovieReview(BaseModel): title: str rating: float summary: str recommend: bool
response = client.chat.completions.create( model="gpt-oss-20b", messages=[ {"role": "user", "content": "Review the movie Inception."} ], response_format={ "type": "json_schema", "json_schema": { "name": "movie_review", "strict": True, "schema": { "type": "object", "properties": { "title": {"type": "string"}, "rating": {"type": "number"}, "summary": {"type": "string"}, "recommend": {"type": "boolean"}, }, "required": ["title", "rating", "summary", "recommend"], "additionalProperties": False, }, }, },)
print(response.choices[0].message.content)The response is always valid JSON matching your schema — parse it directly:
{ "title": "Inception", "rating": 8.8, "summary": "A heist movie set inside dreams, blending spectacle with a surprisingly emotional core.", "recommend": true}Responses API
On the Responses API, pass the schema as text.format:
response = client.responses.create( model="gpt-oss-20b", input="Extract: 'Order #1234 for Alice shipped on Tuesday to Berlin.'", text={ "format": { "type": "json_schema", "name": "order", "strict": True, "schema": { "type": "object", "properties": { "order_id": {"type": "string"}, "customer": {"type": "string"}, "destination": {"type": "string"}, }, "required": ["order_id", "customer", "destination"], "additionalProperties": False, }, } },)
print(response.output_text)Notes
- Works across all providers in the catalog — Spro normalizes the format so the same code works whether the model is served by OpenAI, Z.AI, or anyone else.
- With
strict: true, generation is constrained to the schema at the decoding level — not just prompted to comply. - Not every model supports every schema feature (e.g. deeply nested unions); keep schemas simple and flat where you can.
