Providers & keys¶
A provider is the service that powers an NPC — the LLM for its brain, and (optionally) a voice service for speech. You register a provider once with its API key; your NPCs then reference it by a handle.
Keys never ship in your world
API keys are stored encrypted on your SDK account, server‑side — they are not baked into your world bundle. NPCs reference a provider only by its handle (e.g. my-llm). Never paste a key into a script, a component field, or any asset that uploads with your world — bundle contents are readable by others.
Register a credential (Provider Manager)¶
Open the Provider Manager (Window ▸ SocialScape ▸ Provider Manager), sign in with your SDK token if prompted, and Add an entry. Every entry has a Handle (what you reference, e.g. my-llm), a Type, and a key/secret stored encrypted on your account. The other fields depend on the type:
| Type | Fields | Powers |
|---|---|---|
| Text | Endpoint · Model · Reasoning | the NPC's brain (LLM) |
| Voice | Endpoint · Model (optional model_id) · Default Voice (e.g. ara) · Serialize synths |
NPC speech / TTS — see Voice |
| HTTP | Base URL · Auth scheme | a service your scripts call with HTTP.* |
- Text → Reasoning picks how this model expresses hidden "thinking": Auto (guess from the model name), Thinking flag (Gemma/Qwen/local), Reasoning effort (OpenAI o‑series), or None. Pick it explicitly to avoid mis‑detection. How much an NPC thinks is its own per‑NPC
reasoningdial (AI NPCs). - Voice → Serialize synths — turn on for a single‑stream /
--parallel 1self‑hosted TTS server (e.g. Orpheus) so two NPCs never generate at once and collide; leave off for cloud TTS (ElevenLabs/Cartesia/OpenAI) that handles concurrent requests. - Voice → Default Voice records the provider's voice (e.g.
ara); at runtime the voice actually used is the NPC's ownvoiceName, so set that on each NPC (Voice). Model is an optional TTSmodel_id, sent only when set (leave blank if your provider selects by voice alone). - HTTP → Auth picks how the key is attached (
bearer/apikey/supabase/header/none). Full detail + the secure script usage is on the HTTP & Supabase page.
Leaving the key blank when editing an existing entry keeps the stored key unchanged.
Test before you rely on it
Each saved entry has a Test button — and the HTTP add‑form has a Test too — that checks reachability/auth from your account and reports the status (e.g. 200 OK, or 401/403 = auth rejected). Use it to confirm a credential works before uploading a world. (The saved‑row HTTP test needs the SDK API updated server‑side; the add‑form test runs locally.)
What can I plug in?¶
Text (the brain) — anything that speaks the OpenAI chat API: OpenAI, xAI/Grok, local runtimes (Ollama, llama.cpp, LM Studio, vLLM), or your own server. Just set the Endpoint to its /v1/chat/completions URL (a base URL works too — the path is added for you) and the Model. Self‑hosted/no‑auth endpoints can leave the key blank.
Voice (TTS) — pick the Provider from the dropdown:
| Provider | Use for | Default Voice = |
|---|---|---|
| Orpheus (self‑hosted) | your own TTS box (OpenAI /v1/audio/speech) |
a name (tara, …) |
| OpenAI | hosted OpenAI TTS | a name (alloy, nova, …) |
| OpenAI‑compatible | any custom /v1/audio/speech server |
depends on your server |
| ElevenLabs | ElevenLabs | the voice id |
| Cartesia | Cartesia | the voice id |
| Grok (xAI) | xAI voices | ara/eve/leo/rex/sal |
Self‑hosted? Pick the matching vendor, not 'OpenAI'
If your TTS box speaks the OpenAI /v1/audio/speech API but isn't OpenAI's hosted service, choose Orpheus or OpenAI‑compatible — those stream as they generate. Picking OpenAI for a custom box can make it wait for the whole clip before any audio plays.
Point an NPC at a provider¶
On the NPC's SSAINpc:
| Field | Set to |
|---|---|
providerOverride |
the handle of a Text provider |
modelOverride |
(optional) a specific model for this NPC |
voiceProviderOverride |
the handle of a Voice provider (only if enableVoice) |
If you don't override per‑NPC, the world's default provider is used.
How it travels¶
Your world carries an AIProviderProfile — the non‑secret config (handles, endpoints, models, default voice) that the server reads when your world loads. The keys stay on the server, matched to each handle at runtime. So uploading your world ships the wiring, never the secrets.
Don't use the legacy in‑asset key field
Older setups stored a raw key on the provider entry (legacyApiKey). That key would travel inside your world — avoid it. Use the Provider Manager so the key stays server‑side.
Checklist¶
- Provider Manager → add a Text provider (handle + endpoint + model + key).
- (Optional) add a Voice provider for speech.
- On the NPC, set
providerOverride(andvoiceProviderOverride) to those handles. - Build & upload — keys stay on your account, only handles travel.