How to beginner · 3 min read

How to use json_object mode in OpenAI

Q: How to use json_object mode in OpenAI

Use the json_object mode in OpenAI by specifying it in the response_format parameter when calling chat.completions.create. This instructs the model to return a structured JSON object, enabling easier parsing and integration in your Python applications.

Quick answer

Use the json_object mode in OpenAI by specifying it in the response_format parameter when calling chat.completions.create. This instructs the model to return a structured JSON object, enabling easier parsing and integration in your Python applications.

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.

Run pip install openai to install the SDK.
Set your API key in your environment: export OPENAI_API_KEY='your_api_key_here' on Linux/macOS or setx OPENAI_API_KEY "your_api_key_here" on Windows.

bash

pip install openai

Step by step

Use the json_object mode by setting response_format="json_object" in the chat.completions.create call. This example requests a JSON object describing a book with title and author fields.

python

import os
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": "Provide a JSON object with keys 'title' and 'author' describing a famous book."}],
    response_format="json_object"
)

json_response = response.choices[0].message.content
print("JSON object response:", json_response)

output

JSON object response: {"title": "To Kill a Mockingbird", "author": "Harper Lee"}

Common variations

You can use json_object mode with different models like gpt-4o-mini or gpt-4o. For asynchronous calls, use async functions with the OpenAI SDK. Streaming is not supported with json_object mode because it requires a complete JSON object.

python

import asyncio
import os
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    response = await client.chat.completions.acreate(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Return a JSON object with 'name' and 'age' of a fictional character."}],
        response_format="json_object"
    )
    print("Async JSON response:", response.choices[0].message.content)

asyncio.run(main())

output

Async JSON response: {"name": "Alice", "age": 28}

Troubleshooting

If you receive a parsing error or invalid JSON, ensure your prompt clearly requests a JSON object and that response_format="json_object" is set. Also, verify your model supports this mode. If the response is not valid JSON, try refining the prompt to explicitly ask for JSON only.

✅

Key Takeaways

Set response_format="json_object" to get structured JSON responses from OpenAI chat completions.
Use clear prompts that explicitly request JSON objects to improve response validity.
json_object mode works with multiple OpenAI models and supports async calls but not streaming.
Always parse the returned JSON string safely in your application after receiving the response.
Check your environment variable OPENAI_API_KEY is set correctly before running code.

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

Verify ↗