Parameters and compatibility
An API format describes the request shape. The selected model and route determine which features and parameter values can be used. Start with a minimal request, then add controls published for that offering in the Catalog.
Common controls
| Purpose | Chat Completions | Native Responses | Messages |
|---|---|---|---|
| Conversation input | messages | input | messages; system is top-level |
| Output-token budget | Model-supported max_tokens or max_completion_tokens | max_output_tokens | Required max_tokens |
| Stream output | stream: true | stream: true | stream: true |
| Function tools | tools, tool_choice on supported models | Responses tool declaration and result items | Messages tool declarations and tool_result blocks |
| Structured output | Supported response_format | Supported text.format | Use supported tools and validate the arguments |
| Reasoning effort | Supported reasoning_effort | Supported reasoning.effort | Native thinking/output controls only when supported |
| Cache guidance | Supported prompt_cache_key | Provider-native options on supported routes | Native cache_control on supported blocks |
See the endpoint reference for required fields and response formats, and the conversation guide for history and tool results. The table identifies control locations; it does not grant every model support for every control.
Omit optional sampling parameters for a first request. Provider defaults and
accepted ranges differ, and some reasoning models reject sampling controls.
Omitting temperature is different from forcing a particular value.
How Primex handles a parameter
| Situation | Behavior |
|---|---|
| Supported control on a compatible route | Forwarded using that route's request contract; the provider validates its values |
| Unknown field reaching the Chat Completions/embedding forwarding filter | Removed from the forwarded request and disclosed in X-Primex-Warnings |
stop on restricted GPT reasoning Chat routes | Removed with an ignored_parameter:stop warning |
| Requested output budget exceeds the effective Gateway/model ceiling | Reduced with an output_tokens_clamped warning |
| Unsupported feature or model-specific control | Can return HTTP400 with an actionable error.code before dispatch |
| Request-supplied upstream destination or credentials | Rejected with unsupported_routing_override |
Native Responses and native Messages do not use the Chat top-level field filter. Their own provider validation and Primex's model/tool/security checks still apply. Translated Messages and rewritten Responses have narrower contracts; they do not preserve every native feature. See API formats.
SDK extra_body can be a way to add a supported field to an SDK request. Do not
send an extra_body object or upstream routing configuration as a top-level
Primex wire field. The SDK must serialize the supported field in its normal
request location.
Read compatibility warnings
An otherwise successful response can contain this header:
X-Primex-Warnings: ignored_parameter:stop,output_tokens_clamped:1024
dropped_parameters:field_a|field_b identifies omitted fields. Names in this
warning are bounded and URL-encoded; long lists can be abbreviated. The number
above is illustrative, not a universal output limit.
Inspect response headers when introducing a new option, especially if output
does not change as expected. Browser clients can read X-Primex-Warnings and
X-Primex-Request-ID through the Gateway's CORS-exposed headers. Retain the
request ID for Usage investigation.
A missing warning does not establish that every option was honored upstream. Model/provider validation can still reject the request, and native/translated paths do not all report the same adjustments.
Model-specific restrictions
- Default reasoning does not imply a configurable effort selector. Some
third-party routes reject
reasoning_effortentirely. - A model can serve text Chat Completions while requiring native Responses for function tools. Check the endpoint as well as the capability.
- JSON mode and strict JSON-schema support differ; see structured outputs.
- Image/audio input, voice instructions, embedding dimensions and service languages have operation-specific constraints.
- Provider-run built-ins require explicit Primex availability and metering; ordinary function tools have a different execution contract.
Follow provider documentation for deeper explanations, while retaining Primex's narrower route restrictions. Fix an invalid parameter before retrying. Use Errors & Limits for recovery; a client timeout alone does not establish that no work was billed.