Structured outputs

For /v1/responses, see Using the Responses API. The other examples on this page use Chat Completions.

What is structured outputs?

Structured outputs constrain a model-generated response to a JSON Schema that you provide. Instead of describing the desired shape in the prompt and hoping the model complies, you pass the schema in response_format, and the reply comes back as valid JSON that matches it — the same field names, the same types, and only the values the schema allows. The result is safe to parse, but schema validity does not make its values trusted. Validate domain rules, escape content for its destination, and enforce authorization before using the values in UI, storage, or external actions.

Choose an output mode

Use structured outputs whenever your application depends on fixed fields, types, or enum values. JSON mode only guarantees that the output parses as JSON — the field names, types, and nesting can differ from one call to the next, so you still have to validate what comes back.

JSON mode also requires the word JSON to appear somewhere in the conversation. If it does not, the request returns an HTTP 400 error.

Defining schemas

Structured outputs support a subset of the JSON Schema specification, matching the subset used by OpenAI Structured Outputs.

Requirements

• The supported types are string, number, integer, boolean, object, and array.
• The root of the schema must be an object.
• Every property must be listed in the required array.
• To represent an optional value, keep the key in required and add null to its type — for example, "type": ["string", "null"]. The key is always present in the response; its value can be null.
• strict must be set to true.
• additionalProperties must be set to false on every object.
• Objects can nest up to 10 levels deep.
• $defs and $ref are supported across all current aliases, and are the recommended way to reuse a subschema. Only local references of the form #/$defs/<name> are accepted.

Not supported

• The composition keywords outside the OpenAI subset — allOf, oneOf, not, dependentRequired, dependentSchemas, and if/then/else.
• patternProperties.
• Recursive $ref, including a self-reference to the schema root ({"$ref": "#"}). Any reference other than a local #/$defs/<name> is rejected with an HTTP 400 error, so flatten recursive structures to a fixed depth instead.

Avoid for cross-model compatibility

Nested anyOf is not reliable across all current aliases, so avoid it if your application has to work on more than one model. Express alternatives with an enum or a set of nullable fields instead of composition keywords.

Make a structured request

Classify a support ticket and draft a reply in a single solar-pro4 call. Because the schema pins category to three known values, the response is always one of billing, technical, or account — never a synonym the model chose on its own.

import json

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1"
)

response = client.chat.completions.create(
    model="solar-pro4",
    messages=[
        {
            "role": "user",
            "content": "Classify this urgent support ticket and draft a short reply: I was charged twice for my subscription."
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "support_ticket",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": ["billing", "technical", "account"],
                        "description": "The topic the ticket belongs to."
                    },
                    "urgent": {
                        "type": "boolean",
                        "description": "Whether the ticket needs an immediate response."
                    },
                    "reply": {
                        "type": "string",
                        "description": "A short reply to send to the customer."
                    }
                },
                "required": ["category", "urgent", "reply"],
                "additionalProperties": False
            }
        }
    }
)

ticket = json.loads(response.choices[0].message.content)
print(ticket["category"], ticket["urgent"])
print(ticket["reply"])

Understand the response

The raw Chat Completions response carries the generated JSON as a string in choices[0].message.content, not as an already-parsed object. Anything that speaks the OpenAI-compatible API sees that string: the Python OpenAI, JavaScript, cURL, and LlamaIndex examples above parse it themselves — json.loads in Python, JSON.parse in JavaScript. LangChain is the exception, because with_structured_output parses the string for you and hands back an object.

Check choices[0].finish_reason before parsing. A value of stop means the model finished the object and the content is complete JSON. A value of length means generation hit the token limit and the content is cut off mid-object, so parsing it will fail. Handle that case by raising max_tokens or retrying, rather than by parsing the truncated text.

{
  "id": "b84cc249-fc79-4e84-bedc-eac25f88a90a",
  "object": "chat.completion",
  "created": 1785957109,
  "model": "solar-pro4-260806",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\n  \"category\": \"billing\",\n  \"urgent\": true,\n  \"reply\": \"Dear Customer,\\n\\nThank you for reaching out. I am truly sorry to hear about the duplicate charge on your subscription. I understand how concerning this is.\\n\\nThis ticket is marked as high priority. To help us investigate and issue a refund if necessary, please reply with the following details:\\n- Date and amount of both charges\\n- Transaction IDs (if available)\\n\\nWe aim to resolve this within 24-48 hours. Thank you for your patience.\\n\\nBest regards,\\nSupport Team\"\n}",
        "reasoning": "Thinking Process:\n\n1.  **Analyze the Request:**\n    *   Task: Classify an urgent support ticket and draft a short reply.\n    *   Input: \"I was charged twice for my subscription.\"\n    *   Constraint: I am Solar Pro4, a large language model trained by Upstage AI. My knowledge cutoff is 2026-02.\n    *   Goal: Provide a classification and a draft response.\n\n2.  **Classify the Ticket:**\n    *   Content: User claims duplicate billing/charging.\n    *   Urgency: High (financial issue).\n    *   Category: Billing/Subscription > Duplicate Charge.\n    *   Priority: High/Urgent.\n\n3.  **Draft the Reply:**\n    *   Tone: Empathetic, professional, action-oriented.\n    *   Content: Acknowledge the issue, apologize, request necessary details (transaction IDs, dates), explain next steps (investigation/refund process), provide timeline.\n    *   Length: Short (as requested).\n\n4.  **Check Constraints & Identity:**\n    *   Identity: Solar Pro4 by Upstage AI.\n    *   Knowledge Cutoff: 2026-02 (not directly relevant for this generic task, but good to keep in mind).\n    *   Safety: No sensitive info requested unnecessarily.\n\n5.  **Drafting the Response:**\n\n    *   *Classification:* Billing Issue - Duplicate Charge (High Priority).\n    *   *Reply:*\n        *   Subject: Urgent: Regarding Your Double Charge\n        *   Body: Dear [Customer Name], Thank you for reaching out. I'm sorry to hear about the duplicate charge. This is a priority for us. Please provide the transaction IDs/dates so we can investigate. We aim to resolve this within 24-48 hours. Best, Support Team.\n\n6.  **Refining for Quality:**\n    *   Make it sound natural and helpful.\n    *   Ensure the classification is clear.\n\n7.  **Final Output Generation:** (Matches the thought process above)."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 71,
    "completion_tokens": 553,
    "total_tokens": 624,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 423,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": null
}

Stream structured output

Set stream to true to receive the JSON as it is generated. The response arrives as fragments of JSON text in choices[0].delta.content, not as partial objects — each fragment is a piece of the string, so an individual delta is usually not valid JSON on its own. Accumulate every delta into a single string and parse it only after the stream finishes.

If you read the raw SSE stream instead of using an SDK, the stream ends with a data: [DONE] line.

Using the Responses API

The Responses API is available on Solar Pro 4 and Solar Mini 4.

Use the flat text.format object to define a JSON Schema. The SDK exposes the generated JSON string as response.output_text.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1",
)

response = client.responses.create(
    model="solar-pro4",
    input="Extract the city and country: I flew to Paris last spring.",
    text={
        "format": {
            "type": "json_schema",
            "name": "location",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "country": {"type": "string"},
                },
                "required": ["city", "country"],
                "additionalProperties": False,
            },
        }
    },
)
print(response.output_text)  # {"city": "Paris", "country": "France"}