Skip to main content

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​

PurposeChat CompletionsNative ResponsesMessages
Conversation inputmessagesinputmessages; system is top-level
Output-token budgetModel-supported max_tokens or max_completion_tokensmax_output_tokensRequired max_tokens
Stream outputstream: truestream: truestream: true
Function toolstools, tool_choice on supported modelsResponses tool declaration and result itemsMessages tool declarations and tool_result blocks
Structured outputSupported response_formatSupported text.formatUse supported tools and validate the arguments
Reasoning effortSupported reasoning_effortSupported reasoning.effortNative thinking/output controls only when supported
Cache guidanceSupported prompt_cache_keyProvider-native options on supported routesNative 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​

SituationBehavior
Supported control on a compatible routeForwarded using that route's request contract; the provider validates its values
Unknown field reaching the Chat Completions/embedding forwarding filterRemoved from the forwarded request and disclosed in X-Primex-Warnings
stop on restricted GPT reasoning Chat routesRemoved with an ignored_parameter:stop warning
Requested output budget exceeds the effective Gateway/model ceilingReduced with an output_tokens_clamped warning
Unsupported feature or model-specific controlCan return HTTP400 with an actionable error.code before dispatch
Request-supplied upstream destination or credentialsRejected 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:

Text
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_effort entirely.
  • 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.