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

# Structured output

> Force valid JSON or a strict schema in the model's response.

Use the `response_format` parameter to make a model return JSON, either
free-form JSON (`json_object`) or JSON that conforms to a schema you provide
(`json_schema`). This works on the standard `/v1/chat/completions` endpoint.

<Note>
  Support for strict `json_schema` mode varies by model. JSON mode
  (`json_object`) is broadly supported. Discover models with
  [`GET /v1/models`](/concepts/models) and test your schema against the model you
  intend to use.
</Note>

## JSON mode

Ask for any valid JSON object with `{"type": "json_object"}`:

<CodeGroup>
  ```python Python theme={null}
  resp = client.chat.completions.create(
      model="Qwen/Qwen3-32B",
      messages=[
          {"role": "system", "content": "Return the answer as JSON."},
          {"role": "user", "content": "Give me a person with a name and age."},
      ],
      response_format={"type": "json_object"},
  )
  ```

  ```bash cURL theme={null}
  curl https://gateway.omnia-voice.com/v1/chat/completions \
    -H "Authorization: Bearer $OMNIA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "Qwen/Qwen3-32B",
      "messages": [
        { "role": "system", "content": "Return the answer as JSON." },
        { "role": "user", "content": "Give me a person with a name and age." }
      ],
      "response_format": { "type": "json_object" }
    }'
  ```
</CodeGroup>

<Warning>
  Always instruct the model (in the system or user message) to produce JSON when
  using `json_object` mode. The mode guarantees valid JSON **syntax**, but it does
  not constrain the **shape**; you still have to tell the model what fields you
  want.
</Warning>

## JSON schema mode

For a guaranteed structure, pass `{"type": "json_schema", "json_schema": {...}}`
with a JSON Schema. The model's output is constrained to match it.

<CodeGroup>
  ```python Python theme={null}
  resp = client.chat.completions.create(
      model="Qwen/Qwen3-32B",
      messages=[{"role": "user", "content": "Give me a person."}],
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "person",
              "schema": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "age": {"type": "integer"},
                  },
                  "required": ["name", "age"],
                  "additionalProperties": False,
              },
          },
      },
  )
  ```

  ```bash cURL theme={null}
  curl https://gateway.omnia-voice.com/v1/chat/completions \
    -H "Authorization: Bearer $OMNIA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "Qwen/Qwen3-32B",
      "messages": [{ "role": "user", "content": "Give me a person." }],
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "person",
          "schema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "age": { "type": "integer" }
            },
            "required": ["name", "age"],
            "additionalProperties": false
          }
        }
      }
    }'
  ```
</CodeGroup>

The response `content` is a JSON string matching the schema:

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\": \"Ada Lovelace\", \"age\": 36}"
      },
      "finish_reason": "stop"
    }
  ]
}
```

## Parsing the result

The content is always a JSON string; parse it in your language of choice:

<CodeGroup>
  ```python Python theme={null}
  import json

  data = json.loads(resp.choices[0].message.content)
  print(data["name"], data["age"])
  ```

  ```javascript JavaScript theme={null}
  const data = JSON.parse(resp.choices[0].message.content);
  console.log(data.name, data.age);
  ```
</CodeGroup>

<Tip>
  Structured output pairs well with [tool calling](/inference/tools) for building
  reliable agents: use schemas for data extraction and tools for actions. Setting
  `additionalProperties: false` and listing every field in `required` gives you the
  tightest, most predictable output.
</Tip>