Structured outputs

Structured Outputs ensures the model's reply matches your JSON Schema. Set response_format.type to "json_schema" and define your schema in the json_schema object (name and schema).

Examples

List Nobel Peace Prize winners from 2022 through 2024.

Nobel laureates

curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "subq-preview",
  "messages": [
    {
      "role": "system",
      "content": "Return Nobel Peace Prize laureates for only the year range in the user message. One array entry per laureate (shared prizes produce multiple entries with the same year). Set kind to 👤 for a person and 🏛️ for an organization or institution. Use ISO 3166-1 alpha-2 country codes. Keep each motivation to one sentence."
    },
    {
      "role": "user",
      "content": "List Nobel Peace Prize winners from 2022 through 2024."
    }
  ],
  "stream": false,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "nobel_peace_laureates",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "laureates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "year": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "👤",
                    "🏛️"
                  ],
                  "description": "👤 for a person; 🏛️ for an organization or institution"
                },
                "country_code": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2"
                },
                "motivation": {
                  "type": "string",
                  "description": "One-sentence citation summary"
                }
              },
              "required": [
                "year",
                "name",
                "kind",
                "country_code",
                "motivation"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "laureates"
        ],
        "additionalProperties": false
      }
    }
  }
}
'

cURLNode.jsTypeScriptPython

Example response

The model returns schema-valid JSON as a string in choices[0].message.content. Shown below after parsing:

{
  "laureates": [
    {
      "year": 2022,
      "name": "Ales Bialiatski",
      "kind": "👤",
      "country_code": "BY",
      "motivation": "Recognized for his tireless efforts to expose human rights abuses and promote democracy in Belarus."
    },
    {
      "year": 2022,
      "name": "Memorial",
      "kind": "🏛️",
      "country_code": "RU",
      "motivation": "Honored for its documentation of political repression and human rights violations in the Soviet Union and Russia."
    },
    {
      "year": 2022,
      "name": "Center for Civil Liberties",
      "kind": "🏛️",
      "country_code": "UA",
      "motivation": "Commended for its courageous work defending human rights and civil liberties in Ukraine."
    },
    {
      "year": 2023,
      "name": "Narges Mohammadi",
      "kind": "👤",
      "country_code": "IR",
      "motivation": "Awarded for her unwavering fight against oppression and her advocacy for women's rights in Iran."
    },
    {
      "year": 2024,
      "name": "Nihon Hidankyo",
      "kind": "🏛️",
      "country_code": "JP",
      "motivation": "Recognized for its efforts to achieve a world free of nuclear weapons and its work to eliminate nuclear weapons."
    }
  ]
}

Field	Type	Notes
`laureates`	array	One object per laureate
`year`	integer	Award year
`name`	string	Person or organization
`kind`	enum	`👤` individual, `🏛️` organization
`country_code`	string	ISO 3166-1 alpha-2
`motivation`	string	One-sentence citation summary

Classify each alert from a list of desk messages.

Risk alerts

curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "model": "subq-preview",
  "messages": [
    {
      "role": "system",
      "content": "Classify each risk alert. Use ISO 8601 for detected_at. Set requires_immediate_action true for high or critical severity. Use 0 for exposure_usd when not applicable."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Classify each alert:\n\n1. Counterparty X missed their margin call deadline; $2.3M exposure in US equities.\n\n2. Liquidity in small-cap biotech names dropped 40% this morning; no immediate counterparty issues.\n\n3. NYSE halted trading in SYM for volatility; we have 12,000 shares on the book.\n\n4. Ops team reports duplicate settlement files from last night's batch run."
        }
      ]
    }
  ],
  "stream": false,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "risk_alert_batch",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "alert_id": {
                  "type": "integer",
                  "description": "Matches the numbered alert in the input"
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "counterparty",
                    "liquidity",
                    "market",
                    "operational",
                    "compliance"
                  ]
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "low",
                    "medium",
                    "high",
                    "critical"
                  ]
                },
                "exposure_usd": {
                  "type": "number"
                },
                "requires_immediate_action": {
                  "type": "boolean"
                },
                "detected_at": {
                  "type": "string",
                  "description": "ISO 8601 datetime"
                },
                "summary": {
                  "type": "string"
                }
              },
              "required": [
                "alert_id",
                "category",
                "severity",
                "exposure_usd",
                "requires_immediate_action",
                "detected_at",
                "summary"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "alerts"
        ],
        "additionalProperties": false
      }
    }
  }
}
EOF

cURLNode.jsTypeScriptPython

Example response

The model returns schema-valid JSON as a string in choices[0].message.content. Shown below after parsing:

{
  "alerts": [
    {
      "alert_id": 1,
      "category": "counterparty",
      "severity": "high",
      "exposure_usd": 2300000,
      "requires_immediate_action": true,
      "detected_at": "2024-06-15T09:30:00Z",
      "summary": "Counterparty X missed margin call deadline with $2.3M exposure in US equities"
    },
    {
      "alert_id": 2,
      "category": "market",
      "severity": "medium",
      "exposure_usd": 0,
      "requires_immediate_action": false,
      "detected_at": "2024-06-15T09:30:00Z",
      "summary": "Liquidity in small-cap biotech names dropped 40% this morning; no immediate counterparty issues"
    },
    {
      "alert_id": 3,
      "category": "market",
      "severity": "high",
      "exposure_usd": 0,
      "requires_immediate_action": true,
      "detected_at": "2024-06-15T09:30:00Z",
      "summary": "NYSE halted trading in SYM for volatility; we have 12,000 shares on the book"
    },
    {
      "alert_id": 4,
      "category": "operational",
      "severity": "medium",
      "exposure_usd": 0,
      "requires_immediate_action": false,
      "detected_at": "2024-06-15T09:30:00Z",
      "summary": "Ops team reports duplicate settlement files from last night's batch run"
    }
  ]
}

Field	Type	Notes
`alerts`	array	One object per input alert
`alert_id`	integer	Matches the numbered alert in the input
`category`, `severity`	enum	Fixed classification values
`requires_immediate_action`	boolean	Routing flag
`exposure_usd`	number	Use `0` when not applicable
`detected_at`	string	ISO 8601 datetime
`summary`	string	One-sentence alert summary

Set stream to false or omit it for a single JSON response.

`response_format` reference

Field	Type	Description
`type`	string	Must be `"json_schema"`.
`json_schema.name`	string	Schema identifier, such as `nobel_peace_laureates`.
`json_schema.strict`	boolean	Set `true` to enforce schema adherence.
`json_schema.schema`	object	JSON Schema for the response object.

Schema requirements

Root type must be object.
List every property in required.
Set additionalProperties: false on each object.
Supported types: string, number, boolean, integer, enum, array, nested object.

There is no native datetime type—use a string field with ISO 8601 in the name or description (for example, submit_by, detected_at).

For the full constraint list, see OpenAI's supported schemas.

The model returns your JSON string in choices[0].message.content. Before parsing, check for HTTP 4xx errors, refusals, truncation (finish_reason is "length"), then validate the parsed JSON in your app.

Best practices

Use the system message to interpret the schema. The schema sets shape; the system message sets meaning. Spell out formats, enums, and terse field names—the examples above do this.
Define fallbacks for missing data. Required fields still need a value when input omits them—e.g. Use 0 for exposure_usd when not applicable.
Keep schemas small. Flat objects are easier to satisfy than deep nesting.

On the Responses API

Chat Completions uses response_format with a nested json_schema object. The Responses API uses a flattened text.format field instead — name, strict, and schema sit directly on text.format:

{
  "model": "subq-preview",
  "input": "List Nobel Peace Prize winners from 2022 through 2024.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "nobel_peace_laureates",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "laureates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "year": { "type": "integer" },
                "name": { "type": "string" }
              },
              "required": ["year", "name"],
              "additionalProperties": false
            }
          }
        },
        "required": ["laureates"],
        "additionalProperties": false
      }
    }
  }
}

The structured JSON arrives at output[0].content[0].text. See Responses API for the full parameter reference.

Chat Completions API — request fields and response shape.
Responses API — structured output via text.format.
Function calling — tools and tool call outputs.
Models — supported model IDs.
OpenAI Structured Outputs — full feature reference.