# qlaud

> qlaud is the **AI billing router** — every frontier model behind a single per-user-billed API surface that's drop-in compatible with the official OpenAI / Anthropic / ElevenLabs / Vercel AI / LangChain / LlamaIndex SDKs. Mint a per-user `qlk_live_…` key with a hard spending cap, point any SDK or coding tool at `api.qlaud.ai`, and at month-end pull per-user usage to push to your billing tool of choice (Stripe, Paddle, Lemon Squeezy, custom). One key, one wallet, native SDK shapes preserved.

Use qlaud when you're shipping a product that wraps frontier AI and selling it to end-users. Instead of integrating each provider, building per-user usage tracking, enforcing spend caps, and reconciling N invoices — you mint a key per signup, and qlaud handles the gateway, the meter, the cap, and the audit trail. You keep the customer relationship.

## Product

- [Home](https://qlaud.ai/): Three-step walkthrough — mint a per-user key with a cap, drop into any official SDK (OpenAI / Anthropic / ElevenLabs / Vercel AI SDK / LangChain.js / LlamaIndex / ElevenLabs Python), pull per-user usage at month-end. Plus a CLI section showing how to point Claude Code, Codex, Aider, Cline, and Cursor at qlaud.
- [Models](https://qlaud.ai/models): The hand-picked frontier catalog. Every model id shown is the EXACT provider-native string a customer would already use with the official SDK — no qlaud-specific slugs to learn.
- [Pricing](https://qlaud.ai/pricing): Prepaid wallet, no tiers, flat 7% markup over upstream cost. We bill you for the wallet; you bill your end-users any margin you want on top.
- [Blog](https://qlaud.ai/blog): Engineering posts on the gateway, billing patterns, and per-tool integration guides.
- [Security](https://qlaud.ai/security): Auth flow (custom `qlk_live_…` keys, hashed in D1), upstream key custody, billing isolation (Durable Objects), audit logging, scope separation between master and standard keys.
- [Status](https://qlaud.ai/status): Live status of the qlaud edge worker.
- [Docs](https://docs.qlaud.ai): Full guides + API reference (Mintlify-hosted).

## Surfaces

All endpoints accept ANY of these auth header conventions so the official SDKs work without monkey-patching:
- `x-api-key: qlk_live_...` (Anthropic-style)
- `xi-api-key: qlk_live_...` (ElevenLabs-style)
- `x-goog-api-key: qlk_live_...` (Google-style)
- `Authorization: Bearer qlk_live_...` (OpenAI / xAI / DeepSeek / most)
- `Authorization: Token qlk_live_...` (Deepgram-style)

### Inference

- POST [https://api.qlaud.ai/v1/messages](https://api.qlaud.ai/v1/messages): Anthropic Messages API — Claude Code, @anthropic-ai/sdk, Cursor, Cline, Aider, LangChain @langchain/anthropic. Set `ANTHROPIC_BASE_URL=https://api.qlaud.ai`. Native passthrough for Anthropic models — `cache_control`, image blocks, thinking blocks all preserved verbatim.
- POST [https://api.qlaud.ai/v1/chat/completions](https://api.qlaud.ai/v1/chat/completions): OpenAI Chat Completions — openai-py, openai-node, @ai-sdk/openai, LangChain ChatOpenAI, LlamaIndex, LiteLLM. Set `base_url=https://api.qlaud.ai/v1`.

### Multi-modal

- POST [https://api.qlaud.ai/v1/images/generations](https://api.qlaud.ai/v1/images/generations): OpenAI-shape image generation (gpt-image-1).
- POST [https://api.qlaud.ai/v1/audio/speech](https://api.qlaud.ai/v1/audio/speech): OpenAI-shape TTS (gpt-4o-mini-tts).
- POST [https://api.qlaud.ai/v1/audio/transcriptions](https://api.qlaud.ai/v1/audio/transcriptions): OpenAI-shape STT (whisper-1).
- POST [https://api.qlaud.ai/v1/embeddings](https://api.qlaud.ai/v1/embeddings): OpenAI-shape embeddings (text-embedding-3-large).
- POST [https://api.qlaud.ai/v1/videos](https://api.qlaud.ai/v1/videos): OpenAI Sora (sora-2 / sora-2-pro).

### Provider-native passthrough

When you want a provider's full native API (custom voice cloning, real-time STT, citations, etc.), hit it under qlaud's domain to keep the billing trail:
- /elevenlabs/* → ElevenLabs (voice cloning, sound effects, real-time TTS streaming)
- /deepgram/* → Deepgram (real-time websocket STT, diarization)
- /perplexity/* → Perplexity (web-grounded answers with citations)
- /cartesia/*, /minimaxi/*, /google-ai-studio/*, /grok/*, /alibaba-cloud/*, /moonshot/*, /anthropic/*, /openai/*, /deepseek/*, /groq/*, /mistral/*, /cerebras/* — full native API for each.

### Key + billing management

These require a master (admin-scoped) qlaud key:
- POST [https://api.qlaud.ai/v1/keys](https://api.qlaud.ai/v1/keys): Mint a per-user key. Body: `{name, scope: 'standard'|'admin', max_spend_usd?}`. Returns the secret ONCE.
- GET [https://api.qlaud.ai/v1/keys](https://api.qlaud.ai/v1/keys): List all keys you've minted.
- DELETE [https://api.qlaud.ai/v1/keys/:keyId](https://api.qlaud.ai/v1/keys/:keyId): Immediate revocation (cache cleared on revoke).
- GET [https://api.qlaud.ai/v1/usage](https://api.qlaud.ai/v1/usage): Per-key + per-model spend rollup. Optional `from_ms` / `to_ms` query params.
- GET [https://api.qlaud.ai/v1/keys/:keyId/usage](https://api.qlaud.ai/v1/keys/:keyId/usage): Drill-down for a single key (events, cost, cap progress).

### Discovery

- GET [https://api.qlaud.ai/v1/catalog](https://api.qlaud.ai/v1/catalog): Public model catalog as JSON. `?include_latency=true` adds live p50 TTFT.
- GET [https://api.qlaud.ai/v1/models](https://api.qlaud.ai/v1/models): Anthropic-shape OR OpenAI-shape model list (content-negotiated by `anthropic-version` header).
- GET [https://api.qlaud.ai/healthz](https://api.qlaud.ai/healthz): Health probe.

## Substrate (agentic capabilities)

qlaud is also a **stateful agentic substrate**, not just an inference proxy. The /v1/threads + /v1/tools + /v1/mcp-servers + /v1/search endpoints together let you build agents that hold history across turns, call tools (yours, ours, or any MCP server), and do semantic retrieval — all per-end-user-billed through the same key.

### Threads — stateful conversations with end-user attribution

- POST [https://api.qlaud.ai/v1/threads](https://api.qlaud.ai/v1/threads): Create a thread. Optional `{end_user_id, metadata}` for trusted session context that's spliced into tool calls (so the model can't be prompt-injected into looking up someone else's data).
- POST [https://api.qlaud.ai/v1/threads/:id/messages](https://api.qlaud.ai/v1/threads/:id/messages): Send a message. Body controls which tools the model sees via `tools_mode`:
  - `dynamic` (default when `tools` absent): inject 4 meta-tools (qlaud_search_tools, qlaud_get_tool_schemas, qlaud_multi_execute, qlaud_manage_connections). Bounded token overhead; end-users connect their own MCP accounts inline. Best for consumer-facing apps.
  - `tenant`: auto-attach EVERY tenant-shared tool the developer owns (built-ins, tenant-mode MCP servers, webhook tools). No per-message ID enumeration. Best for company-internal agents — "use OUR tools every turn".
  - `explicit`: exactly the IDs in the `tools` field. Surgical control.
- GET [https://api.qlaud.ai/v1/threads/:id/messages](https://api.qlaud.ai/v1/threads/:id/messages): Full audit trail including tool_use + tool_result blocks.
- See: [https://docs.qlaud.ai/api-reference/threads](https://docs.qlaud.ai/api-reference/threads), [https://docs.qlaud.ai/api-reference/tools-modes](https://docs.qlaud.ai/api-reference/tools-modes)

### Tools — three tool kinds, one registration endpoint

- POST [https://api.qlaud.ai/v1/tools](https://api.qlaud.ai/v1/tools): Register a tool. Three shapes:
  - **Built-in** (`provider: "qlaud-builtin/<slug>"` + `config`): qlaud hosts the dispatch handler. 14+ catalog entries — Resend email, Twilio SMS, Linear/GitHub/Zendesk tickets, Slack, Notion, Brave web search, OpenAI image-gen, E2B code execution, plus the universal http-call wrapper.
  - **Webhook** (`webhook_url` + `input_schema`): you host the handler, qlaud signs every dispatch with HMAC-SHA256.
  - **Custom HTTP endpoint** (`provider: "qlaud-builtin/http-call"` + templated config): wrap ANY REST endpoint with a JSON config — no webhook needed. Templated URL/headers/body with auto-injected end-user session context (`{{end_user.id}}`, `{{end_user.metadata.X}}`) and `lock_input_fields` to prevent prompt-injection redirect attacks.
- GET [https://api.qlaud.ai/v1/builtins](https://api.qlaud.ai/v1/builtins): Public catalog of qlaud-hosted handlers. Each entry includes `config_schema` (JSON Schema) so a UI can render a registration form.
- GET [https://api.qlaud.ai/v1/tools](https://api.qlaud.ai/v1/tools), DELETE [https://api.qlaud.ai/v1/tools/:id](https://api.qlaud.ai/v1/tools/:id): List + soft-revoke.
- See: [https://docs.qlaud.ai/api-reference/tools](https://docs.qlaud.ai/api-reference/tools), [https://docs.qlaud.ai/api-reference/builtins](https://docs.qlaud.ai/api-reference/builtins), [https://docs.qlaud.ai/api-reference/http-call](https://docs.qlaud.ai/api-reference/http-call)

### MCP — Model Context Protocol servers (your own + curated catalog)

- POST [https://api.qlaud.ai/v1/mcp-servers](https://api.qlaud.ai/v1/mcp-servers): Register any MCP server URL OR a curated catalog slug (Notion, Stripe, GitHub, Linear, Slack, Salesforce, HubSpot, Asana, Jira, Airtable, Intercom — 100+ entries). Two auth modes: `tenant` (developer's account, all end-users share) or `per_user` (each end-user OAuths their own account inline via `qlaud_manage_connections.connect`).
- GET [https://api.qlaud.ai/v1/mcp-catalog](https://api.qlaud.ai/v1/mcp-catalog): Browse the curated catalog (also visible at [https://qlaud.ai/connectors](https://qlaud.ai/connectors)).
- See: [https://docs.qlaud.ai/api-reference/mcp](https://docs.qlaud.ai/api-reference/mcp), [https://docs.qlaud.ai/api-reference/mcp-catalog](https://docs.qlaud.ai/api-reference/mcp-catalog)

### Semantic search over thread history

- GET [https://api.qlaud.ai/v1/search](https://api.qlaud.ai/v1/search): Vector search across every prior thread message, scoped to the calling key (or end_user_id). Backed by Cloudflare Vectorize; no infrastructure for you to operate.
- See: [https://docs.qlaud.ai/api-reference/search](https://docs.qlaud.ai/api-reference/search)

### How to use these together

The substrate compounds. A typical AI app:
1. On user signup, mint a per-user qlaud key with a spending cap.
2. On chat session start, `POST /v1/threads` with `end_user_id` + metadata.
3. Pre-register company tools in the dashboard's "Connect with your company's key" section. Use `tools_mode: "tenant"` so the model gets them on every message — no per-request ID enumeration.
4. For end-user-owned data (their Notion, Stripe, GitHub), use `tools_mode: "dynamic"` — end-users connect their own accounts inline.
5. Wrap arbitrary internal APIs with `qlaud-builtin/http-call` — paste a JSON config, no webhook to host.
6. `POST /v1/threads/:id/messages` per turn. qlaud handles dispatch, retries, audit trail, billing.

## Frontier model catalog

Hand-picked, not a marketplace. Every model id below is the exact string you'd pass to the official provider SDK — no qlaud-specific slugs.

- Claude Fable 5 — `claude-fable-5` (Anthropic, most capable model, 1M context, native passthrough preserves cache_control + betas)
- Claude Opus 4.8 — `claude-opus-4-8` (Anthropic, current flagship Opus, 1M context, native passthrough)
- Claude Opus 4.7 — `claude-opus-4-7` (Anthropic, 87.6% SWE-Verified, native passthrough preserves cache_control)
- Claude Sonnet 4.6 — `claude-sonnet-4-6` (Anthropic, vision-capable, native passthrough)
- GPT-5.4 — `gpt-5.4` (OpenAI, frontier general)
- GPT-5.4 mini — `gpt-5.4-mini` (OpenAI, faster + cheaper)
- DeepSeek V3 — `deepseek-chat` (DeepSeek)
- DeepSeek R1 — `deepseek-reasoner` (DeepSeek, reasoning)
- Gemini 3 Pro — `gemini-3-pro-preview` (Google AI Studio)
- Grok 4.20 — `grok-4.20-0309-reasoning` (xAI)
- Qwen Coder Plus — `qwen-coder-plus` (Alibaba)
- Kimi K2.6 — `kimi-k2.6` (Moonshot)
- MiniMax M2 — `MiniMax-M2` (MiniMax)
- Sora 2 / Sora 2 Pro — `sora-2` / `sora-2-pro` (OpenAI video)
- gpt-image-1 (OpenAI image gen)
- whisper-1 (OpenAI STT, batch)
- nova-3 (Deepgram STT, real-time)
- text-embedding-3-large (OpenAI embeddings)
- eleven_multilingual_v2 / eleven_turbo_v2_5 (ElevenLabs TTS)
- sonar-pro (Perplexity, web-grounded search)

## Per-user billing primer

The headline workflow:
1. Sign up at qlaud.ai → mint a master (admin) key in /keys → store as `QLAUD_MASTER_KEY` server-side.
2. On user signup in YOUR app: `POST /v1/keys` with `{name: 'user_42', max_spend_usd: 5}` → store the returned `secret` (qlk_live_…) with that user.
3. That user's app calls qlaud with their key. Cap is enforced gateway-side; over the cap returns 402.
4. Month-end: `GET /v1/usage` → response includes `by_key[]` with `cost_micros` per key. Loop, push to your billing system (Stripe, Paddle, Lemon Squeezy, in-app invoicing — any).

You see only your own users' usage. Master scope gates the keys+usage endpoints; standard keys are inference-only.

## CLI / IDE integrations (env-var swap)

- Claude Code: `export ANTHROPIC_BASE_URL=https://api.qlaud.ai && export ANTHROPIC_API_KEY=qlk_live_...`
- OpenAI Codex CLI: register qlaud as a model_provider in `~/.codex/config.toml`
- Aider: `export OPENAI_API_BASE=https://api.qlaud.ai/v1 && export OPENAI_API_KEY=qlk_live_... && aider --model openai/gpt-5.4`
- Cline (VSCode): in-extension settings panel — pick Anthropic or OpenAI Compatible provider, paste qlaud URL + key
- Cursor IDE: Settings → Models → Override OpenAI Base URL → `https://api.qlaud.ai/v1`

## Engineering blog

- [How I cut my AI app's OpenAI bill 60% with per-user API keys](https://qlaud.ai/blog/cut-openai-bill-per-user-keys): A $5,247 bill I couldn't attribute. The naive Postgres approach that didn't scale. The per-user-keys pattern that fixed it — with the actual numbers, code, and the 60% cost reduction in 6 weeks.
- [The hidden infrastructure you build when you ship AI chat](https://qlaud.ai/blog/hidden-infrastructure-ai-chat): A chat textarea is a 30-minute build. The persistence, streaming reassembly, dedup, tool-call audit trail, and history endpoint that turn it into a real product is 3+ weeks. A walkthrough of what breaks, in what order, and how to skip most of it.
- [qlaud vs OpenRouter: when to pick which](https://qlaud.ai/blog/qlaud-vs-openrouter): OpenRouter is a router. qlaud is a router PLUS per-user billing, threads, semantic search, and 100+ vendor MCP connectors — one platform, one bill.
- [qlaud vs LiteLLM: same proxy idea, different layer](https://qlaud.ai/blog/qlaud-vs-litellm-managed-vs-self-hosted): LiteLLM is a self-hosted proxy. qlaud is hosted with per-user billing, threads, semantic search, and 100+ tool connectors built in. When to pick which.
- [47 tools out of the box: 35 vendor MCP connectors + 12 first-party builtins](https://qlaud.ai/blog/47-tools-out-of-the-box-mcp-catalog-plus-builtins): Every qlaud account ships with 100+ vendor MCP connectors and 12 first-party builtins (E2B, web search, image gen, email). Auto-discovered.
- [Stop building auth, billing, and a database for your AI app](https://qlaud.ai/blog/stop-building-ai-app-backend-billing-database): The default AI-app stack is Clerk + Stripe + Postgres + a custom proxy. qlaud collapses three of those four into one platform. You write the chat UI.
- [Build a ChatGPT clone in 200 lines (no database)](https://qlaud.ai/blog/build-chatgpt-clone-200-lines-no-database): End-to-end Next.js + Clerk + qlaud tutorial: per-user keys, streaming chat with auto-history, semantic search, 100+ connectors live — no Postgres, no Pinecone.
- [Per-user AI billing in 5 minutes (without rebuilding metering)](https://qlaud.ai/blog/per-user-ai-billing-in-5-minutes): The four-step playbook with qlaud — mint per-user keys, cap spend, meter usage, bill — using the official SDKs you're already using. Ship in 5 minutes.
- [Point your coding agent at qlaud — Claude Code, Codex, Aider, Cline, Cursor](https://qlaud.ai/blog/use-your-coding-agent-with-qlaud): Point Claude Code, Codex, Aider, Cline, or Cursor at qlaud — one base URL, per-user spend caps, every frontier model. Setup snippets for each agent.
- [Building qlaud on Cloudflare AI Gateway in five days](https://qlaud.ai/blog/building-qlaud-on-cloudflare-ai-gateway): How qlaud was built on Cloudflare AI Gateway in five days — architecture, primitives, and the trade-offs that made shipping per-user billing fast.
- [Why Claude Code on DeepSeek V3 costs 30× less than Claude direct](https://qlaud.ai/blog/why-claude-code-on-deepseek-costs-30x-less): DeepSeek V3 via qlaud delivers Claude-class agentic coding for ~30x less than Claude direct. The pricing math and cap pattern that make it work.

## Community

- Reddit: [r/qlaud](https://www.reddit.com/r/qlaud) — official subreddit. Tutorials, integration patterns, deploy stories, feature requests, and changelog posts all land here. The maintainer team posts directly; users reply and cross-post into adjacent subs (r/programming, r/MachineLearning, r/LocalLLaMA, r/SideProject).
- X: [@qlaud](https://x.com/qlaud) — release notes, model availability, status incidents.

## Contact

- Security / vuln disclosure: security@qlaud.ai
- General: hello@qlaud.ai