Structured outputs

Give a JSON Schema, and the answer is JSON that follows it. Use this when your code parses the answer, for example to extract fields from text or to fill a form.

With a schemaCopy Anchor Link

The OpenAI SDKs build the schema from a Pydantic model or a Zod object and parse the answer for you:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

completion = client.chat.completions.parse(
    model="raon-1-mini-preview",
    messages=[{"role": "user", "content": "Make up a person who lives in Seoul."}],
    response_format=Person,
)
print(completion.choices[0].message.parsed)

The model still reasons first. The reasoning stays in its own field, and only the answer follows the schema.

JSON modeCopy Anchor Link

response_format: {"type": "json_object"} on Chat Completions asks for any valid JSON object, without a schema. Say in the prompt which keys you want.

TipsCopy Anchor Link

• Give each field a clear name, and a description where the meaning is not obvious. The model fills fields from these.
• Leave enough output tokens for both reasoning and JSON: max_tokens or max_completion_tokens on Chat Completions, max_tokens on Messages, and max_output_tokens on Responses. Check for truncation using finish_reason: "length", stop_reason: "max_tokens", or status: "incomplete" and incomplete_details, respectively. Parse and validate the answer before using it.