Structured outputs

Get reliable JSON back without prompt-engineering the model to behave. Two modes: JSON mode (any well-formed JSON) and JSON-schema mode (matches a schema you supply).

JSON mode

Set response_format to { "type": "json_object" }. The model is forced to emit valid JSON. Include the word "JSON" in your system or user message (provider requirement on most models).

resp = client.chat.completions.create(
  model="deepseek-v4",
  response_format={"type": "json_object"},
  messages=[
    {"role": "system", "content": "Reply in JSON only."},
    {"role": "user", "content": "Top 3 monsoon cities in India with avg July rainfall (mm)."},
  ],
)
data = json.loads(resp.choices[0].message.content)

JSON schema mode

Pin the output to a specific shape. Models that support json_schema (deepseek-v4, qwen3-plus) will refuse to emit anything that doesn't validate:

response_format="{"
    "type": "json_schema",
    "json_schema": {
        "name": "city_list",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "cities": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name":     {"type": "string"},
                            "rain_mm":  {"type": "number"},
                        },
                        "required": ["name", "rain_mm"],
                    },
                },
            },
            "required": ["cities"],
        },
    },
}"

When to use which