Connect in 60 seconds
Use one key to call supported models through OpenAI-compatible Chat Completions and Responses, or Anthropic Messages. Start with a real request, then use the rest of this page to prepare it for production.
Quickstart
- 1. Create an API key in the console. The full key is shown only once.
- 2. Add credits on the Credits page. Free to sign up, no monthly fee — pay as you go with credits.
- 3. Copy a bare model ID from Models.
- 4. Replace
sk-your-keyandmodel-name, then run the request below.
https://korouter.aicurl https://korouter.ai/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "model-name",
"messages": [{ "role": "user", "content": "Hello" }]
}'Verify the connection
Open Usage after the response arrives. A successful inference row shows its request ID, token breakdown, outcome, and exact amount charged.
Choose an API
Pick the API your client already speaks. KoRouter supports the surfaces below; it is not a replacement for every endpoint offered by OpenAI or Anthropic.
| Method | API | Path | Use it for |
|---|---|---|---|
| POST | Chat Completions | /v1/chat/completions | Most OpenAI SDKs and OpenAI-compatible apps. Start here unless your client requires another API. |
| POST | Responses | /v1/responses | Codex and POST paths it uses, including compact. Every request must carry a top-level model. |
| POST | Messages | /v1/messages | Claude Code, Anthropic SDKs, and applications that use the Anthropic Messages shape. |
| POST | Count tokens | /v1/messages/count_tokens | Estimate Anthropic request tokens. This helper endpoint is free and does not use a concurrency slot. |
| GET | Models | /v1/models | List the currently callable model IDs for this key. |
Authentication. Send the key as Authorization: Bearer sk-… or x-api-key: sk-…. Anthropic SDKs use the second header by default.
Base URL. https://korouter.ai works for every client; the conventional /v1 suffix used by OpenAI-style tools is accepted too.
Connect your tools
Use the matching configuration for Claude Code, Codex, an SDK, or an OpenAI-compatible client that lets you set a base URL. The curl tab includes one minimal request for each supported inference API.
export OPENAI_BASE_URL="https://korouter.ai"
export OPENAI_API_KEY="sk-your-key"Works with any OpenAI SDK or client; the conventional /v1 suffix is also accepted. On Windows, set these with set (CMD) or $env: (PowerShell) instead of export.
Replace sk-your-key with your key and model-name with a bare model ID from Models.
Setting up an editor or a chat app? Step-by-step guides for Cursor, Cline, Aider, Continue, Open WebUI, and the Vercel AI SDK — each with a verify step and troubleshooting — are on the Integrations page.
Configuration notes
On Windows, use set VAR=value in CMD or $env:VAR="value" in PowerShell instead of export.
Keep credentials out of git. User-level files such as settings.json and config.toml may contain a key; never commit them to a project repository.
Parameters & model capabilities
Request fields are forwarded using the selected API shape, but support is model- and provider-specific. An unsupported field may be ignored or rejected upstream, so test the exact model and request shape before moving production traffic.
| Capability | Common fields | Requirement |
|---|---|---|
| Custom tools | tools, tool_choice | The selected model must list tool support. Provider-hosted paid tools follow the separate rules below. |
| Structured output | response_format | Supported formats and JSON Schema behavior vary by model and upstream provider. |
| Reasoning | reasoning, reasoning_effort | Field shape and accepted effort levels depend on the API protocol and model. |
| Multimodal input | message content parts | Send only modalities listed as inputs for the model, using the content-part shape for your chosen API. |
Check Modalities in a model's info panel on Models. The GET /v1/models response is an ID list and does not include that capability metadata.
The public API does not currently expose image-generation or temporary-upload endpoints. Multimodal input, where listed for a model, goes through Chat Completions, Responses, or Messages content parts.
Models & pricing
Model IDs are bare names — claude-fable-5, not provider/model. Browse the model marketplace for input modalities, supported parameters, context limits, and price details, and the status page for live availability and uptime history.
Token prices are shown in USD per 1M tokens. Cache reads, cache writes with TTL variants, and long-context tiers follow the selected model's published price breakdown. KoRouter calculates the charge from the provider usage returned for that request and the price configured for the public model ID.
Use the marketplace as the pricing source of truth instead of keeping a local copy of the catalog. The exact price applied to a completed request is preserved in its Usage detail.
Streaming, reliability & production
Routing. You call a public model ID rather than naming an upstream route. Treat retryable failures as part of the client contract; do not depend on a failed request being replayed transparently.
Streaming. Server-sent events pass through without response buffering. A completed Chat Completions stream includes a final usage chunk. If the client stops reading, KoRouter may continue consuming the upstream stream so it can capture the final usage accurately.
- ModelConfirm that the model is available and lists every modality and parameter your request needs.
- TimeoutSet an explicit client timeout long enough for reasoning models and long generations.
- RetriesRetry transport failures, 502, and 503 with exponential backoff. For 429, use the message and any Retry-After header to choose between backing off and editing the key's spend limit.
- StreamsTreat a stream that ends before its terminal event as incomplete. Disconnecting does not necessarily stop upstream generation; a retry creates a new request that may be billed separately.
- ObserveReview Usage under representative traffic before increasing concurrency or moving production traffic, and retain representative request IDs for support.
Do not retry 400, 401, 403, 404, or 413 without correcting the cause. For a persistent availability issue, retain the request ID from the response or Usage and send it to support@korouter.ai with the model ID and exact error text.
Usage, billing & privacy
Settlement. A forwarded inference request that returns HTTP 4xx or 5xx is settled at zero token charge. Requests rejected before forwarding — for authentication, balance, validation, or limits — may not create a Usage row or request ID. If the upstream or metering stream itself truncates, KoRouter bills only captured usage; closing the client does not guarantee a partial charge because metering continues upstream.
Request details. Expand a row on Usage to see its request ID, endpoint, outcome or finish reason, token breakdown, time to first token, duration, the official reference price, your saving, and exact charge. The request ID is the fastest way for support to locate a recorded call.
App attribution. The App column on Usage shows the application a request declares about itself: send an X-Title: My app header (optionally with HTTP-Referer: https://…), the same convention OpenRouter uses. Requests without these headers show no app; the OpenAI and Anthropic SDKs both accept a default_headers option.
Content privacy. KoRouter keeps the metadata needed for billing and operations, but does not persist prompt or completion bodies. Request content passes through to the provider that serves the model, where that provider's data and retention policies apply. Read the full Privacy Policy.
Credits never expire. When the balance reaches zero, inference endpoints return 403 with the error code INSUFFICIENT_BALANCE ("Insufficient account balance") until you add credits; count_tokens and GET /v1/models remain available.
Errors & limits
| Status | Cause | What to do |
|---|---|---|
| 400 | Invalid request | Fix the JSON body, model field, or unsupported paid feature. |
| 401 | Missing, invalid, or disabled API key | Check the Authorization or x-api-key header; re-enable the key on Keys if it was disabled. |
| 403 | Insufficient balance (code INSUFFICIENT_BALANCE) | Add credits, then submit a new request. The error type is insufficient_quota. |
| 403 | Key expired or not permitted | Extend the key's expiration on Keys, or contact support if the account is restricted. |
| 404 | Unknown path or model | Use a supported endpoint and a model listed on Models. |
| 413 | Request body over 32 MB | Reduce the serialized request payload. |
| 429 | Concurrency limit reached | Reduce parallel requests and retry with backoff. |
| 429 | API key spend limit reached | Raise or remove the key's spend limit before retrying. |
| 429 | Upstream rate limit | Honor Retry-After when present and retry with backoff. |
| 502 | Upstream engine unreachable | Retry with backoff. If the problem persists, retain the request ID and contact support. |
| 503 | Metering or upstream temporarily unavailable | Retry shortly. If the problem persists, retain the request ID and contact support. |
Errors use the native protocol envelope: OpenAI-style { "error": { "message", "type", "param", "code" } } on Chat Completions and Responses, and Anthropic-style on Messages. KoRouter-generated 429 responses distinguish concurrency from key spend limits in the message and do not include a Retry-After header; an upstream 429 and Retry-After header may pass through.
Paid features not included in token pricing
The fields below can create upstream charges outside normal token pricing. Until KoRouter can settle them correctly, the gateway rejects or removes them before forwarding the request.
| Feature | Gateway behavior | Request fields |
|---|---|---|
| Paid service tiers | Rejected with 400 | service_tier: "priority" or "flex" on Chat Completions and Responses. |
| Audio output | Rejected with 400 | Chat Completions requests whose modalities include "audio". |
| Background mode | Rejected with 400 | Responses requests with background: true. |
| Region-pinned inference | Rejected with 400 | Anthropic inference_geo values other than "global". |
| Provider-hosted paid tools | Removed, or 400 if forced | Chat web search; Responses web search, file search, code interpreter, and image generation; Anthropic web search and code execution. A tool_choice that forces a removed tool is rejected. |
API keys & support
The full key is shown once and stored as a hash. KoRouter cannot recover it later, so create a replacement when the original is lost or exposed.
- Keep keys server-sideLoad keys from environment variables. Never ship them in browser code.
- Separate environmentsUse different named keys for production, development, and temporary integrations.
- Bound exposureSet an expiration and cumulative spend limit appropriate for each workload.
- Rotate immediatelyDisable or delete an exposed key, create a replacement, and update every client that used it.
Contact an engineer
Email is the only support channel. An engineer reads every message and replies as soon as possible.
| Address | Use it for |
|---|---|
| support@korouter.ai | Billing questions, failed calls, refunds, and account issues |
| business@korouter.ai | Volume pricing, invoicing, and partnerships |
Include with your message
- Request ID— if the request appears on Usage
- Key name— never send the key itself
- Model ID— the bare model name you called
- Error and expected result— include the exact error text
- Order number— only for a payment question
Never send an API key by email. For refunds, include the order number and review the Refund Policy.