Provider preferences
Constrain where a request may run and how the gateway ranks the candidates.
Every model is served by one or more endpoints. The gateway picks one for each request. The
provider object narrows the candidates and changes how they are ranked. It never names a
supplier: the gateway chooses who serves a request.
curl https://api.opinference.com/v1/chat/completions \
-H "Authorization: Bearer $OP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-oss-120b",
"messages": [{"role": "user", "content": "Say hi."}],
"provider": {"sort": "price"}
}'The same provider object is accepted on every media route.
Fields
| Field | Values | Effect |
|---|---|---|
zdr | true | Only endpoints verified to retain no prompts or outputs. false asks for nothing. See the note below |
data_collection | allow, deny | deny excludes endpoints that may train on your inputs. allow asks for nothing. See the note below |
region | eu, us, global | Only endpoints labelled with that region. global means endpoints labelled global, not "any region" |
sort | price, latency, throughput | How candidates are ranked. See below |
allow_fallbacks | false | Use one endpoint only. true is the default and asks for nothing |
Any other value of data_collection or region is refused with 400 invalid_request, so a typo
such as "EU" fails loudly instead of matching no endpoint.
No endpoint is verified as retaining nothing today, so "zdr": true fails with
404 no_endpoint_available for every model. "data_collection": "deny" leaves some text models
with no endpoint either. When a filter removes every endpoint, the error message names it, for
example excluded by: data_policy. Check a model with one request before you depend on either
filter.
Sorting
price: cheapest healthy endpoint first.latency: fastest to first token first. Degraded endpoints drop out of the ranking.throughput: highest sustained output rate first.- Not set: a blend of health, speed and price, weighted towards price.
An unknown sort value is ignored and the default ranking applies.
Turning failover off
With "allow_fallbacks": false, the request goes to the best-ranked endpoint only. If that
endpoint fails, you get its error instead of an answer from another endpoint. If no endpoint
passes your filters, the request fails with 404 no_endpoint_available.
Preferences only tighten
Your account, workspace and key can each carry a policy, and the request's preferences apply on
top of them. The most restrictive setting wins. A request can add a constraint but never remove
one: asking for a region outside the ones your key allows, or a looser op.retention than your
key's, is refused with 400 policy_conflict.
Supplier choice is refused
provider.order, provider.only and provider.ignore are refused with 400 invalid_request:
{"error": {"code": "invalid_request", "message": "provider.order is not accepted: the gateway chooses the supplier", ...}}They are refused rather than ignored, so an integration that pinned a supplier elsewhere learns the pin has no effect here.
Accepted but ignored
These fields are accepted and have no effect today:
max_pricequantizationsrequire_parameterspreferred_min_throughputpreferred_max_latencyenforce_distillable_textop.tags
max_price does not cap what a request costs. To limit spend, set a monthly cap on the key. See
Key restrictions and spend caps.
On a media job, each ignored field you sent is listed in op_metadata.policy as
option_ignored:<name>:
"op_metadata": {
"policy": ["option_ignored:max_price", "option_ignored:tags"]
}Chat completions do not report them.