Using shuntio: a practical manual
From your first key to reading a bill: how the gateway works, what you are charged for, and what to check when a call fails.
shuntio
This is not API reference material — the integration guide covers the endpoints. This page is about operating the service: getting a key, understanding a bill, and diagnosing a failure without guessing. Console labels change from time to time, so where this page names a screen, treat the console as the source of truth.
What shuntio is, and what it is not
shuntio is a gateway. It accepts a request, decides which upstream account should serve it, forwards it, and bills you for the tokens that came back. It does not train models, does not produce output of its own, and is not affiliated with any model vendor.
Two consequences follow, and both matter more than they look:
- The model is the vendor’s. If a model’s behaviour changes upstream — a new default, a stricter refusal, a rate limit — that change reaches you through the gateway unchanged.
- The bill is composed of two numbers. What the model charges per token, and the multiplier of the group that served your request. Neither is a single fixed rate across the whole service.
Getting a key
- Sign in with Google or GitHub. There is no separate password to manage, and no form to fill in.
- Open the API keys screen in the console and create a key. It is shown once — copy it then; it cannot be recovered in plaintext later.
- Create a separate key per project or environment. Keys share one balance, and revoking one leaves the others working, so there is no good reason to run everything off a single key.
The two base URLs
| What you are calling | base_url |
|---|---|
| OpenAI-compatible clients | https://api.shuntio.com/v1 |
| Anthropic-compatible clients | https://api.shuntio.com |
The /v1 is already part of the OpenAI URL. Appending it a second time is a common mistake and
produces a confusing error, because the request that arrives is well-formed but the route is not.
For Claude Code specifically, set ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. The latter is
validated against Anthropic’s own format and rejected before it reaches the gateway.
What you are charged for
Billing is per token, with input and output counted separately. Three things are worth knowing:
Cache reads and writes are billed separately where the model supports them. For a workload with a long, repeated prefix — an agent loop, a large system prompt — the cache line in the request log is often the largest number on the page. If you only look at input and output, you will misread your own bill.
A call that fails before reaching the upstream provider is not billed. A call the upstream provider already served is billed even if the answer was unhelpful, because the tokens were consumed either way.
Credit does not expire, and an idle account costs nothing. There is no subscription to renew and no monthly floor. What you top up stays until you spend it.
Group multipliers are where most of the price difference lives. The same model can appear in more than one group at different multipliers; the group that served your request is recorded per call in the request log, so a surprising charge can always be traced to a specific group.
Choosing a model
The catalog is published as machine-readable JSON at /models.json. Copy an id from
there byte for byte. Two rules save time:
- An id outside the catalog is rejected, not mapped to a fallback. There is no silent substitution, so a typo surfaces immediately rather than quietly serving a different model.
- Treat the catalog as a snapshot. Models are added and withdrawn.
/models.jsoncarries asynced_atdate for exactly this reason; check it before assuming a model is still there.
Reading a request log
Every call leaves a row. The fields that answer most questions:
| Field | What it tells you |
|---|---|
| Model id | What actually served the call, after upstream routing |
| Group | Which multiplier was applied |
| Input / output tokens | The two numbers the charge is built from |
| Cache read / write | Whether a repeated prefix was actually cached |
| Credit deducted | The final amount, already multiplied |
| Latency | Time to first byte and total, useful for spotting a bad route |
| Status | The HTTP status from upstream, not a rewritten one |
When a bill looks wrong, reconcile from the log rather than from a total. A total tells you the sum was computed; the rows tell you whether it was computed from the right inputs.
Troubleshooting, in the order worth checking
401 — the key is the problem. Either it was revoked, it was mistyped, or the header is missing
Bearer. The key itself is only valid on the host that issued it.
A model error naming the id — the model is not in the catalog. Read /models.json and compare
the string exactly. Case and separators matter.
A quota or balance error — the account ran out. Top up in the console; keys stay valid and no code changes.
Timeouts with no upstream status — the upstream did not answer. This is the failure mode a gateway cannot hide. Try another model in the same group; if only one model fails, the problem is upstream of us. If the whole group fails, tell support with the request id.
Streaming that stops mid-response — the upstream connection dropped. The partial output you received was still billed, because the tokens were generated. Retrying the whole request doubles the cost; retry only from the point of failure where your client supports it.
Limits worth knowing before you depend on this
- No SLA. There is no uptime commitment and no service credit for downtime. If your workload needs a contractual guarantee, buy from the model vendor directly.
- Caching behaviour is not identical to the official API. Check the cache rates for your model before assuming a prompt-cache strategy will pay off the same way.
- Upstream policy reaches you. An upstream account restriction, a model withdrawal, or a changed rate limit shows up here as a failure or a price change, not as something the gateway can prevent.
- Rate limits apply per key and per group. If you are hitting them, adding a key does not increase a per-account ceiling.
Where to look next
- Integration guide — base URLs, SDK snippets, client configuration
- /models.json — the current catalog with per-model rates
- Pricing — rates by group, including peak-hour multipliers
- Terms of service and privacy policy — what is promised, and what is not
If something here contradicts what the console shows, the console is right and this page is out of date. Tell us, and it gets fixed.