Structured Outputs

Chat models accept an OpenAI-style response_format, which turns "please reply in JSON" from a request the model may quietly ignore into a constraint the provider enforces:

{ "response_format": { "type": "json_schema", "json_schema": {
    "name": "person",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": { "name": { "type": "string" }, "age": { "type": "integer" } },
      "required": ["name", "age"],
      "additionalProperties": false
    }
} } }

Leave the field out — or send { "type": "text" } — and the call behaves exactly as before, so existing integrations are unaffected.

The two modes

Prefer json_schema whenever you know the shape you want. json_object still leaves you writing defensive parsing code, because nothing stops the model from renaming a key or nesting the answer one level deeper next time.

Model support

Every chat model accepts both types, with these exceptions:

Claude has no schema-less JSON mode, which is why json_object is refused there rather than approximated. The Qwen models above accept a schema upstream and then answer without enforcing it — a silently unconstrained reply is worse than a clear error, so the gateway refuses the type the model cannot honour.

Ask for an unsupported type and you get a 400 naming the one that works, before the request reaches the provider — never a surprise later.

Where the JSON arrives

The response keeps the provider's native envelope. Your JSON is a string in the usual text field, which you parse yourself:

{
  "choices": [
    { "message": { "role": "assistant", "content": "{\"name\":\"Mara Ellison\",\"age\":34}" } }
  ]
}

On v2

An async result carries the whole provider response as a string in output, so there are two decodes: one to get the envelope, one to get your object.

result = requests.get(poll_url, headers=headers).json()
envelope = json.loads(result["output"])                     # provider response
person = json.loads(envelope["choices"][0]["message"]["content"])  # your object

Rules that produce a 400

OpenAI and DeepSeek require the word "json" in the conversation when you use json_object. The provider rejects the request outright:

'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'

Adding "Reply in json." to your prompt is enough. json_schema has no such rule.

Schemas are not portable between providers. Each enforces its own subset:

The intersection — an object with every property required and additionalProperties: false, no numeric or length bounds — works everywhere. Write to that if one schema has to serve several models.

Errors

These come from the gateway, before the provider is called. On /v1 they are a 400; on /v2 the request lands as FAILED carrying the same message.

A schema keyword the provider rejects surfaces as a 400 naming the keyword.

Examples

curl -X POST https://api.segmind.com/v1/gpt-5.4-mini \
  -H "x-api-key: $SEGMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Invent one person." }],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": { "name": { "type": "string" }, "age": { "type": "integer" } },
          "required": ["name", "age"],
          "additionalProperties": false
        }
      }
    }
  }'

With the Python SDK, where .json() does the parsing:

import segmind

reply = segmind.chat_sync(
    "gpt-5.4-mini",
    messages=[{"role": "user", "content": "Invent one person."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

person = reply.json()   # {'name': 'Mara Ellison', 'age': 34}

.json() raises a SegmindError when the reply was not JSON — a refusal, for instance — so catch it rather than assuming the constraint always held.

Notes

• Billing is unchanged. You pay the model's usual token rates; asking for structured output costs nothing extra.
• No streaming. Structured replies arrive whole.
• Schema-shaped output is also what powers fan-out from an LLM in PixelFlow, where the schema is derived from the fields your downstream nodes consume.