Gateway documentation

Build once. Route through Kanonas.

Use one API across OpenAI, xAI, Anthropic, Gemini, Z.AI, and DeepSeek. Kanonas handles cost controls, cache optimization, privacy defaults, and offline evals.

Try an example
6provider families30+documented routes5SDK quickstarts

Providers

Supported provider surfaces.

Core endpoint families with their Kanonas URLs.

Base URLhttps://api.kanonas.ai

Authentication

Drop in with your existing SDK.

Swap the base URL and API key. Keep the client code.

OpenAI SDKAnthropic SDKGemini SDKxAIZ.AI clientsDeepSeekLiteLLM

Quickstart

Get a key, then use your SDK.

Create a Kanonas API key, set the SDK base URL, and choose the model you want to route through Kanonas.

One completion() interfaceLiteLLM
pip install litellm
Base URLhttps://api.kanonas.ai/v1
Model
Python example
from litellm import completion

response = completion(
    model="openai/gpt-5.5",
    api_base="https://api.kanonas.ai/v1",
    api_key="key_your_id.your_secret",
    messages=[{"role": "user", "content": "Say ack"}],
    max_tokens=64,
)

print(response.choices[0].message.content)
Responses APIOpenAI SDK
npm install openai
Base URLhttps://api.kanonas.ai/v1
Model
JavaScript example
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "key_your_id.your_secret",
  baseURL: "https://api.kanonas.ai/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "Say ack",
  max_output_tokens: 64,
});

console.log(response.output_text);
Messages APIAnthropic SDK
npm install @anthropic-ai/sdk
Base URLhttps://api.kanonas.ai
Model
JavaScript example
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "key_your_id.your_secret",
  baseURL: "https://api.kanonas.ai",
});

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 64,
  messages: [{ role: "user", content: "Say ack" }],
});

console.log(message.content[0]?.text);
Generate ContentGemini GenAI SDK
npm install @google/genai
Base URLhttps://api.kanonas.ai
Model
JavaScript example
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "key_your_id.your_secret",
  httpOptions: {
    baseUrl: "https://api.kanonas.ai",
  },
});

const response = await ai.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "Say ack",
  config: { maxOutputTokens: 64 },
});

console.log(response.text);

Reference

Complete gateway endpoint map.

Public model requests can authenticate with Kanonas API keys. Account-management routes require signed-in Firebase auth unless noted.

Gateway

GET/modelsAPI key

Model list alias for clients using the API host.

GET/v1/modelsAPI key

Models available through platform provider routes.

GET/v1beta/openai/modelsAPI key

OpenAI beta compatibility alias.

OpenAI-compatible

POST/v1/responsesAPI key + credits

OpenAI Responses-shaped requests.

POST/v1/chat/completionsAPI key + credits

OpenAI Chat Completions-shaped requests.

POST/v1/embeddingsAPI key + credits

OpenAI Embeddings-shaped requests.

POST/responsesAPI key + credits

Bare Responses alias.

POST/chat/completionsAPI key + credits

Bare Chat Completions alias.

POST/embeddingsAPI key + credits

Bare Embeddings alias.

POST/v1beta/openai/responsesAPI key + credits

OpenAI beta Responses alias.

POST/v1beta/openai/chat/completionsAPI key + credits

OpenAI beta Chat alias.

xAI-compatible

POST/v1/responsesAPI key + credits

xAI Grok Responses through the OpenAI-compatible route.

POST/v1/chat/completionsAPI key + credits

xAI Grok Chat Completions compatibility route.

GET/v1/modelsAPI key

Saved-provider model list including curated xAI text models.

Anthropic-compatible

POST/v1/messagesAPI key + credits

Anthropic Messages-shaped requests.

POST/v1/messages/count_tokensAPI key

Anthropic token counting helper.

Z.AI-compatible

POST/v1/chat/completionsAPI key + credits

GLM chat requests through the OpenAI-compatible route.

GET/v1/modelsAPI key

Saved-provider model list including Z.AI models.

DeepSeek-compatible

POST/v1/chat/completionsAPI key + credits

DeepSeek V4 chat requests with Kanonas credits.

POST/v1/responsesAPI key + credits

Text-only Responses requests bridged to DeepSeek chat.

POST/v1/messagesAPI key + credits

Anthropic-shaped text messages routed to DeepSeek.

POST/v1beta/models/{model}:generateContentAPI key + credits

Gemini-shaped text requests routed to DeepSeek.

Gemini-compatible

POST/models/{model}:generateContentAPI key + credits

Generate Content alias.

POST/v1beta/models/{model}:generateContentAPI key + credits

Gemini v1beta Generate Content.

POST/v1/models/{model}:generateContentAPI key + credits

Gemini v1 Generate Content.

POST/models/{model}:streamGenerateContent501

Streaming disabled for prepaid accounting.

POST/v1beta/models/{model}:streamGenerateContent501

Streaming disabled for prepaid accounting.

POST/v1/models/{model}:streamGenerateContent501

Streaming disabled for prepaid accounting.

GET/models/{model}:cachedContentsAPI key

LiteLLM cache lookup alias.

POST/models/{model}:cachedContentsAPI key

LiteLLM cache setup alias.

GET/v1beta/models/{model}:cachedContentsAPI key

Gemini v1beta cache lookup compatibility.

POST/v1beta/models/{model}:cachedContentsAPI key

Gemini v1beta cache setup compatibility.

GET/v1/models/{model}:cachedContentsAPI key

Gemini v1 cache lookup compatibility.

POST/v1/models/{model}:cachedContentsAPI key

Gemini v1 cache setup compatibility.

POST/v1beta/cachedContentsAPI key

Gemini explicit context cache creation.

GET/v1beta/cachedContents/{cached_content}API key

Read a cached content resource.

POST/interactionsAPI key + credits

Interactions alias.

POST/v1beta/interactionsAPI key + credits

Gemini v1beta Interactions.

POST/v1/interactionsAPI key + credits

Gemini v1 Interactions.

GET/v1beta/interactions/{interaction_id}API key

Read an interaction resource.

DELETE/v1beta/interactions/{interaction_id}API key

Delete an interaction resource.

POST/v1beta/interactions/{interaction_id}/cancelAPI key

Cancel an interaction resource.

Portal account routes

GET/v1/meFirebase or API key

Inspect the authenticated account context.

GET/v1/api-keysFirebase

List Kanonas API key metadata.

POST/v1/api-keysFirebase

Create a Kanonas API key.

DELETE/v1/api-keys/{key_id}Firebase

Revoke a Kanonas API key.

GET/v1/projectsFirebase

List projects.

POST/v1/projectsFirebase

Create a project.

DELETE/v1/projects/{project_id}Firebase

Delete a project and revoke scoped keys.

GET/v1/projects/{project_id}/usageFirebase

Project usage summary.

GET/v1/usageFirebase

Account usage summary.

GET/v1/usage/summaryFirebase

Usage summary alias.

GET/v1/audit-eventsFirebase

Recent account audit events for management actions.

GET/v1/billing/balanceFirebase

Prepaid credit balance and funding policy.

Health

GET/None

Service acknowledgment.

GET/ackNone

Service acknowledgment alias.

GET/healthNone

Health check.

GET/healthzNone

Health check alias.

Limits

Sparse limits with explicit retry headers.

Kanonas does not use blanket per-user quotas for normal model traffic. Limits apply only to unusual request volume, near-empty prepaid balances, or repeated upstream provider failures.

  • outrageous_request_volumeFraud-scale request volume Very high account or API-key request counts can be paused briefly to protect accounts from leaked keys and abusive traffic.
  • prepaid_low_balancePrepaid balance is almost exhausted Credit-funded requests may slow down near a zero balance so concurrent jobs do not accidentally overdraw the account.
  • provider_cooldownProvider route is failing repeatedly Provider traffic can be paused for a provider and model after repeated upstream rate-limit or transient failures.
429rate_limitedRetryable

Wait for the Retry-After value before retrying. Responses also include X-Kanonas-RateLimit-Reason, X-Kanonas-RateLimit-Limit, X-Kanonas-RateLimit-Remaining, and sometimes X-Kanonas-RateLimit-Reset.

Managed credits, request overrides.

Leave funding on auto for the default managed-credit behavior. Add the header only when a request must force a supported funding mode.

Billing summaries show current credits and lifetime credit movement for signed-in accounts.

  • X-Kanonas-Funding: autoUse the default managed-credit behavior.
  • X-Kanonas-Funding: creditsRequire managed billing with prepaid balance.
LiteLLM
import os
from litellm import completion

response = completion(
    model="openai/gpt-5.5",
    api_base="https://api.kanonas.ai/v1",
    api_key=os.environ["KANONAS_API_KEY"],
    messages=[{"role": "user", "content": "Say ack"}],
    extra_headers={"X-Kanonas-Funding": "credits"},
)

print(response.choices[0].message.content)

Security

Account-owned keys, account-scoped traces.

Kanonas keeps public integration instructions separate from private account surfaces. Client apps use Kanonas API keys; provider credentials and trace payloads remain server-side. Trace, feedback, usage, and operational data may be retained and used to improve the product as described in the Privacy Policy and Terms.

  • Managed provider credentialsUpstream platform credentials stay server-side and are never copied into client SDK snippets.
  • Kanonas API keysFull keys are shown once, stored as hashes, and can be revoked from signed-in Settings.
  • Trace accessModel-call payload previews, route decisions, usage, audit events, and feedback stay behind authenticated account access.
  • Audit eventsAccount management actions are logged for signed-in review without storing raw Kanonas API keys, prompts, or responses in audit metadata.
  • Data useKanonas does not offer zero data retention; prompts, outputs, traces, labels, feedback, and usage metadata may be retained and used to operate, secure, evaluate, and improve the product.
  • Public docsCanonical setup guidance is public at /docs; authenticated portal views are marked noindex.

Agent context

Machine-readable docs for LLM agents.

Agents should cite the canonical docs for setup and use the Markdown context files when they need a compact, comprehensive representation of Kanonas.

LLM summary

A compact index of canonical product, docs, API, legal, and discovery URLs.

Open resource

Full LLM context

One comprehensive Markdown file for agents that need setup, endpoints, auth, billing, limits, and traces.

Open resource

Homepage Markdown

Markdown mirror of the public product overview for agents that prefer text extraction.

Open resource

Docs Markdown

Markdown mirror of this documentation page, including security and troubleshooting guidance.

Open resource

Troubleshooting

Fast checks for common gateway responses.

Most integration issues reduce to authentication, funding, provider availability, request shape, rate limits, or upstream provider errors.

401missing_api_keyCheck

Add a full Kanonas API key as bearer auth, x-api-key, or x-goog-api-key.

402funding_requiredCheck

Add prepaid credits before calling model APIs.

403provider_unavailableCheck

Confirm the requested provider has managed billing support.

400invalid_requestCheck

Check required request fields such as model, messages, input, contents, or max tokens.

429rate_limitedCheck

Respect Retry-After and inspect X-Kanonas-RateLimit-Reason before retrying.

501streaming_not_enabledCheck

Send non-streaming prepaid model requests.

502upstream_errorCheck

Check provider status, model availability, and the trace for upstream details.

Beta feature

-or-better model policies.

Append -or-better to an existing model name on any model-bearing endpoint. During beta, Kanonas uses the base model and records the policy in Traces as not rerouted.

Betagpt-5.5-mini-or-betterPassthrough

The request is sent to gpt-5.5-mini today. The trace keeps the original policy so offline evals can label it for future routing decisions.