Skip to main content

Structured Outputs

JSON is one of the most widely used formats in the world for applications to exchange data.

Structured Outputs is a feature that ensures the model will always generate responses that adhere to your supplied JSON Schema, so you don't need to worry about the model omitting a required key, or hallucinating an invalid enum value.

Model Support

Most models support Structured Outputs. Check the NagaAI Models page for details. Before using this feature, test to ensure the specific model supports it.

Example Request​

{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "system",
      "content": "Extract the event information."
    },
    {
      "role": "user",
      "content": "Alice and Bob are going to a science fair on Friday."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "CalendarEvent",
      "description": null,
      "schema": {
        "properties": {
          "name": {
            "title": "Name",
            "type": "string"
          },
          "date": {
            "title": "Date",
            "type": "string"
          },
          "participants": {
            "items": {
              "type": "string"
            },
            "title": "Participants",
            "type": "array"
          }
        },
        "required": [
          "name",
          "date",
          "participants"
        ],
        "title": "CalendarEvent",
        "type": "object",
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

Example Response​

In the response, you will receive something like this:

{
  "id": "chatcmpl-6dJRrPVTYFxfOOcrbF66fytYVXVH",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "{\"name\":\"Science Fair\",\"date\":\"Friday\",\"participants\":[\"Alice\",\"Bob\"]}",
        "refusal": null,
        "role": "assistant",
        "annotations": [],
        "tool_calls": null,
        "parsed": {
          "name": "Science Fair",
          "date": "Friday",
          "participants": [
            "Alice",
            "Bob"
          ]
        }
      }
    }
  ],
  "created": 1758384822,
  "model": "gpt-4.1-2025-04-14",
  "object": "chat.completion",
  "usage": {...}
}

If you parse the content of the message, you will get a ready JSON object that follows your structure.

Code Example with OpenAI Library​

from pydantic import BaseModel
from openai import OpenAI

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


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


completion = client.chat.completions.parse(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {
            "role": "user",
            "content": "Alice and Bob are going to a science fair on Friday.",
        },
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)