Structured Output

Two Modes

JSON Mode

Set response_format to { "type": "json_object" }. The model returns valid JSON, but you do not control the schema. You must instruct the model in your prompt to use the structure you want.

{
  "model": "openai/gpt-4.1",
  "messages": [
    {
      "role": "system",
      "content": "You extract contact info. Return JSON with fields: name, email, phone."
    },
    {
      "role": "user",
      "content": "John Smith, john@example.com, (555) 123-4567"
    }
  ],
  "response_format": { "type": "json_object" }
}

Response:

{
  "name": "John Smith",
  "email": "john@example.com",
  "phone": "(555) 123-4567"
}

JSON Schema Mode

Set response_format to { "type": "json_schema", "json_schema": { ... } }. The model is forced to produce output that validates against your schema. This gives you guaranteed structure.

{
  "model": "openai/gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "Extract the product info: iPhone 16 Pro, $999, 256GB storage, available in black and white."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "product_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "product_name": { "type": "string" },
          "price_usd": { "type": "number" },
          "storage_gb": { "type": "integer" },
          "colors": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["product_name", "price_usd", "storage_gb", "colors"],
        "additionalProperties": false
      }
    }
  }
}

Response:

{
  "product_name": "iPhone 16 Pro",
  "price_usd": 999,
  "storage_gb": 256,
  "colors": ["black", "white"]
}

JSON Mode vs JSON Schema Mode

Use JSON mode when the structure is simple and you can describe it in the prompt. Use JSON Schema mode when you need guaranteed field names, types, and nesting.

Supported Models

JSON Schema mode (json_schema) is supported by:

• OpenAI: GPT-4.1, GPT-4.1-mini, GPT-4.1-nano, GPT-4o, GPT-5, o3, o4-mini
• Anthropic: Claude Opus 4, Claude Sonnet 4, Claude Haiku 3.5
• Google: Gemini 2.5 Pro, Gemini 2.5 Flash

JSON mode (json_object) is supported by most chat models across all providers.

Code Examples

curl -X POST https://api.chuizi.ai/v1/chat/completions \
  -H "Authorization: Bearer ck-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [
      {"role": "user", "content": "Extract: Tokyo, population 14 million, country Japan, continent Asia"}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "city_info",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "population": {"type": "integer"},
            "country": {"type": "string"},
            "continent": {"type": "string"}
          },
          "required": ["city", "population", "country", "continent"],
          "additionalProperties": false
        }
      }
    }
  }'

Tips

• Always include "additionalProperties": false in strict mode schemas. Without it, the model may add extra fields.
• Keep schemas flat when possible. Deeply nested schemas increase the chance of validation errors and slow down generation.
• JSON mode requires a prompt hint. If you use json_object mode without mentioning "JSON" in the system or user message, some models will return an error.
• Streaming works with structured output. The JSON is generated token-by-token. Parse incrementally or wait for the complete response.
• Set "strict": true for production pipelines. Without strict mode, the model makes a best effort but may occasionally deviate from the schema.

Next Steps

• Function Calling — structured tool calls as an alternative to JSON output
• Chat Completions API — full response_format parameter reference
• Error Handling — handle schema validation failures gracefully