How to beginner · 3 min read

How to use response_format in OpenAI API

Q: How to use response_format in OpenAI API

Use the response_format parameter in the OpenAI API chat completions call to specify the output format such as json, text, or verbose_json. Pass it as a keyword argument in client.chat.completions.create() to receive structured responses directly from the model.

Quick answer

Use the response_format parameter in the OpenAI API chat completions call to specify the output format such as json, text, or verbose_json. Pass it as a keyword argument in client.chat.completions.create() to receive structured responses directly from the model.

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.

Install SDK: pip install openai
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai

Step by step

This example shows how to request a JSON-formatted response from the OpenAI API using the response_format parameter.

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 name and age."}],
    response_format="json"
)

print(response.choices[0].message.content)

output

{
  "name": "Alice",
  "age": 30
}

Common variations

You can use different response_format values depending on your needs:

text (default): plain text output.
json: structured JSON output parsed by the client.
verbose_json: JSON with additional metadata.

Example with verbose_json:

python

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Return a verbose JSON with details."}],
    response_format="verbose_json"
)

print(response.choices[0].message.content)

output

{
  "object": "chat.completion",
  "created": 1680000000,
  "model": "gpt-4o",
  "choices": [...],
  "usage": {...}
}

Troubleshooting

If you receive unexpected output or parsing errors, verify that the model supports the requested response_format. Not all models support all formats. Also, ensure your client code correctly handles the returned format.

If the response is not valid JSON when response_format="json" is used, try adding explicit instructions in your prompt to output valid JSON.

✅

Key Takeaways

Use the response_format parameter to get structured outputs like JSON from the OpenAI API.
Pass response_format directly in client.chat.completions.create() calls with the Python SDK.
Not all models support every response_format; check model docs if issues arise.

Verified 2026-04 · gpt-4o

Verify ↗