Structured Outputs
Get reliable, schema-validated JSON responses from AI models
What are Structured Outputs?
Structured Outputs ensure that AI models return responses in a specific format, typically JSON, that conforms to your predefined schema. This eliminates parsing errors and makes AI responses directly usable in your applications.
100% Reliable
Guaranteed valid JSON that matches your schema
Type Safety
Define schemas with types, constraints, and validation
Direct Integration
Use responses directly without parsing or validation
Basic Usage
JSON Mode
The simplest way to get JSON output is using JSON mode:
from openai import OpenAI
client = OpenAI(
base_url="https://api.parrotrouter.com/v1",
api_key="your-api-key"
)
response = client.chat.completions.create(
model="gpt-4-turbo-preview",
messages=[
{"role": "system", "content": "Output JSON only"},
{"role": "user", "content": "List 3 programming languages with their use cases"}
],
response_format={"type": "json_object"}
)
# Response will be valid JSON
import json
data = json.loads(response.choices[0].message.content)
print(data)Schema Validation
For more control, define a schema that the model must follow:
response = client.chat.completions.create(
model="gpt-4-turbo-preview",
messages=[
{"role": "user", "content": "Extract product information from: iPhone 15 Pro, $999, 256GB storage, Titanium design"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "product_info",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"storage": {"type": "string"},
"features": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "price"]
}
}
}
)
# Response guaranteed to match schema
product = json.loads(response.choices[0].message.content)
print(f"Product: {product['name']} - $" + str(product['price']))Use Cases
Data Extraction
Extract structured data from unstructured text like emails, documents, or web pages.
# Extract meeting details from email
response = client.chat.completions.create(
model="gpt-4-turbo-preview",
messages=[
{"role": "user", "content": "Extract meeting details from: Let's meet tomorrow at 3pm in Conference Room A to discuss the Q4 budget. Please bring the financial reports."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "meeting_details",
"schema": {
"type": "object",
"properties": {
"date": {"type": "string"},
"time": {"type": "string"},
"location": {"type": "string"},
"topic": {"type": "string"},
"action_items": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["date", "time", "location", "topic"]
}
}
}
)API Responses
Generate API-ready responses for your applications.
# Generate user profile data
response = client.chat.completions.create(
model="gpt-4-turbo-preview",
messages=[
{"role": "user", "content": "Generate a user profile for a software developer named Alex Chen"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "user_profile",
"schema": {
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"role": {"type": "string"},
"skills": {
"type": "array",
"items": {"type": "string"}
},
"experience_years": {"type": "integer"},
"contact": {
"type": "object",
"properties": {
"email": {"type": "string"},
"linkedin": {"type": "string"}
}
}
},
"required": ["id", "name", "role", "skills"]
}
}
}
)Form Generation
Dynamically generate form configurations and validation rules.
# Generate form configuration
response = client.chat.completions.create(
model="gpt-4-turbo-preview",
messages=[
{"role": "user", "content": "Create a contact form for a dental clinic"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "form_config",
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"type": {"type": "string"},
"label": {"type": "string"},
"required": {"type": "boolean"},
"validation": {
"type": "object",
"properties": {
"pattern": {"type": "string"},
"message": {"type": "string"}
}
}
}
}
}
}
}
}
}
)Supported Models
Structured outputs are supported by these models:
GPT-4 Turbo
Full schema support
GPT-3.5 Turbo
JSON mode only
Claude 3 Models
Via prompt engineering
Gemini Pro
Via prompt engineering
Best Practices
- 1.Keep Schemas Simple
Start with basic schemas and add complexity as needed
- 2.Use Descriptive Names
Clear property names help the model understand what to generate
- 3.Provide Examples
Include example values in your prompts for better results
- 4.Validate Critical Data
Always validate business-critical fields on your backend