Docs/Structured Outputs

Structured Outputs

Get valid JSON out of any capable model

Constrain model output to valid JSON with the OpenAI-compatibleresponse_format parameter, forwarded to models that support it.

JSON mode

python
resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {"role": "system", "content": "Extract invoice fields. Respond in JSON only."},
        {"role": "user", "content": "Invoice #42 from Acme, due 2026-11-01, total $1,204.50"},
    ],
    response_format={"type": "json_object"},
    max_tokens=300,
)
data = json.loads(resp.choices[0].message.content)

Practical guidance

Topic	Guidance
Say it twice	Describe the exact JSON shape in the prompt even when using json mode — field names, types, and enums.
Validate at the boundary	Parse and validate with Pydantic / zod; retry once on failure with the parse error appended.
max_tokens	Keep a generous cap — a truncated JSON object is the most common failure mode.
Model support	JSON-following quality varies by model; reasoning models tend to be strongest. Validate before shipping prompts to production.

Noteresponse_format constrains syntax, not semantics. The model can still invent field values — schema validation stays your job.