How to beginner · 3 min read

How to use structured outputs in OpenAI API

Q: How to use structured outputs in OpenAI API

Use the OpenAI API's functions parameter to define structured output schemas and request the model to respond in JSON or other structured formats. Parse the response.choices[0].message.function_call.arguments to extract the structured data reliably.

Quick answer

Use the OpenAI API's functions parameter to define structured output schemas and request the model to respond in JSON or other structured formats. Parse the response.choices[0].message.function_call.arguments to extract the structured data reliably.

PREREQUISITES

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

Setup

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

bash

pip install openai>=1.0

Step by step

Define a function schema to specify the structured output format, then call the chat.completions.create method with the functions parameter. Extract the structured JSON output from the function_call.arguments field.

python

import os
from openai import OpenAI

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

functions = [
    {
        "name": "get_user_info",
        "description": "Extract user information in a structured format.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "The user's full name."},
                "age": {"type": "integer", "description": "The user's age."},
                "email": {"type": "string", "description": "The user's email address."}
            },
            "required": ["name", "age", "email"]
        }
    }
]

messages = [
    {"role": "user", "content": "Please provide my name, age, and email in JSON format."}
]

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

structured_output = response.choices[0].message.function_call.arguments
print("Structured output (JSON string):", structured_output)

# To parse the JSON string into a Python dict:
import json
parsed_output = json.loads(structured_output)
print("Parsed output:", parsed_output)

output

Structured output (JSON string): {"name": "John Doe", "age": 30, "email": "john.doe@example.com"}
Parsed output: {'name': 'John Doe', 'age': 30, 'email': 'john.doe@example.com'}

Common variations

Use function_call="auto" to let the model decide when to call the function.
Define multiple functions in the functions array for different structured outputs.
Use other structured formats like XML or CSV by instructing the model in the prompt, but JSON with functions is recommended for reliability.
Use async calls with asyncio for concurrency.

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 JSON with product name and price."}],
        functions=[
            {
                "name": "get_product_info",
                "description": "Returns product details.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "product_name": {"type": "string"},
                        "price": {"type": "number"}
                    },
                    "required": ["product_name", "price"]
                }
            }
        ],
        function_call="auto"
    )
    print(response.choices[0].message.function_call.arguments)

asyncio.run(main())

output

{"product_name": "Wireless Mouse", "price": 29.99}

Troubleshooting

If the model returns text instead of structured JSON, ensure you use the functions parameter and specify function_call.
Validate the JSON string with json.loads() to catch formatting errors.
If the output is incomplete, increase max_tokens or simplify the schema.
Check your API key and environment variable if you get authentication errors.

✅

Key Takeaways

Use the functions parameter to define structured output schemas for reliable JSON responses.
Extract structured data from response.choices[0].message.function_call.arguments and parse it with json.loads().
Force or auto-select function calls with the function_call parameter to control output format.
Async calls are supported via acreate for scalable applications.
Validate and troubleshoot by checking JSON formatting and API key setup.

Verified 2026-04 · gpt-4o

Verify ↗