Structured output

Structured output helps you use model responses directly in software. Instead of asking for free-form text and parsing it later, you can request JSON or a strict JSON Schema shape. Use it for extraction, form filling, configuration generation, routing decisions, and any workflow where downstream code expects stable fields.

JSON mode

JSON mode asks the model to return valid JSON:

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "system", "content": "You extract information and return JSON only."},
    {"role": "user", "content": "Alice is 28 and works as an engineer. Extract name, age, and job."}
  ],
  "response_format": {
    "type": "json_object"
  }
}

JSON mode guarantees valid JSON, but it does not guarantee a specific field structure. Describe the expected keys clearly in the prompt when you use this mode.

JSON Schema mode

Use json_schema when you need a stricter shape:

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "Alice is 28 and works as an engineer."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "job": {"type": "string"}
        },
        "required": ["name", "age", "job"],
        "additionalProperties": false
      }
    }
  }
}

Important fields:

strict: true asks the model to follow the schema closely.
required lists fields that must be present.
additionalProperties: false prevents unexpected fields.

Python example

Replace the entire sk-your-api-key value in API_KEY with your actual key. To use another model, change MODEL. The example bypasses system proxy environment variables and connects directly to Moxus AI.

import json
import httpx
from openai import OpenAI

# Replace the entire value with your actual key before running.
API_KEY = "sk-your-api-key"
# Use the exact name from Model Square. This example uses gpt-5.4-mini.
MODEL = "gpt-5.4-mini"

client = OpenAI(
    api_key=API_KEY,
    base_url="https://moxus.cloud/v1",
    # Connect directly to Moxus AI without reading system or terminal proxy variables.
    http_client=httpx.Client(trust_env=False, timeout=60.0),
)

response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "Alice is 28 and works as an engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "job": {"type": "string"},
                },
                "required": ["name", "age", "job"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(data["name"], data["age"], data["job"])

Node.js example

Replace the entire sk-your-api-key value in API_KEY with your actual key. To use another model, change MODEL. The model returns a JSON string; the example converts it to an object with JSON.parse.

import OpenAI from "openai";

// Replace the entire value with your actual key before running.
const API_KEY = "sk-your-api-key";
// Use the exact name from Model Square. This example uses gpt-5.4-mini.
const MODEL = "gpt-5.4-mini";

const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: "https://moxus.cloud/v1",
});

const response = await client.chat.completions.create({
  model: MODEL,
  messages: [
    { role: "user", content: "Alice is 28 and works as an engineer." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          job: { type: "string" },
        },
        required: ["name", "age", "job"],
        additionalProperties: false,
      },
    },
  },
});

const content = response.choices[0].message.content;
if (!content) {
  throw new Error("The model did not return JSON content");
}

const data = JSON.parse(content);
console.log(data.name, data.age, data.job);

Nested structures

Schemas can include arrays, nested objects, and enums:

{
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "status": {
      "type": "string",
      "enum": ["pending", "paid", "shipped", "done"]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "quantity": {"type": "integer"},
          "price": {"type": "number"}
        },
        "required": ["name", "quantity", "price"],
        "additionalProperties": false
      }
    }
  },
  "required": ["order_id", "status", "items"],
  "additionalProperties": false
}