Developers · Documentation

Documentation

One API key, one wallet, and OpenAI-compatible access to frontier models. Start with a base URL change, then scale with routing, billing headers, and retry-safe requests.

vr_sk_

One key for every model

OpenAI + Anthropic

Compatible endpoints

$1 = 1M

Quota micros per USD

Base URL · OpenAI-compatible

https://api.virouter.com/v1

Start quickstart Tool setup guides Gateway deep dive

Quickstart

Three steps to your first routed request. If you already use the OpenAI SDK, only the base URL changes.

Create an API key

Generate a Virouter virtual key from the dashboard. Keys can be separated by environment and revoked without changing provider accounts.

Open API keys

Point your client at Virouter

Set the OpenAI-compatible base URL to https://api.virouter.com/v1. Existing SDKs, CLIs, and frameworks keep the same request shape.

Send your first request

Pass a public model id. Virouter authenticates, routes to an available upstream, meters token usage, and settles the cost against your wallet.

First request · curl

curl https://api.virouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vr_sk_xxxxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Summarize what Virouter does." }
    ]
  }'

Authentication

Every gateway request uses a Virouter virtual API key. Provider keys stay server-side and never enter your application.

Virtual keys

Keys start with the vr_sk_ prefix and carry their own usage trail, rate limits, and revocation state.

Authorization header

Send the key as a Bearer token on every request.

Authorization: Bearer vr_sk_xxxxxxxxxxxx

Keep keys server-side. Store them in environment variables, CI secrets, or a secrets manager, and share only masked prefixes with support.

Endpoints

One gateway, two API dialects. OpenAI-compatible traffic uses /v1; Anthropic Messages traffic uses the same host for Claude clients.

POST/v1/chat/completions

OpenAI-compatible chat completions for GPT and Claude model ids.

POST/v1/responses

Responses API shape for clients built on the newer OpenAI endpoint.

POST/v1/messages

Anthropic Messages API surface for Claude Code and Claude Max style clients.

GET/v1/models

Lists public model ids currently available through Virouter.

POST/v1/redeem

Redeems a gift code into Billing USD Quota on the authenticated account.

SDKs & tools

Virouter is a drop-in target: keep your SDK, change the base URL. Claude models can run through the OpenAI-compatible surface.

TypeScript · OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.VIROUTER_API_KEY,
  baseURL: "https://api.virouter.com/v1",
});

const reply = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello Virouter" }],
});

console.log(reply.choices[0].message.content);

OpenAI SDK · Python Claude via OpenAI SDK Claude Code setup Tool setup guides Image generation

Routing

Virouter routes each request to an available upstream model automatically. If a provider is temporarily unavailable, the gateway can retry through another healthy route without client-side changes.

Validate

Check the virtual API key, rate limit state, request shape, and model id before forwarding.

Route

Choose an available upstream route for the requested public model id.

Settle

Read token usage, settle wallet cost, and return request metadata in headers.

Billing USD Quota

All usage is metered in USD quota micros. You pay for real returned tokens, with separate cache pricing where upstreams expose it.

USD quota micros

1 USD equals 1,000,000 micros, allowing balances and request costs to settle precisely.

Reservation

Virouter reserves a worst-case estimate before forwarding so unpayable requests fail early.

Settlement

After the response, actual usage is charged and unused reservation is released.

Response headers

Every gateway response includes cost, remaining balance, token usage, and request identifiers for dashboards and support workflows.

x-virouter-cost-usd

Actual cost settled against the wallet.

x-virouter-remaining-usd

Wallet balance after settlement.

x-virouter-input-tokens

Input tokens reported for the call.

x-virouter-output-tokens

Output tokens generated by the call.

x-virouter-total-tokens

Total tokens billed for the request.

x-virouter-request-id

Request id for support and log correlation.

Reliability

Use idempotency keys and conservative retry rules so client retries do not double-charge or duplicate work.

Idempotent requests

Send an Idempotency-Key header for retry-safe logical operations. The same key with a different body returns 409.

Idempotency-Key: 8f3d2c1e-order-42

Retry strategy

Retry 429 and 503 with exponential backoff. Treat 401 and 402 as configuration or balance errors that require user action.

Error codes

Errors follow standard HTTP semantics and include machine-readable messages for client-side handling.

401

API key is missing, invalid, revoked, or inactive.

402

Insufficient Billing USD Quota for the requested call.

409

Idempotency key was reused with a different body, or processing is still in progress.

429

Rate limit reached. Wait for the reset window before retrying.

503

No available upstream route for the requested model. Retry later.