How to beginner · 3 min read

How to parse OpenAI structured output response

Q: How to parse OpenAI structured output response

Use the OpenAI SDK v1 to call chat.completions.create with a model that supports structured outputs, then access the structured data from response.choices[0].message.content. Parse this JSON or dict directly in Python for reliable extraction.

Quick answer

Use the OpenAI SDK v1 to call chat.completions.create with a model that supports structured outputs, then access the structured data from response.choices[0].message.content. Parse this JSON or dict directly in Python for reliable extraction.

PREREQUISITES

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

Setup

Install the official openai Python package version 1.0 or higher and set your API key as an environment variable.

Run pip install openai>=1.0
Set environment variable OPENAI_API_KEY with your API key

bash

pip install openai>=1.0

Step by step

Call the OpenAI chat.completions.create method with a model that supports structured outputs (e.g., gpt-4o). The response contains a content field inside the first choice's message with the structured output as JSON. Parse this field as a Python dict to access structured data.

python

import os
import json
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Generate a JSON object with name and age."}],
    # Enable structured output if needed (depends on model and API version)
    # For example, you might specify a function or schema here if supported
)

# Access the content from the response
content_str = response.choices[0].message.content

# Parse JSON string to dict
structured_data = json.loads(content_str)

print("Parsed structured output:", structured_data)

output

Parsed structured output: {'name': 'Alice', 'age': 30}

Common variations

You can parse structured outputs asynchronously or with different models like gpt-4o-mini. Some models require specifying a functions parameter or response_format to get structured JSON. Always check the model documentation for structured output support.

python

import asyncio
import os
import json
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-mini",
        messages=[{"role": "user", "content": "Return a JSON with city and population."}]
    )
    content_str = response.choices[0].message.content
    structured_data = json.loads(content_str)
    print("Async parsed structured output:", structured_data)

asyncio.run(main())

output

Async parsed structured output: {'city': 'New York', 'population': 8419000}

Troubleshooting

If content is missing or not JSON, verify your model supports structured outputs and you requested it properly.
If you get a string instead of a dict, parse it with json.loads().
Check for API errors or rate limits if the response is empty or malformed.

✅

Key Takeaways

Use response.choices[0].message.content to access the structured output as a JSON string.
Parse the JSON string with json.loads() to convert it to a Python dict.
Ensure your model supports structured outputs and you request them correctly in the API call.
Use async calls with acreate for non-blocking structured output parsing.
Check API docs for model-specific structured output features and parameters.

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

Verify ↗