Structured Outputs

What are Structured Outputs

Structured Outputs ensure that the model's generated output completely matches the JSON Schema you define, guaranteeing deterministic output format. This is essential for application scenarios that require programmatic processing of model outputs.

Core Features

Feature	Description
Format Guarantee	Output strictly follows JSON Schema
Type Safety	Supports JSON Schema type validation
Repeatability	Same input produces same format output

Usage

Basic Syntax

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Extract the following info: name, age, occupation"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"}
                },
                "required": ["name", "age", "occupation"]
            }
        }
    }
)

JSON Schema Examples

Simple Object

{
  "type": "json_schema",
  "json_schema": {
    "name": "recipe",
    "schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "ingredients": {
          "type": "array",
          "items": {"type": "string"}
        },
        "steps": {"type": "string"}
      },
      "required": ["title", "ingredients", "steps"]
    }
  }
}

Nested Object

{
  "type": "json_schema",
  "json_schema": {
    "name": "company",
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "founded": {"type": "integer"},
        "headquarters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "country": {"type": "string"}
          }
        },
        "employees": {"type": "integer"}
      },
      "required": ["name", "headquarters"]
    }
  }
}

Array Type

{
  "type": "json_schema",
  "json_schema": {
    "name": "product_list",
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "price": {"type": "number"}
        }
      }
    }
  }
}

Complete Example

Extract Structured Data

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://ai-tokenhub.com/v1",
    api_key="your_api_key"
)

# Define output format
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "news_summary",
        "schema": {
            "type": "object",
            "properties": {
                "headline": {"type": "string"},
                "category": {
                    "type": "string",
                    "enum": ["tech", "sports", "entertainment", "finance", "international"]
                },
                "key_points": {
                    "type": "array",
                    "items": {"type": "string"}
                },
                "sentiment": {
                    "type": "string",
                    "enum": ["positive", "negative", "neutral"]
                },
                "word_count": {"type": "integer"}
            },
            "required": ["headline", "category", "key_points", "sentiment"]
        }
    }
}

# Send request
news_text = """
Apple announced the new iPhone at today's tech launch.
The new product uses the all-new A19 chip with 40% performance improvement.
Analysts believe this will help Apple maintain its competitive edge in the premium market.
"""

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": f"Analyze the following news and extract structured information:\n{news_text}"}
    ],
    response_format=response_format
)

# Parse response
result = json.loads(response.choices[0].message.content)
print(json.dumps(result, indent=2))

Example Output

{
  "headline": "Apple Releases New iPhone with A19 Chip",
  "category": "tech",
  "key_points": [
    "Apple launches new iPhone",
    "Uses A19 chip with 40% performance boost",
    "Analysts看好Apple premium market prospects"
  ],
  "sentiment": "positive",
  "word_count": 58
}

Enum Constraints

Define Enums

{
  "type": "json_schema",
  "json_schema": {
    "name": "status_report",
    "schema": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": ["pending", "in_progress", "completed", "failed"]
        },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high", "critical"]
        },
        "progress": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        }
      },
      "required": ["status", "priority"]
    }
  }
}

Best Practices

1. Clear Schema Naming

# ✅ Good naming
"json_schema": {"name": "customer_order", ...}

# ❌ Unclear naming
"json_schema": {"name": "data", ...}

2. Add Field Descriptions

{
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Customer unique identifier, format: CUST-XXXXX"
    }
  }
}

3. Use Required Fields Appropriately

# Only set truly required fields as required
"required": ["name", "email"]