Structured Outputs

Use text.format when your application needs schema-shaped output instead of free-form prose. On the wire, the structured result still comes back as JSON text inside a normal message item. Choose this when downstream code depends on a predictable schema, not just “please answer in JSON” prompting.

Request

from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1",
    input="Extract an event from: Alice and Bob are going to a science fair on Friday.",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "date": {"type": "string"},
                    "participants": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                },
                "required": ["name", "date", "participants"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    },
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-4.1',
  input: 'Extract an event from: Alice and Bob are going to a science fair on Friday.',
  text: {
    format: {
      type: 'json_schema',
      name: 'event',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          date: { type: 'string' },
          participants: {
            type: 'array',
            items: { type: 'string' },
          },
        },
        required: ['name', 'date', 'participants'],
        additionalProperties: false,
      },
      strict: true,
    },
  },
});

console.log(response.output_text);

curl https://api.naga.ac/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "Extract an event from: Alice and Bob are going to a science fair on Friday.",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "event",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "date": { "type": "string" },
            "participants": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["name", "date", "participants"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  }'

Response Shape

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "{\"name\":\"Science Fair\",\"date\":\"Friday\",\"participants\":[\"Alice\",\"Bob\"]}",
      "annotations": [],
      "logprobs": []
    }
  ]
}

Choose the right mode

Mode	Use it when
`json_schema`	you need required fields, enums, nested objects, or strict validation
`json_object`	you only need valid JSON without full schema enforcement

How To Read The Result

parse the JSON string from output[*].content[*].text
if you only need valid JSON and not schema enforcement, use text.format.type: "json_object" instead

Caveats

strict: true works best with a closed schema such as additionalProperties: false
the wire response remains item-based even when the output is structured
model support still depends on the selected model

Common mistakes

expecting a native JSON object instead of parsing the returned text
using an open schema when the app really needs closed, validated output
assuming every model supports strict schema following equally well

Get Started

Build

API Guides

Account

Product

Request

Response Shape

Choose the right mode

How To Read The Result

Caveats

Common mistakes

​Request

​Response Shape

​Choose the right mode

​How To Read The Result

​Caveats

​Common mistakes

​Related Docs

Request

Response Shape

Choose the right mode

How To Read The Result

Caveats

Common mistakes

Related Docs