The connection test fails
Check the provider key was pasted whole, with no spaces, and that the account has credit with that provider. For a custom endpoint, the base URL must be public HTTPS and end at the API root (usually /v1).
cable QUICKSTART
Bring your own key
Connect the provider account you already pay for, and every preset, lorebook, plugin and profile on Composite works with it, in any frontend. Tokens go on your provider's bill; Composite charges nothing for it.
1. Connect a provider
- Create a Composite account, open the Keys page and choose New key. The key is shown once, so copy it somewhere safe.
- Open the API Keys page and choose Connect a provider.
- Pick your provider, paste its API key, and press Test connection. The test lists the models your key can reach.
- Leave Use it on my key now ticked to bind every key that has no provider yet, then save. A key can also be bound later from its External provider setting.
| Provider | Where to get a key | Notes |
|---|---|---|
| OpenRouter | openrouter.ai/settings/keys | Hundreds of models behind one key; prompt caching on |
| DeepSeek | platform.deepseek.com/api_keys | Caches repeated prompts by itself |
| Anthropic | platform.claude.com/settings/keys | Claude, with prompt caching on |
| OpenAI | platform.openai.com/api-keys | Caches repeated prompts by itself |
| Google Gemini | aistudio.google.com/apikey | Caches repeated prompts by itself |
| Mistral AI | console.mistral.ai/api-keys | |
| Local or OpenAI-compatible | your server | Must be reachable over public HTTPS, for example through a tunnel |
Your provider key stays private It is stored encrypted and is only used to send your own requests. Nobody who applies your published assets ever sees it.
One request per message Composite never retries a failed request on your key and never falls back to another model. A 429 or an error from your provider comes straight back to your frontend, in your provider's own words for 401, 402, 403 and 429. The one exception: if a reply trips Composite's safety canary and the check then clears it, that reply is regenerated once.
2. Pick a model
A key bound to a provider uses that provider's model ids, exactly as the provider names them: deepseek-chat on DeepSeek, anthropic/claude-sonnet-5 on OpenRouter. The Models page has a Your provider view listing everything your provider reported. Frontends that fetch a model list get the same list from GET /v1/models with your Composite key.
3. Use it in your frontend
Nothing changes on the frontend side: paste Composite's URL and your Composite key (not the provider's), then choose a model. Each app has its own guide under All Docs.
Settings
Base URL: https://composite.lucidity.sh/v1
Full URL: https://composite.lucidity.sh/v1/chat/completions (JanitorAI)
API key: your Composite key (cmp-...)
Model: any id your provider listsThen make it yours: open Discovery, find a profile, preset or lorebook you like, and apply it to your key. A profile sets everything at once. The next message from your frontend uses it.
What costs what
| On a key bound to your provider | Who pays |
|---|---|
| Your chat requests | Your provider bill. No Composite daily cap. |
| Presets, prompts, lorebooks, plugins, profiles | Free, always |
| Helper calls (plugin directors, thinking helpers, memory summaries) | Your provider by default, using the key's helper model. The Helper calls setting can move them to Composite's models, billed to your credits or plan. |
| Satori Lite memory | Free |
| Satori, Heavy and Ultra memory | Needs credits or a plan |
| Routers and Leviathan models | Not available on provider keys; use a key without a provider plus credits or a plan |
Prompt caching is switched on where the provider supports it (Anthropic and OpenRouter get cache breakpoints; DeepSeek, Gemini, OpenAI and xAI cache a stable prefix on their own), so long chats cost less on your bill.
Troubleshooting
429 errors
With your own provider there is no Composite daily limit, so a 429 starting "Provider error: Your provider returned 429" is your provider's rate limit. A preprocessing_rate_limited error means one account ran too many lorebook scans or plugin graphs in a minute; it clears on its own.
Model not found
Use the id your provider lists (Models page, Your provider view), not a Composite catalog id. Ids ending in :free are passed to your provider unchanged.
A profile says it needs credits
It uses a premium memory layer, Composite-run helpers or a router model. Apply it anyway and the memory falls back to Satori Lite with a note, or add credits.