Skip to main content

Structured Outputs

When you need machine-parseable output, ask the model for JSON. Primex passes the relevant request fields straight through to the underlying model, so the behavior matches the provider's OpenAI/Anthropic-compatible contract.

Chat Completions​

On /v1/chat/completions, set response_format:

{
  "model": "YOUR_MODEL",
  "messages": [{"role":"user","content":"Extract the invoice total and currency."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "invoice",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"total": {"type": "number"}, "currency": {"type": "string"}},
        "required": ["total", "currency"],
        "additionalProperties": false
      }
    }
  }
}

response_format: {"type": "json_object"} requests plain JSON without a schema. Tell the model to produce JSON in the prompt.

Responses​

On a native /v1/responses model, use input and text.format:

{
  "model": "YOUR_LIVE_RESPONSES_MODEL",
  "input": "Extract the total and currency from this invoice: USD 12.50.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "invoice",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"total": {"type": "number"}, "currency": {"type": "string"}},
        "required": ["total", "currency"],
        "additionalProperties": false
      }
    }
  }
}

For JSON mode, set text.format to {"type": "json_object"} and request JSON in the prompt. See the OpenAI structured-output guide. Choose a model that advertises structured_output in the live catalogue, and validate refusals and incomplete responses too.

Anthropic-compatible​

On /v1/messages, use tool calling with a single tool whose input_schema is your target shape, then read the tool-call arguments. This is the standard Anthropic pattern and passes through unchanged.

Notes​

  • Always validate the returned JSON in your code; a model can still return text that doesn't satisfy the schema on models without hard schema enforcement.
  • Structured output does not change billing: you pay for the tokens produced.