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 ▸ Social Scape ▸ 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 |
| Image (gen) | Provider (Grok / OpenAI / OpenAI‑compatible / custom) · Endpoint · Model | AI image generation — see Images |
| 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 — and the list of approved providers — is on the HTTP & backends 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.
Image (gen) — pick the Provider: Grok (xAI), OpenAI (DALL·E / gpt-image-1), or OpenAI‑compatible / custom for any server speaking /v1/images/generations. Set the Endpoint (a bare host or /v1 base both work) and Model (e.g. gpt-image-1, dall-e-3, grok-imagine-image-quality). Point an NPC at it with its Image Provider dropdown. Full feature: Images.
How many providers can I add?
Each account can store up to 10 providers/endpoints (across all types) on the free tier — enough for a brain, a voice, an image provider, and a few HTTP credentials. Premium tiers raise the limit. Hit it? Delete one you no longer use, or upgrade. (Editing an existing provider never counts against it.)
Point an NPC at a provider¶
On the NPC's SSAINpc:
| Field | Set to |
|---|---|
Provider (providerOverride) |
the handle of a Text provider |
modelOverride |
(optional) a specific model for this NPC |
Voice Provider (voiceProviderOverride) |
the handle of a Voice provider (only if enableVoice) |
Image Provider (imageProviderOverride) |
the handle of an Image provider (for its image actions / AI.GenerateImageOnto); also becomes the world's image provider |
Each is a dropdown of the matching‑type providers on your account. If you don't override per‑NPC, the world's default provider is used.
How it travels¶
Your world ships only the handles — each NPC references a provider by name. The full config (endpoints, models, keys) lives on your account in the Provider Manager and is resolved server‑side by handle when your world loads. So uploading your world ships the wiring, never the secrets — nothing provider‑related is baked into the bundle.
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.