Router quickstart & integration guide

Runix Router is an OpenAI-compatible endpoint in front of many model providers. If your code already calls an OpenAI-compatible API, integration is a configuration change: point the client at Runix and swap the key. This guide covers the quickstart, model selection, streaming, what happens when a provider fails, and the operational details teams ask about. Router is available, with accounts opened by our team, and support comes directly from the engineers.

1. Quickstart

Set your client's base URL to https://router.runixcloud.io/v1 and use a key from the Tokens page of the console. Everything else about your existing integration stays the same.

# cURL
curl https://router.runixcloud.io/v1/chat/completions \
  -H "Authorization: Bearer $RUNIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# OpenAI SDK (Python)
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://router.runixcloud.io/v1",
    api_key=os.environ["RUNIX_API_KEY"],
)
resp = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Hello"}],
)

The same base-URL swap works for any tool that speaks the OpenAI API: LangChain, LlamaIndex, the Vercel AI SDK, or plain HTTP. Replace your-model-id with an id from GET /v1/models or the models catalogue. The Responses API is served at the same base URL, under /v1/responses.

2. Model selection

Every request names its model in the model field, and Router sends it to the provider that serves that model.

• Model ids are the vendors' own. Anthropic models answer to their official hyphenated ids (claude-opus-5, claude-sonnet-5), and other vendors' models keep their catalogue names: there is no Runix-specific alias table to maintain, so an id copied from a vendor's announcement works as-is.
• Discover what a key can call: GET /v1/models with your key returns the model ids that key is allowed to use, so you can list them from code instead of asking us. A request for a model outside that list is refused before it reaches a provider.
• Prices are on the models catalogue, at each vendor's public list price.

3. Streaming

Pass "stream": true and responses arrive as standard server-sent events, exactly as your SDK already expects. Streaming passes through the router rather than being buffered and replayed, including tool-call deltas, so the first token is forwarded as soon as the provider emits it rather than after the response completes. That is a statement about the mechanism, not a performance claim: measure time to first token against the provider directly and you will see what the router costs you.

4. When a provider fails

Each model is served by one provider today, so a provider's failure reaches you, in a form your client already handles:

• The error keeps the OpenAI shape and HTTP status, so the retry and fallback logic in your SDK keeps working unchanged.
• Every response carries a request id (section 6), so a failed call can be traced to that exact request.
• Long answers are not cut off at the gateway: Router waits up to 15 minutes for a response, and a stream that stops at the provider stops for you at the same moment.
• Failover to a second provider is set up per account where it is needed, with the models it covers and the providers it may use named in writing. Without it, keep your own retries.

For the background on failure taxonomy, read Model failover for production LLM traffic; why retries should be a spend budget rather than a count (and which errors deserve one at all) is covered in Retry budgets for LLM APIs. How Router behaves today is on Reliability.

5. Limits, usage and cost

• Per-key limits: each key can carry a spending quota, an expiry date, a list of allowed models and an IP allowlist, set on the Tokens page of the console and changed without a redeploy. A call outside them is refused before it reaches a provider.
• List-price metering (requests are metered per token at the upstream vendors' published rates, with input, output, cached-read and cache-write tokens priced separately) the same structure the vendors themselves publish. We audit the rate table against the vendors' own pricing pages; the mechanics of why token bills diverge from price lists, and how to check one by hand, are in Why your LLM bill doesn't match the price list.
• Usage on every response: the usage object carries the full token breakdown, cached tokens included, so any single request can be reconciled against the rate card without asking us. Billing is usage-based in USD with itemised statements; see Pricing for how quotes work.
• The request log: every call is listed on the Logs page of the console with its key, model, tokens and cost.
• Attribution: issue separate keys per team or product to get cost attribution along the lines your finance team actually asks about; the reasoning is covered in LLM cost attribution.

6. Errors and request ids

Errors come back as JSON in the shape your OpenAI-compatible client already parses: an error object carrying message, type and code.

// missing or invalid key -> HTTP 401
{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 20261030145933...)",
    "type": "runix_error"
  }
}

// a path under /v1 that does not exist -> HTTP 404
{
  "error": {
    "message": "Invalid URL (POST /v1/nope)",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

Two things worth knowing before you write error handling. First, branch on the HTTP status rather than on error.type: the status is what the OpenAI SDKs already map to their own exception classes, and it is the part that will not surprise you. Second, every response carries its request id in the X-Runix-Request-Id header, and an error repeats it inside message; quote it when you contact us and we can trace that exact call.

Paths outside /v1 on this host are not part of the API surface and do not return this envelope. A call refused by a key's limits (section 5) and a call a provider failed (section 4) both arrive in this shape.

7. Data handling

Prompt and response content is processed to serve your request; it is not used to train models and not sold. Operational metadata (usage counts, latency, error codes) is kept to run billing, reliability and support. The full statement is in the Privacy Policy, and the security posture in Security.

If you are evaluating us — or any gateway — the security review an LLM gateway should survive is the list of questions we think you should ask, including of Runix.

8. Getting a key

Accounts are opened by our team: tell us what you are building — models, expected volume, latency needs — or email [email protected], and we reply within one business day and set the account up for you. Evaluation credits are issued on request, so you can test against real traffic before you pay. Once the account exists, keys are created on the Tokens page of the console.