How to Intermediate · 4 min read

How to classify with structured outputs

Quick answer

Use the OpenAI API's chat.completions.create method with a prompt that instructs the model to output structured JSON. Specify the expected output format in the prompt and parse the JSON response for classification results. This approach enables precise, machine-readable classification outputs.

PREREQUISITES

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

Setup

Install the openai Python package and set your API key as an environment variable for secure authentication.

bash

pip install openai>=1.0

output

Collecting openai
  Downloading openai-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: openai
Successfully installed openai-1.x.x

Step by step

Use the OpenAI chat.completions.create method with a prompt that instructs the model to classify input text and return a structured JSON output. Parse the JSON string from the response to extract classification labels.

python

import os
import json
from openai import OpenAI

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

prompt = (
    "Classify the following text into categories: Positive, Negative, or Neutral. "
    "Return the result as a JSON object with keys 'label' and 'confidence' (0-1).\n"
    "Text: \"I love using AI APIs!\""
)

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

# Extract the content
content = response.choices[0].message.content

# Parse JSON from the model's response
try:
    classification = json.loads(content)
except json.JSONDecodeError:
    classification = {"error": "Invalid JSON response", "raw": content}

print("Classification result:", classification)

output

Classification result: {'label': 'Positive', 'confidence': 0.98}

Common variations

Use different models like gpt-4o for higher accuracy.
Implement async calls with asyncio and await for concurrency.
Stream responses for real-time output using stream=True in chat.completions.create.
Adjust prompt instructions to output other structured formats like XML or YAML if needed.

python

import asyncio
from openai import OpenAI

async def classify_async(text: str):
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    prompt = (
        f"Classify the following text into Positive, Negative, or Neutral. "
        f"Return JSON with 'label' and 'confidence'.\nText: \"{text}\""
    )
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    content = response.choices[0].message.content
    return content

async def main():
    result = await classify_async("The product is okay, but could be better.")
    print("Async classification result:", result)

asyncio.run(main())

output

Async classification result: {"label": "Neutral", "confidence": 0.85}

Troubleshooting

If JSON parsing fails, verify the prompt clearly instructs the model to output valid JSON.
Use explicit delimiters or JSON schema in the prompt to improve output consistency.
Check your API key and environment variable setup if authentication errors occur.
For unexpected model outputs, try increasing max_tokens or adjusting temperature to 0 for deterministic results.

✅

Key Takeaways

Use explicit prompt instructions to get structured JSON classification outputs from the model.
Parse the model's JSON response safely to extract classification labels and confidence scores.
Leverage async and streaming options for scalable and real-time classification workflows.
Adjust model parameters and prompt clarity to reduce JSON parsing errors and improve reliability.

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

Verify ↗