How sub2api works

01The idea

sub2api is a reverse proxy with a business layer on top. On one side are upstream credentials you own. On the other side are people and programs holding keys that sub2api issued. Between them sit a scheduler, a translator and a ledger.

Everything ships as one Go binary. It serves the Vue admin/user web app, the panel API (/api/v1/…) and the AI gateway (/v1/…, /v1beta/… and others), all from one Gin HTTP server on one port. It needs PostgreSQL for durable data and Redis for everything fast-moving: concurrency slots, sticky sessions, caches and counters.

02Five nouns

Almost every admin screen manages one of these. Once you know how they connect, the rest of the system is easy to follow.

Platforms and the four gateway families

A platform is a provider. Each platform is handled by one of four internal gateway services, which determines the protocol the account speaks.

composite is not a provider. It is a group-only platform that looks at the model name (claude-* → anthropic, gpt-* / o3 → openai, gemini-* → gemini, and so on) or at routes you define, and sends each request to the matching concrete platform.

03Life of a request

Here is what happens when Claude Code sends POST /v1/messages with a sub2api key. Other endpoints follow the same outline.

1. Middleware: size limit, request ID, error logger

   The body is capped (256 MB, 32 MB on text routes). Each request gets an X-Client-Request-ID, which later makes billing idempotent.

2. Authenticate the key api_key_auth.go

   The key is read from Authorization: Bearer, then x-api-key, then x-goog-api-key. sub2api loads the key with its user and group from a cache, then checks: key enabled, IP rules, user active, group enabled, and access to an exclusive group.

   Billing gate: subscription groups need an active subscription that is under its day/week/month limits. Balance groups need a balance above 0. In both modes the key must not be expired or over its quota.

   401 missing or unknown key · 403 insufficient balance / no subscription · 429 limit exceeded · 400 key passed in ?key=

3. Model allowlist and group check

   If the group has a model allowlist, the requested model must be on it; otherwise the response is 404. A key with no group is rejected (403) unless the "ungrouped key scheduling" setting is on. A composite group resolves its target platform at this point.

4. Pick the handler by platform

   The same URL is served by a different handler depending on the group's platform. /v1/messages on an OpenAI-family group goes to the OpenAI gateway, which translates Anthropic to OpenAI and back (see §06).

5. User concurrency slot Redis

   The request takes one of the user's concurrent slots, which are counted across all of that user's keys. If none is free, it waits up to 30 s in a queue of at most 20 extra requests. Streaming clients receive SSE pings every 10 s while they wait.

   429 when the queue is full or the wait times out

6. Billing re-check and in-flight reservation

   Limits are re-checked: subscription windows, balance, per-user platform quotas, the key's 5h/1d/7d windows and RPM. In balance mode, sub2api reserves the estimated cost in Redis (input bytes / 4, plus max_tokens × output price), so parallel requests cannot all spend the same dollar.

7. Compute a sticky-session key

   From Claude Code's session ID in metadata.user_id, or a hash of the prompt-cache blocks, or a hash of IP + user agent + key + prompt. If Redis already binds this conversation to an account, that account is preferred, so Anthropic's prompt cache keeps hitting.

8. Select an account and take its slot gateway_scheduling.go

   The scheduler (see §04) picks a healthy, least-loaded account that supports the model, and takes one of that account's concurrency slots in Redis.

9. Forward upstream

   The request is rebuilt for this account: model name mapping, OAuth token (refreshed if it expires within 3 min), proxy, optional TLS fingerprint, beta-header policy. If the account is a Claude subscription and the client is not Claude Code, the request is rewritten to look like Claude Code: system prompt, metadata.user_id, X-Stainless-* headers.

   On a retryable failure, sub2api records a cooldown on the account, excludes it and goes back to step 8 with another account, up to 10 switches. Once any byte has reached the client, it can no longer switch.

10. Stream back

    SSE events are relayed, mapped model names are changed back to what the client asked for, and token usage is collected from message_start / message_delta. Keepalives are sent every 10 s; after 180 s with no data from upstream the request is aborted. If the client disconnects, sub2api keeps reading the upstream response so the usage can still be billed.

11. Bind the session, release slots, record usage

    The conversation is bound to this account for 1 h. A worker pool computes the cost and charges it in one Postgres transaction, deduplicated by (request_id, api_key_id), then writes a usage_logs row.

04Picking an account

This is the core of the system. For the Anthropic, Gemini and Antigravity families it works in layers; the OpenAI family has its own scoring scheduler (below).

First, which accounts are eligible at all?

Candidates come from a Redis snapshot of the group's accounts, kept current by an outbox worker and rebuilt in full every 5 minutes. An account is schedulable only if all of these hold:

• status = active and the manual schedulable switch is on
• not inside any cooldown: rate_limit_reset_at, overload_until, temp_unschedulable_until
• not expired (enforced only when auto_pause_on_expired is set, which is the default)
• its own USD quota is not exhausted (API-key, Bedrock and service-account types)
• it supports the requested model (an empty mapping allows all models) and has no cooldown for that specific model
• Claude oauth / setup-token only: under its 5-hour cost budget, RPM and max concurrent sessions, if you configured them

Then, the layers

The OpenAI-family scheduler

OpenAI, Grok and the Chinese providers use a different selector. It tries, in order, previous_response_id affinity, then sticky session (and leaves a sticky account that is erroring or slow to first token), then a weighted score over priority, load, queue depth, error rate and time to first token. It keeps the top 7 and picks one of them.

05When upstreams fail

An upstream error can change two things: this request may move to another account, and the account may be benched for a while. The account changes are what make the pool heal itself without manual work.

You can change this per account. Temp-unschedulable rules match an error code plus keywords and bench the account, or just one model, for N minutes. Custom error codes (API-key accounts) make sub2api ignore every status not in your list. Pool mode is for API-key accounts that front another relay: errors are retried on the same account (3 times by default) and the account is never benched.

Keeping OAuth tokens alive

A background job runs every 5 minutes and refreshes any OAuth token that expires within 30 minutes, with per-provider rate limits and circuit breakers. Claude oauth accounts also refresh on demand during a request, under a distributed Redis lock so that only one instance refreshes at a time. A permanent failure (invalid_grant, revoked token) sets the account to error, and you have to re-authorize it. Repeated temporary failures bench it for 10 minutes.

06Protocol translation

Clients and upstreams do not have to speak the same protocol. sub2api converts between them, using the OpenAI Responses format as the common intermediate (pkg/apicompat).

So a Claude Code user can be served by a ChatGPT/Codex account, and an OpenAI-SDK app can be served by a Claude subscription. The Use Key dialog only offers the Claude Code tab on an OpenAI group if the group has allow_messages_dispatch enabled. Images, video, TTS/STT and search endpoints exist for OpenAI and Grok groups.

07How billing works

Every request ends up as a USD amount. The upstream reports token counts, sub2api prices them, applies your markup, and deducts the result from a balance or adds it to a subscription's usage.

Where prices come from

1. The group's own model_pricing card, if set
2. A pricing channel (Admin → Channels → Pricing), with overrides or per-request prices
3. The LiteLLM-format catalogue, synced from Wei-Shaw/model-price-repo on GitHub (hash checked every 10 min) and cached at data/model_pricing.json, merged with a bundled fallback file and your optional pricing.override_file
4. A hard-coded fallback table

Money in

Redeem codes (balance, concurrency, subscription or invitation), promo codes applied at signup, default grants for new users, built-in payments (EasyPay, Alipay, WeChat Pay, Stripe, Airwallex) with subscription plans for sale, and affiliate rebates that users transfer into their balance. For a private, single-operator setup you can ignore all of this and run in RUN_MODE=simple, which logs usage but charges nothing.

08Where state lives

Knowing which store holds what tells you what is safe to wipe, what to back up, and where to make each change.

Startup, in short

main.go checks whether setup is needed. If AUTO_SETUP=true, it installs from env vars (tests the DB and Redis, runs migrations, creates the admin, writes config.yaml and the lock). Otherwise it serves an unauthenticated setup wizard, so never expose an un-installed instance. It then loads the config, builds the object graph with Google Wire, applies migrations under a Postgres advisory lock, starts about 30 background workers (token refresher, ops metrics, cleanup, usage-record pool, backups and others) and serves HTTP. There is no write timeout, because streams can run for minutes.

09Your first hour

The shortest path from a fresh install to a working Claude Code session through your own gateway.

1. Settings → General → API Base URL. Set it to the URL clients will use (for a local install, http://127.0.0.1:8080). The "Use Key" snippets are generated from it; if it is empty they use the current browser origin.
2. Proxies (optional). Add one per subscription if you want each account to call out from a stable IP of its own.
3. Accounts → Add. Pick the platform and type. For a Claude subscription, choose OAuth: sub2api gives you an authorize link, you log in at claude.com, and paste the code back. Prefer oauth over setup-token: it can be refreshed during a request, and a 401 benches it instead of putting it into error. Set its concurrency and priority.
4. Groups → Create. One per platform you serve. Choose standard (balance) or subscription, set the multiplier (1.0 = list price), and link the accounts.
5. Users. Your admin user already exists. Add a balance (Users → adjust) or use simple mode so that billing does not block you.
6. Keys → Create a key with a group. Then use Use Key to get client config, or Import to CC Switch.
7. Test. Send a request, then look at Usage (per request: tokens, list cost, charged cost, account) and Ops (errors, rejected requests, latency).

Pointing clients at it

# site root: no /v1
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
export ANTHROPIC_AUTH_TOKEN="sk-…your sub2api key…"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude

# ~/.codex/config.toml
model_provider = "OpenAI"
model = "gpt-5.5"
[model_providers.OpenAI]
name = "OpenAI"
base_url = "http://127.0.0.1:8080/v1"
wire_api = "responses"
requires_openai_auth = true

# ~/.codex/auth.json
{ "OPENAI_API_KEY": "sk-…your sub2api key…" }

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8080/v1",
                api_key="sk-…your sub2api key…")
client.chat.completions.create(
    model="claude-sonnet-4-5",   # served by whatever the key's group points at
    messages=[{"role": "user", "content": "hi"}])

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:8080"
export GEMINI_API_KEY="sk-…your sub2api key…"
gemini

curl http://127.0.0.1:8080/v1/messages \
  -H "x-api-key: sk-…" -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":64,
       "messages":[{"role":"user","content":"ping"}]}'

# what this key may spend / has spent
curl http://127.0.0.1:8080/v1/sub2api/billing -H "x-api-key: sk-…"

10Gotchas worth knowing

11Code map

Where to look when you want to see how something works.