Choosing a provider
Use Auto routing or choose a published computer and model offer at a price you have reviewed.
Choose an enabled model edition first. Then let Router select eligible capacity with Auto, or select one published computer/model offer yourself.
Auto or a specific offer
| Choice | Behavior |
|---|---|
| Auto · default | Omit provider_selection. Router chooses eligible available capacity with the lowest conservative credit reservation; equal rounded reservations rotate. |
| Specific offer | Send its offer_id and displayed pricing_revision. Router accepts only that computer/model offer at that revision. |
Auto uses saved input/output rates, the provider's context bound, and your output limit to calculate a conservative maximum, rounded up to six decimal credits. This is a reservation, not a prediction of the final charge or a ranking by only one displayed rate. The offer must fit your authorized request maximum. Public publication is not required for Auto eligibility.
For the exact model, Auto ranks eligible conservative reservations and manual selection binds the chosen offer and price revision. Eligibility and capacity checks lead to an accepted saved quote or an explicit error, without silent fallback.
The diagram preview uses JavaScript. Read or copy its source below.
Diagram source
flowchart LR accTitle: Auto and manual provider selection accDescr: For the exact model, Auto ranks eligible conservative reservations and manual selection binds the chosen offer and price revision. Eligibility and capacity checks lead to an accepted saved quote or an explicit error, without silent fallback. Auto[Auto routing] --> Check[Eligible capacity] Manual[Chosen offer] --> Check Check -->|Pass| Accept[Accept quote] Check -->|Fail| Error[Explicit error]Discover public offers
In Playground, open the provider picker for your selected model. You can also follow a public provider page at /providers/{handle}. Names, descriptions, websites, and avatars are self-described identities; they do not establish verified reputation, confidential execution, or guaranteed performance.
For an API integration, query discovery at the API origin, outside /v1:
curl --get "${ROUTER_BASE_URL%/v1}/public/provider-offers" \ --data-urlencode 'model=gemma3:1b'The response includes offers, has_more, and next_cursor. Review each offer's public computer name, exact model, separate input/output rates in USD per 1M tokens, availability, and pricing_revision. Pass next_cursor as cursor to load more; a null cursor ends the list. Available offers precede busy and offline offers within each page. Discovery observes capacity and does not reserve it.
Send your selection
Copy the current offer UUID and pricing revision into the chat request:
{ "model": "gemma3:1b", "messages": [{ "role": "user", "content": "Explain retrieval briefly." }], "max_tokens": 128, "provider_selection": { "offer_id": "00000000-0000-4000-8000-000000000001", "pricing_revision": 3 }}The UUID and revision above are synthetic. Use values returned by discovery. Keep the usual authentication, Idempotency-Key, and spending limit headers. You cannot serve your own account's paid requests.
API selection applies to each request. Playground selection lasts for its current conversation. Omitting provider_selection explicitly selects Auto.
Recover deliberately
Router checks the published profile and offer, ownership, exact model revision, current price, and capacity before acceptance. It never silently switches a manual selection to Auto or another offer.
| Error | Next step |
|---|---|
provider_price_changed | Fetch the current offer and review its price before accepting the new revision. |
provider_offer_unavailable | Choose another published eligible offer or explicitly choose Auto. |
selected_provider_unavailable | Wait for the selected computer, choose another offer, or explicitly choose Auto. |
self_provider_only | Choose an offer owned by another account. |
Changing the offer, pricing revision, or routing choice creates a new logical request and needs a new UUID. If an earlier result is uncertain, check its credit receipt first; retries of that request keep the original UUID and unchanged body. See retries and cancellation.
See the provider API reference for discovery fields and the privacy guide for the provider trust boundary.