FEATURE GUIDES

Structured outputs

Strict JSON Schema, JSON mode, and validation.

Constrain the response with JSON Schema

Use a model that supports structured output and set strict: true. Prefer a small schema with explicit required fields and additionalProperties: false. Schema support follows the selected OpenAI model.

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://www.cheapinference.dev/v1",
  apiKey: process.env.CHEAPINFERENCE_API_KEY,
});

const result = await client.responses.create({
  model: "gpt-5.4-mini",
  input: "Classify this feedback: the page loads quickly.",
  store: false,
  text: { format: {
    type: "json_schema", name: "feedback", strict: true,
    schema: {
      type: "object",
      properties: { sentiment: { type: "string", enum: ["positive", "negative", "neutral"] } },
      required: ["sentiment"], additionalProperties: false,
    },
  } },
});
if (result.status === "completed" && result.output_text) {
  console.log(JSON.parse(result.output_text));
}

Use the Chat Completions shape

const result = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "Return a short task title as JSON." }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "task", strict: true,
      schema: {
        type: "object", properties: { title: { type: "string" } },
        required: ["title"], additionalProperties: false,
      },
    },
  },
});

The nesting differs: Chat uses response_format.json_schema; Responses uses text.format. Do not copy one structure unchanged into the other endpoint.

JSON mode and failure handling

For JSON without a fixed schema, use { type: "json_object" } in the corresponding format field and explicitly instruct the model to return JSON. This does not enforce your own application schema.

Handle refusals, incomplete output, and token-limit endings before parsing. Structured output does not bypass safety refusals, and a truncated response may not be valid JSON. Validate parsed data before acting on it. Streaming delivers partial JSON text; wait for completion before interpreting the whole object.