How to beginner · 3 min read

How to classify text with structured outputs

Quick answer

Use a chat completion API like client.chat.completions.create with a prompt instructing the model to output classification results in a structured format such as JSON. Parse the structured response to extract labels or categories programmatically.

PREREQUISITES

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

Setup

Install the 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 shell: export OPENAI_API_KEY='your_api_key_here' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key_here" (Windows).

bash

pip install openai

Step by step

This example uses the gpt-4o model to classify text into categories with a JSON structured output. The prompt instructs the model to respond with a JSON object containing the classification label and confidence score.

python

import os
from openai import OpenAI

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

prompt = (
    "Classify the following text into one of these categories: ['Sports', 'Politics', 'Technology', 'Entertainment']. "
    "Respond ONLY with a JSON object with keys 'category' and 'confidence' (0 to 1).\n"
    "Text: 'The new smartphone release features advanced AI capabilities and improved battery life.'"
)

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

print("Raw response:", response.choices[0].message.content)

import json

# Parse the JSON output
try:
    classification = json.loads(response.choices[0].message.content)
    print(f"Category: {classification['category']}")
    print(f"Confidence: {classification['confidence']}")
except json.JSONDecodeError:
    print("Failed to parse JSON from model response.")

output

Raw response: {"category": "Technology", "confidence": 0.95}
Category: Technology
Confidence: 0.95

Common variations

You can adapt this approach for other models like claude-3-5-sonnet-20241022 using the Anthropic SDK, or use async calls for concurrency. Structured outputs can be customized to XML, YAML, or custom schemas depending on your application.

python

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

system_prompt = "You are a helpful assistant that classifies text into categories and outputs JSON."
user_message = (
    "Classify the following text into one of these categories: ['Sports', 'Politics', 'Technology', 'Entertainment']. "
    "Respond ONLY with a JSON object with keys 'category' and 'confidence' (0 to 1).\n"
    "Text: 'The new smartphone release features advanced AI capabilities and improved battery life.'"
)

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    system=system_prompt,
    messages=[{"role": "user", "content": user_message}]
)

print("Raw response:", response.content[0].text)

import json
try:
    classification = json.loads(response.content[0].text)
    print(f"Category: {classification['category']}")
    print(f"Confidence: {classification['confidence']}")
except json.JSONDecodeError:
    print("Failed to parse JSON from model response.")

output

Raw response: {"category": "Technology", "confidence": 0.95}
Category: Technology
Confidence: 0.95

Troubleshooting

If the model response is not valid JSON, ensure your prompt explicitly instructs the model to respond only with JSON.
Use try-except blocks to handle JSON parsing errors gracefully.
If confidence scores are missing, add instructions in the prompt to always include them.
Check your API key environment variable if authentication errors occur.

✅

Key Takeaways

Use explicit prompt instructions to get structured JSON outputs for classification.
Parse the model's JSON response programmatically to extract classification results.
Adapt the approach easily for different models and output formats.
Handle JSON parsing errors gracefully to avoid runtime crashes.
Always secure your API keys via environment variables.

Verified 2026-04 · gpt-4o, claude-3-5-sonnet-20241022

Verify ↗