Using Structured Outputs

Note: Forcing a structured output schema automatically disables background tool usage (like web search) for that specific request.

Using a Standard JSON Dictionary#

You can define your schema using a standard JSON dictionary. This dictionary can be passed using the “text” parameter. Follow the examples below to get started.

from openai import OpenAI

client = OpenAI(
    api_key="<your_api_key>",
    base_url="https://api.eugpt.ai/v1",
)

response = client.responses.create(
    model="auto",
    input="John Doe is 34 years old and lives in New York.",
    stream=False,
    text={
        "format": {
            "type": "json_schema",
            "name": "PersonExtraction",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

# Returns the raw JSON string
print(response.output_text)

Tip: Setting "additionalProperties": True allows the model to dynamically generate new keys in the JSON response if it discovers extra, relevant information in the input.

Tip: Use the "required" array to enforce which fields must always be returned. If an optional property is not listed here and lacks relevant data in the input, the model will simply omit that key from the final output.

Using Pydantic with a File ID#

For complex schemas, it is often easier to define your data model using Pydantic. You can generate the JSON schema dynamically using .model_json_schema() and pass it to the API.

This example also demonstrates how to extract structured data directly from an uploaded document by providing a file_id in the input array.

Tip: Setting “strict”: True forces the model to adhere to the JSON schema, while setting it to false allows the model to be more flexible.

Python#

from pydantic import BaseModel, Field
from openai import OpenAI

client = OpenAI(
    api_key="<your_api_key>",
    base_url="https://api.eugpt.ai/v1",
)

# 1. Define your extraction schema using Pydantic
class QuarterlyReportExtraction(BaseModel):
    company_name: str = Field(
        description="The name of the company issuing the report"
    )
    quarter: str = Field(
        description="The specific quarter being reported (e.g., Q1 2024)"
    )
    total_revenue: float = Field(
        description="The total revenue reported for the quarter"
    )
    key_highlights: list[str] = Field(
        description="A list of key highlights, risks, or milestones mentioned"
    )

# 2. Issue the request with the file_id and Pydantic model
structured_input = [
    {
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Extract information from this document."
            },
            {
                "type": "input_file",
                "file_id": "<your_file_id>"
            }
        ]
    }
]

# Use .parse() to automatically deserialize the JSON response
response = client.responses.parse(
    model="auto",
    input=structured_input,
    text_format=QuarterlyReportExtraction,
)

# Returns your populated Pydantic object!
extracted_data = response.output_parsed
print(extracted_data.company_name)
print(extracted_data.key_highlights)