How to beginner · 3 min read

How to return JSON from OpenAI API

Q: How to return JSON from OpenAI API

Use the OpenAI Python SDK to call client.chat.completions.create with your prompt requesting JSON output. Parse the returned response.choices[0].message.content string as JSON using Python's json.loads() to convert it into a dictionary.

Quick answer

Use the OpenAI Python SDK to call client.chat.completions.create with your prompt requesting JSON output. Parse the returned response.choices[0].message.content string as JSON using Python's json.loads() to convert it into a dictionary.

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

This example sends a prompt asking the model to respond with JSON, then parses the response string into a Python dictionary.

python

import os
import json
from openai import OpenAI

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

prompt = "Provide a JSON object with keys 'name' and 'age' representing a person."

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": prompt}]
)

json_text = response.choices[0].message.content

try:
    data = json.loads(json_text)
    print("Parsed JSON:", data)
except json.JSONDecodeError:
    print("Failed to parse JSON. Raw response:", json_text)

output

Parsed JSON: {'name': 'John Doe', 'age': 30}

Common variations

Use different models like gpt-4o-mini for faster, cheaper responses.
Request JSON with explicit instructions or JSON schema in the prompt for better accuracy.
Use async calls with asyncio and await for concurrency.

python

import asyncio
import os
import json
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    prompt = "Return a JSON object with 'city' and 'population'."
    response = await client.chat.completions.acreate(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )
    json_text = response.choices[0].message.content
    try:
        data = json.loads(json_text)
        print("Parsed JSON:", data)
    except json.JSONDecodeError:
        print("Failed to parse JSON. Raw response:", json_text)

asyncio.run(main())

output

Parsed JSON: {'city': 'San Francisco', 'population': 883305}

Troubleshooting

If JSON parsing fails, ensure your prompt explicitly asks for JSON only.
Use delimiters like triple backticks ```json ... ``` in the prompt to help the model format output correctly.
Validate the JSON string before parsing to handle partial or malformed responses.

✅

Key Takeaways

Always parse the model's text response with json.loads() to convert JSON strings into Python objects.
Explicitly instruct the model to respond with JSON and consider using code block delimiters for better formatting.
Use the latest OpenAI SDK v1+ with client.chat.completions.create for stable and supported API calls.

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

Verify ↗