Structured Output

Structured Output ensures the model generates responses that conform to a JSON schema you define. This is essential for building reliable applications that need to parse model output programmatically.

JSON Mode

The simplest approach is to request JSON output using response_format:

from openai import OpenAI

client = OpenAI(
    base_url="https://openapi.linkwo.ai/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that responds in JSON."},
        {"role": "user", "content": "List 3 programming languages with their use cases."}
    ],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)
print(data)

Important: When using json_object mode, include instructions to output JSON in the system or user message, or the model may produce empty output.

JSON Schema

For stricter control, specify a JSON schema that the model must follow:

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract the name, age, and skills from: John is a 30-year-old Python developer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "skills": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "age", "skills"],
                "additionalProperties": False
            }
        }
    }
)

The response will always be valid JSON matching this schema:

{
  "name": "John",
  "age": 30,
  "skills": ["Python"]
}

Using Pydantic (Python)

With the OpenAI Python SDK, you can use Pydantic models directly:

from pydantic import BaseModel

class PersonInfo(BaseModel):
    name: str
    age: int
    skills: list[str]

response = client.beta.chat.completions.parse(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract: John is a 30-year-old Python developer."}
    ],
    response_format=PersonInfo
)

person = response.choices[0].message.parsed
print(f"{person.name}, age {person.age}, skills: {person.skills}")

Schema Definition Rules

When defining a strict JSON schema:

All fields must be in required
Set additionalProperties: false on each object
Use supported types: string, number, integer, boolean, array, object
Nest objects and arrays as needed
Use enum for constrained string values

Common Use Cases

Use Case	Example Schema
Data extraction	Extract entities from unstructured text
Classification	Categorize input with labels and confidence
Code generation	Generate structured code configurations
API input	Produce valid JSON for downstream APIs

Error Handling

If the model cannot generate valid output for the given schema, it may return a refusal:

message = response.choices[0].message
if message.refusal:
    print(f"Model refused: {message.refusal}")
else:
    data = json.loads(message.content)

Supported Models

Structured output with JSON schema is available on most models. Check individual model pages in Model Overview for compatibility details.

Function Calling — Tool calling with structured parameters
Chat Completions — Base API reference

Function Calling

Batch Requests