Structured output

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.

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

JSON mode

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

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"},
)

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" }
  }'

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.

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.

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,
            },
        },
    },
)

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
        }
      }
    }
  }'

The response content is a JSON string matching the schema:

{
  "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:

import json

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

const data = JSON.parse(resp.choices[0].message.content);
console.log(data.name, data.age);

Structured output pairs well with tool calling 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.

Get started

Capture

Observe

Grade & Judge

Evaluate

Improve

Run at scale

Platform

Structured output

JSON mode

JSON schema mode

Parsing the result

​JSON mode

​JSON schema mode

​Parsing the result

JSON mode

JSON schema mode

Parsing the result