Using Umbra in SillyTavern

Umbra speaks the OpenAI chat completions API, so SillyTavern needs two things from you: a base URL and a key. Everything else you already have — your cards, personas and lorebooks all work unchanged.

You'll need a key too. Sign in with Discord to make one — new accounts get $2 of credit to try it with, no card.

Step by step

1. Open the API settings. The plug icon in SillyTavern's top bar.
2. Set API to Chat Completion.
3. Set Chat Completion Source to Custom (OpenAI-compatible).
4. Paste the base URL above into Custom Endpoint (Base URL). It ends in /v1 — SillyTavern adds the rest.
5. Paste your key into Custom API Key. It starts with sk-umbra-.
6. Press Connect. The model dropdown fills in. If it stays empty the base URL is wrong — check it ends in /v1 and has no trailing slash.
7. Pick a model, then set max response length — see the next section, because the default will bite you.

Set max response length to at least 512

This is the one setting that will make Umbra look broken when it isn't. DeepSeek V4 Flash and GLM 4.7 Flash are reasoning models: they think before they answer, and that thinking comes out of the same token budget as the reply. Set the limit low and the whole budget goes to reasoning — you get an empty message and it looks like a failure, when what actually happened is the model ran out of room before it started writing.

512 is a safe floor and 1024 is better. You are billed for tokens the model actually produces, not for the ceiling you set, so a generous limit costs nothing on short replies.

Prompt caching does the heavy lifting

A roleplay turn resends the card, the persona, the lorebook and the history every time — so after your first message most of what you send is unchanged, and unchanged context is billed at the cache-read rate. That is roughly a third of the uncached cost, and it is why a $5 plan stretches as far as it does.

Two things spoil it: editing something near the start of your context, and switching models mid-chat. Both invalidate the cache and the next message costs full price. Editing the most recent message is free — that part was never cached.

Anything that talks to OpenAI

Two environment variables:

OPENAI_BASE_URL=https://api.umbraapi.dev/v1
OPENAI_API_KEY=sk-umbra-...

Or from a shell, to check a key works:

curl https://api.umbraapi.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-umbra-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hello"}],"stream":true}'

When something goes wrong

• Empty model list after Connect — the base URL is wrong. It must end in /v1, with no trailing slash.
• 401 — the key is wrong, or it has been revoked. Make a new one; keys are free.
• 402 — out of allowance for today, or no active plan. The message says which. Allowances reset every morning.
• 429 — too fast, too many at once, or spending too quickly. The response carries a Retry-After telling you how long to wait. It does not cost you anything.
• Empty replies — max response length. See above.
• 502 — the upstream model failed. You are not charged; the hold is returned automatically. Check the status page.

What we log

Token counts, model, latency, status code and cost. Not your prompts, not the replies, not your character cards. There is no column in our database that holds message text — that is a schema guarantee, not a policy we could quietly change our mind about. The privacy policy lists every field.