Router

Router lets an application use one R9S-issued Router key and a logical model name while a routing profile selects the execution model and target. Targets can use Token Plan quota, account balance, or an authorized BYOK provider.

Requests go directly to the gateway at https://gw.r9s.ai/v1/chat/completions. The Console manages profiles and keys; it is not an extra inference proxy.

Router keys currently support Chat Completions only, including streaming. They do not support /v1/responses, /v1/messages, embeddings, or native Gemini passthrough. If an agent requires Responses or Messages, use a key and connection that support that protocol instead of a Router key.

Before you start

• Select the organization that owns the profile and request usage.
• An organization OWNER or ADMIN creates routing profiles. Members can create their own Router keys from profiles they can access.
• Prepare each enabled target: usable balance for a balance target, a configured Plan execution key for a Plan target, or an active and authorized BYOK connection for a BYOK target.
• Use only execution models that support Chat Completions. For BYOK, choose a Chat Completions connection or Gemini via the Chat Completions adapter, not a Responses-only or Messages-only connection.

Enabling a target does not create a subscription, top up a wallet, or bypass provider permissions.

Create a routing profile

Open Router in the Console and choose New routing profile.

1. Name the profile and select its strategy.
2. Decide whether to enable Allow request target override.
3. Enable the targets you need. For each target, enter the Logical request model the application will send and its Execution model.
4. For priority routing, use the arrows to arrange targets in selection order.
5. Choose Create immutable profile.

Profiles support up to eight target slots. Balance and BYOK slots may repeat for different mappings; at most one Plan slot is allowed. Fixed routing requires exactly one enabled target. Disable or remove unused defaults, especially the Plan target if you do not have a configured Plan.

Logical and execution models

The logical name is the contract with your application. The execution name must be a real model authorized for the selected target.

For example, separate slots can map the same logical model as follows:

The BYOK ID above is illustrative; replace it with your own connection’s public ID. A logical name does not make different execution models equivalent in output quality, capabilities, or pricing.

The Plan alias in this table is resolved inside Router. It does not allow a standard key to call Plan-only aliases directly, or a direct Plan Key to call the ordinary glm-5.3 ID. See Token Plan for direct-key setup.

Routing strategies

There is no automatic cross-target fallback. If a selected priority target has insufficient balance, exhausted Plan quota, an unavailable BYOK connection, or an upstream error, the request fails. Router does not then call the next target. Retrying the same request with the same profile is not a failover policy and can create additional provider charges if work already started.

Lowest-cost selection uses estimated input length, including tools, and the output limit, with configured time-of-day and context-tier pricing. All comparable prices must use the same currency. Missing, negative, or non-finite prices are not treated as free; only an explicit complete zero price is. If no candidate has usable pricing, selection returns route_cost_unavailable; mixed currencies return route_cost_currency_mismatch. A Plan target can consume allowance even when it does not debit wallet cash.

Create a Router key

In Router, choose Create Router key, select the profile, and optionally set RPM and TPM limits. Save the new secret when it is displayed and keep it on your backend.

Each key uses an execution snapshot of its selected profile, including its version and the caller’s billing context. Profiles in use cannot be edited in place. To change routing, create a replacement profile and Router key, test with limited traffic, update your application’s secret, and revoke the old key.

Do not pass a direct Plan Key or provider secret in the request body. Router resolves the execution identity on the server.

Send a request

The following request assumes your profile maps the logical name glm-5.3:

export R9S_ROUTER_KEY="<R9S_ROUTER_KEY>"

curl https://gw.r9s.ai/v1/chat/completions \
  -H "Authorization: Bearer $R9S_ROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "Explain this route in one sentence."}],
    "max_tokens": 64,
    "stream": false
  }'

Use the logical model configured in the profile even if /v1/models also exposes execution aliases. Model discovery alone does not establish that an ID has a Router mapping. A successful call returns the normal Chat Completions response; enable stream: true and use an SSE-capable client for streaming.

Per-request target override

When Allow request target override is enabled, add one of these values:

X-R9S-Route-Target: plan

Supported values are plan, balance, byok, and auto. Omit the header or use auto to use the full configured strategy. A specific type filters the candidate set; it does not change the strategy, select an arbitrary connection, or grant access to a target absent from the profile. If multiple BYOK slots match, the configured strategy still chooses among them.

A non-automatic override is rejected with route_override_forbidden when the profile disallows it. Invalid values return invalid_route_target. The old X-R9S-Funding-Source name is a compatibility alias; use X-R9S-Route-Target for new integrations.

Client-supplied credentials, API bases, internal route metadata, and fallback configuration cannot override authenticated routing decisions.

Billing, audit, and revocation

• Balance targets use the applicable organization balance admission and billing rules.
• Plan targets use the current eligible Plan execution key and its expiry, blocking, quota, and concurrency checks. Direct Plan requests and Router Plan requests share the relevant Plan concurrency limit; additional Router keys do not create additional allowance or concurrency.
• BYOK targets inject the authorized connection credential and record BYOK usage separately; they do not consume R9S balance or Plan allowance.
• Gateway audit records capture the route decision ID, profile version, logical and resolved models, selected target, and applicable failure phase or error code. Keep your request ID for support correlation; internal decision metadata is not a response-header contract.

Use Revoke on an unused or compromised Router key. REVOKING or Retry cleanup means cleanup is pending, not that remote deletion has completed. The Console distinguishes confirmed gateway revocation from unconfirmed revocation. Wait for confirmation and escalate an unconfirmed revocation rather than assuming access has stopped. Already executing requests may finish.

Troubleshooting

Use Agent Trace for agent request correlation and Monitoring and Operations for broader rollout and incident workflows.