> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Output

> Get JSON responses that conform to a schema

You can force models to return valid JSON, optionally conforming to a specific schema.

## Prerequisites

* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)
* Python 3.10+ with the OpenAI SDK (`pip install openai`) or the auriko SDK (`pip install auriko`)
  * OR Node.js 18+ with the OpenAI SDK (`npm install openai`) or `@auriko/sdk` (`npm install @auriko/sdk`)

## Choose a response format

Auriko supports three response format types:

| Type          | Description                                      | Use case                             |
| ------------- | ------------------------------------------------ | ------------------------------------ |
| `text`        | Default. Model returns plain text.               | General chat, creative writing       |
| `json_object` | Model returns valid JSON. No schema enforcement. | Flexible JSON extraction             |
| `json_schema` | Model returns JSON matching a provided schema.   | Typed data extraction, API responses |

`json_schema` and `json_object` are separate capabilities. `json_schema` has broader model support. Most **Claude** models support `json_schema` but not `json_object`. Claude Sonnet 4 and Opus 4 don't support either mode.

If you request an unsupported mode, Auriko returns a `400` with a suggested alternative.

<Note>
  Check per-model support on the [models page](https://www.auriko.ai/models) or via the [Model directory](/api-reference/model-directory). `json_schema` appears as **Structured Output**, `json_object` as **JSON Mode**.
</Note>

## Return JSON

To return any JSON output, set `response_format` to `json_object`:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {"role": "system", "content": "Extract the user's name and age as JSON."},
          {"role": "user", "content": "I'm Alice and I'm 30 years old."},
      ],
      response_format={"type": "json_object"},
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          { role: "system", content: "Extract the user's name and age as JSON." },
          { role: "user", content: "I'm Alice and I'm 30 years old." },
      ],
      response_format: { type: "json_object" },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {"role": "system", "content": "Extract the user's name and age as JSON."},
          {"role": "user", "content": "I'm Alice and I'm 30 years old."}
      ],
      response_format={"type": "json_object"}
  )

  print(response.choices[0].message.content)
  # {"name": "Alice", "age": 30}
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          { role: "system", content: "Extract the user's name and age as JSON." },
          { role: "user", content: "I'm Alice and I'm 30 years old." },
      ],
      response_format: { type: "json_object" },
  });

  console.log(response.choices[0].message.content);
  // {"name": "Alice", "age": 30}
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        {"role": "system", "content": "Extract the user'\''s name and age as JSON."},
        {"role": "user", "content": "I'\''m Alice and I'\''m 30 years old."}
      ],
      "response_format": {"type": "json_object"}
    }'
  ```
</CodeGroup>

The model returns valid JSON, but the structure isn't guaranteed. For strict schema conformance, use `json_schema` instead.

<Warning>
  When using `json_object` mode, always include the word "JSON" in your system or user message. Some providers require this and return a 400 error without it. Including it is harmless on providers that don't enforce it. The `json_schema` mode does not have this requirement.

  The examples above include "JSON" in the system message.
</Warning>

## Enforce schema

You can enforce a specific JSON structure by providing a schema:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  import json
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {"role": "user", "content": "Extract: Alice is 30, lives in NYC, alice@example.com"},
      ],
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "ContactInfo",
              "schema": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "age": {"type": "integer"},
                      "city": {"type": "string"},
                      "email": {"type": "string"},
                  },
                  "required": ["name", "age", "city", "email"],
              },
          },
      },
  )

  contact = json.loads(response.choices[0].message.content)
  print(contact["name"])
  print(contact["email"])
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          { role: "user", content: "Extract: Alice is 30, lives in NYC, alice@example.com" },
      ],
      response_format: {
          type: "json_schema",
          json_schema: {
              name: "ContactInfo",
              schema: {
                  type: "object",
                  properties: {
                      name: { type: "string" },
                      age: { type: "integer" },
                      city: { type: "string" },
                      email: { type: "string" },
                  },
                  required: ["name", "age", "city", "email"],
              },
          },
      },
  });

  const contact = JSON.parse(response.choices[0].message.content!);
  console.log(contact.name);
  console.log(contact.email);
  ```

  ```python Python Auriko theme={null}
  import os
  import json
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {"role": "user", "content": "Extract: Alice is 30, lives in NYC, alice@example.com"}
      ],
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "ContactInfo",
              "schema": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "age": {"type": "integer"},
                      "city": {"type": "string"},
                      "email": {"type": "string"}
                  },
                  "required": ["name", "age", "city", "email"]
              }
          }
      }
  )

  contact = json.loads(response.choices[0].message.content)
  print(contact["name"])   # Alice
  print(contact["email"])  # alice@example.com
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          { role: "user", content: "Extract: Alice is 30, lives in NYC, alice@example.com" },
      ],
      response_format: {
          type: "json_schema",
          json_schema: {
              name: "ContactInfo",
              schema: {
                  type: "object",
                  properties: {
                      name: { type: "string" },
                      age: { type: "integer" },
                      city: { type: "string" },
                      email: { type: "string" },
                  },
                  required: ["name", "age", "city", "email"],
              },
          },
      },
  });

  const contact = JSON.parse(response.choices[0].message.content!);
  console.log(contact.name);   // Alice
  console.log(contact.email);  // alice@example.com
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        {"role": "user", "content": "Extract: Alice is 30, lives in NYC, alice@example.com"}
      ],
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "ContactInfo",
          "schema": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "age": {"type": "integer"},
              "city": {"type": "string"},
              "email": {"type": "string"}
            },
            "required": ["name", "age", "city", "email"]
          }
        }
      }
    }'
  ```
</CodeGroup>

The `json_schema` object requires a `name` field. The `schema` field accepts a standard JSON Schema definition.

<Note>
  Auriko automatically routes to providers that support your requested format. If no provider supports it, you get a clear error with suggestions.
</Note>

## Resources

<CardGroup cols={2}>
  <Card title="Tool calling" icon="wrench" href="/guides/tool-calling">
    Call functions from LLM responses
  </Card>

  <Card title="Routing options" icon="route" href="/guides/routing-options">
    Optimize for cost, latency, or throughput
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle errors and retries
  </Card>

  <Card title="Browse models" icon="list" href="https://www.auriko.ai/models">
    See which models support structured output and JSON mode
  </Card>
</CardGroup>