> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scitix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Output

Structured Output lets models return JSON content that can be parsed by programs, making it easier to validate, parse, and automate downstream processing.

## Use Cases

* Extract structured fields from news articles, such as title, time, and link.
* Perform sentiment analysis on product reviews, including polarity, intensity, and keywords.
* Generate recommendation lists from transaction or browsing history, such as products, reasons, prices, and promotional information.

## Supported Models

* Most online language models support JSON mode; VL models currently do not.
* Model capabilities are continuously updated. For the latest support information, refer to the model detail page in [Models](https://console.scitix.ai/model-inference/models).

## Output Format

The platform supports controlling model output format through `response_format`. This includes:

* JSON mode (`json_object`): Use `json_object` when you only need the model to return valid JSON.
* Strict schema (`json_schema`): Use `json_schema` when the output must follow a fixed structure.

### JSON Mode

JSON mode lets the model return a JSON string instead of free-form text.

```python theme={null}
response_format = {"type": "json_object"}
```

When using JSON mode, we still recommend specifying the required fields and format in your prompt.

### Strict Schema

If you need the model to output data in a specific structure, you can pass in a JSON Schema. The model is then constrained to the field names, types, and required fields you define, reducing post-processing costs.

```python theme={null}
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "city",
        "schema": {
            "type": "object",
            "properties": {
                "capital": {"type": "string"},
            },
            "required": ["capital"],
        },
    },
}
```

## Best Practices

* **Define output constraints clearly**: In your prompt, state that the model should output JSON only and should not include explanatory text.
* **Strengthen schema constraints**: When using `json_schema`, clearly define field names, types, required fields, optional fields, examples, and "no extra fields" when applicable.
* **Reduce randomness**: Use a lower `temperature`, such as 0.2-0.5, to reduce randomness and drift.
* **Prefer non-streaming responses**: Prefer `stream=False`. If you use streaming, wait until all chunks are received before calling `json.loads`.
* **Control output length**: Set a reasonable `max_completion_tokens` value to avoid truncating the JSON object.
* **Handle parsing failures**: If parsing fails, retry with stricter constraints and record the raw output for troubleshooting.
* **Validate external JSON**: We recommend handling edge cases where the model returns incomplete or invalid JSON on the application side. Validate the JSON returned by the model before using it, and avoid concatenating untrusted content directly into SQL queries or code paths.

## Examples

The examples read the API key from an environment variable to avoid writing secrets into code.

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

### JSON Mode

```python theme={null}
import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://api.scitix.ai/model-api",
)

resp = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant designed to output JSON.",
        },
        {
            "role": "user",
            "content": "What is the capital of France? Please respond as {\"capital\": ...}",
        },
    ],
    response_format={"type": "json_object"},
    temperature=0.3,
    max_completion_tokens=256,
    stream=False,
)

raw = resp.choices[0].message.content
print("RAW:", raw)

try:
    data = json.loads(raw)
    print("PARSED:", data)
except json.JSONDecodeError:
    print("JSON parsing failed; retry with lower temperature or higher max_completion_tokens")
```

Sample output:

```json theme={null}
{"capital": "Paris"}
```

### Strict Schema

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://api.scitix.ai/model-api",
)

response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "city",
        "schema": {
            "type": "object",
            "properties": {
                "capital": {"type": "string"},
            },
            "required": ["capital"],
        },
    },
}

resp = client.chat.completions.create(
    model="Qwen/Qwen3-32B",
    messages=[{"role": "user", "content": "Capital of France?"}],
    response_format=response_format,
)

print(resp.choices[0].message.content)
```