How to Intermediate · 4 min read

How to use structured outputs with OpenAI API

Q: How to use structured outputs with OpenAI API

Use the OpenAI API's functions parameter to define structured output schemas and receive responses in a predictable JSON format. This enables you to parse and validate AI outputs reliably by specifying JSON schema for the expected structure.

Quick answer

Use the OpenAI API's functions parameter to define structured output schemas and receive responses in a predictable JSON format. This enables you to parse and validate AI outputs reliably by specifying JSON schema for the expected structure.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

bash

pip install openai>=1.0

Step by step

Define a JSON schema for the structured output you want, then call client.chat.completions.create with the functions parameter. The model will return a function_call with arguments matching your schema.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Define a function schema for structured output
functions = [
    {
        "name": "get_weather",
        "description": "Get the current weather information",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"},
                "temperature": {"type": "number", "description": "Temperature in Celsius"},
                "condition": {"type": "string", "description": "Weather condition description"}
            },
            "required": ["location", "temperature", "condition"]
        }
    }
]

messages = [
    {"role": "user", "content": "What's the weather like in New York?"}
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    functions=functions,
    function_call={"name": "get_weather"}  # force calling the function
)

function_call = response.choices[0].message.function_call
import json

# Parse the JSON arguments from the function call
structured_output = json.loads(function_call.arguments)
print(structured_output)

output

{'location': 'New York', 'temperature': 22.5, 'condition': 'Partly cloudy'}

Common variations

Use function_call="auto" to let the model decide when to call functions.
Use different models like gpt-4o-mini for faster, cheaper calls.
Implement async calls with asyncio and await in Python.
Parse nested or complex JSON schemas for richer structured data.

python

import asyncio
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def main():
    response = await client.chat.completions.acreate(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Give me a summary with structured output."}],
        functions=functions,
        function_call="auto"
    )
    print(response.choices[0].message.function_call.arguments)

asyncio.run(main())

output

{"location": "San Francisco", "temperature": 18.3, "condition": "Sunny"}

Troubleshooting

If you get a KeyError on function_call, ensure your functions parameter is correctly defined and the model supports function calling.
Malformed JSON in function_call.arguments can be fixed by validating your schema or using try-except when parsing JSON.
Check your API key and environment variables if authentication errors occur.

✅

Key Takeaways

Use the functions parameter to define JSON schemas for structured outputs.
Parse function_call.arguments as JSON to extract structured data reliably.
You can force or auto-enable function calls to control when structured outputs are returned.

Verified 2026-04 · gpt-4o, gpt-4o-mini

Verify ↗