Skip to content
Router One
Skip to content
Router One

Router One Documentation

A concise guide from account setup to calling the OpenAI-compatible API gateway.

Get started

  1. 1

    Create an account

    Open the console and create a Router One account.

    Sign up
  2. 2

    Create an API key

    Generate a project key in Dashboard -> API Keys.

    API Keys
  3. 3

    Send your first request

    Use curl, the OpenAI SDK, or the Anthropic SDK with Authorization: Bearer <key>.

    Quickstart

One-click setup (recommended)

One command installs the CLI, writes the gateway config, and verifies your key with a 1-token test request. Existing config files are backed up automatically.

Create an API key

The key is only inserted into the command locally in your browser; it is never uploaded.

bash
curl -fsSL https://router.one/install/claude-code.sh | bash -s -- sk-your-api-key

Config takes effect immediately — run claude to start.

powershell
$env:ROUTER_ONE_API_KEY = "sk-your-api-key"; irm https://router.one/install/claude-code.ps1 | iex

Config takes effect immediately — run claude to start.

Review the script before running: /install/claude-code.sh · /install/claude-code.ps1

bash
curl -fsSL https://router.one/install/codex.sh | bash -s -- sk-your-api-key

New terminals work right away; in the current one, run source ~/.zshrc (or your shell profile) first, then codex.

powershell
$env:ROUTER_ONE_API_KEY = "sk-your-api-key"; irm https://router.one/install/codex.ps1 | iex

The current session is ready — run codex to start.

Review the script before running: /install/codex.sh · /install/codex.ps1

Connect your client and verify the result

Client integrations

Find your coding tool, SDK, or chat app. Match its URL field and protocol, then follow the setup guide.

Connection troubleshooting

Work through URL, DNS, TLS, HTTP, and model-response checks when the first request fails.

Read your request logs

Understand request IDs, HTTP status, tokens, settlement, and latency. A 200 response alone does not confirm a completed stream.

Example request

bash
curl https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

What is Router One?

Router One is a unified LLM API gateway. It gives your application one OpenAI-compatible endpoint for model calls, smart routing, fallback, budgets, and request-level observability.

Core value

Use one API key and one base URL for common LLM tools and models. Router One handles provider differences, cost tracking, and routing behind the gateway.

Main API entry points:

text
OpenAI-compatible API / Codex CLI / OpenClaw / Hermes Agent:
https://api.router.one/v1

Claude Code / Anthropic-compatible endpoint:
https://api.router.one

API reference

Chat

POST/v1/chat/completions

Create a chat completion — OpenAI Chat Completions compatible, streaming and non-streaming.

POST/v1/messages

Create a message — Claude / Anthropic Messages compatible, for currently listed Claude models (the Claude Code path).

POST/v1/responses

Create a response — OpenAI Responses API compatible, for currently listed GPT-family models (native path for Codex CLI).

Models

GET/v1/models

List the model IDs this key can call — the catalog Codex CLI and Claude Code fetch each session, with ETag / 304 support.

Account

GET/v1/balance

Check the prepaid balance behind this key — poll it from your server and top up before it runs out.

Images

POST/v1/images/generations

Generate images from text — size hints passed to the model as sent, returns URL or base64.

POST/v1/images/edits

Edit reference images with text instructions (image-to-image) — multipart file upload, returns URL or base64.

Videos

POST/v1/videos/generations

Submit a video generation task — async execution, returns a task_id to poll.

GET/v1/videos/generations/{task_id}

Check video generation status — pending / processing / completed, final video URL, or failure reason.

Guides

Quickstart

First request in five minutes — base URLs, curl, OpenAI SDK, Anthropic SDK, streaming.

CLI setup guide

One-click setup for Claude Code and Codex; manual steps for OpenClaw and Hermes Agent.

CC Switch setup guide

Connect Claude Code or Codex to Router One with a desktop app — no manual environment variables.

FAQ & troubleshooting

Base URLs, 401/402/429 debugging, CLI configuration, and per-request costs.

Model catalog

Compare model IDs, pricing, context windows, and capabilities.

Request logs

Filter by model and date, then inspect request IDs, HTTP status, tokens, settlement, and recorded latency.

Common error codes

Common error codes
CodeMeaningWhat to do
401Invalid or missing API keyCheck the Authorization header.
402Insufficient balance or key spend cap reachedTop up, or raise the key's maxSpend — topping up does not lift a key cap.
429Rate limit exceededRead Retry-After and back off; the code names the limit (RATE_LIMIT_EXCEEDED, TOKEN_QUOTA_EXCEEDED, SUBSCRIPTION_QUOTA_EXCEEDED). Contact support to raise limits.
500Internal server errorRetry shortly; contact support if it persists.