Structured Output

Make model responses easier for applications to parse and validate as structured data.

Structured Output makes a model return results in an expected data structure so applications can extract fields, write records to a database, or continue a downstream workflow. Common use cases include support ticket classification, form extraction, content review results, and fixed-format analysis reports.

Structured Output and Tool Calling solve different problems

Use Structured Output when you need the model to return a structured answer. Use Tool Calling when you need the model to select and request an application function. Tool arguments can also be constrained by a Schema, but they belong to the tool call loop.

Choose the appropriate output method first

Method	What it solves	What the client still needs to do
Request JSON in the prompt	Provides a basic constraint for models that do not support a dedicated field	Extract, parse, and validate the JSON, then retry when parsing fails
JSON Object	Requires the model to return a valid JSON object	Validate fields, types, and business rules
JSON Schema	Supplies the target structure in the request	Handle model support, refusals, truncation, and validation failures

Support for JSON Object, JSON Schema, or strict adherence depends on the current model and protocol. Do not assume that the requested Schema took effect simply because the request returned 200.

Define a small, explicit Schema

The following structure classifies a customer question as a support ticket:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

Field names should be stable and easy to understand, and enum values should match the business code. Avoid deeply nested structures, too many optional branches, or difficult-to-explain regular expression constraints at the beginning.

Return a structured result with Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "My API Key does not work. Please classify this issue."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strict is part of the target format, but whether it is available still depends on the model. See Chat Completions Reference for the complete fields.

Field locations across protocols

Chat selects json_object or json_schema in response_format. When using JSON Schema, the Schema appears in response_format.json_schema.schema.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

These structures cannot be copied directly between protocols. Before use, see Responses Reference and Gemini Generate Content Reference.

Validate after parsing

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('The structured result is missing required fields');
  }

  return value as SupportTicket;
}

This example demonstrates only the minimum checks. Production projects should use a Schema validator aligned with the business data model and validate enums, lengths, numeric ranges, and cross-field rules.

Handle incomplete and invalid results

Observed state	Action
Plain text is returned	Confirm that the model supports the target format and check the field location and whether the SDK rewrote the request
JSON cannot be parsed	Save the redacted response and stop reason, then retry a limited number of times according to the business policy
Required fields are missing	Treat it as a validation failure; do not silently hide missing critical data with defaults
Output is truncated	Adjust the output budget or simplify the Schema; do not guess and append missing JSON
The model refuses to answer	Handle the refusal separately; do not treat refusal text as a business object
The Schema parses but the result is invalid for the business	Return an explicit validation error or route it to manual handling

Pre-production checklist

Generate the Schema and application types from the same source or keep them synchronized.
Reconfirm the protocol, supported Schema subset, and strict mode before switching models.
Give parsing failures, refusals, truncation, and empty output separate handling branches.
Validate structured results again before writing to a database or triggering a business action.
Store only the redacted information needed for troubleshooting in logs.

After confirming the model in the Model marketplace, open the corresponding API Reference for complete fields. If a request fails, see Errors and troubleshooting.