Providers
How Facio selects model providers and how to configure them.
Facio separates provider identity from model choice. A model name, forced provider setting, configured API key, API base, and provider registry metadata all contribute to routing.
At runtime, the provider pool can switch the active provider when settings change, so a Placet settings update does not always require a restart.
Provider fields
Every non-OAuth provider can use these fields:
| Field | Meaning |
|---|---|
apiKey | Secret used by the provider. Stored in config for provider credentials, or captured via Placet/API. |
apiBase | Optional OpenAI-compatible base URL. Required for custom, azure_openai, and vllm. |
extraHeaders | Extra headers for OpenAI-compatible providers. |
extraBody | Extra request body fields for provider-specific options. |
Provider credentials can be set from Placet settings, the management API, config files, or supported environment variables. Provider values are never returned in clear text by the API; responses use masked state such as hasValue.
Routing rules operators should know
| Rule | Effect |
|---|---|
| Forced provider | provider overrides auto-routing when set to a provider name. |
| Model prefix | A model like openrouter/anthropic/claude-... can explicitly select a provider family. |
| Keyword match | Provider keywords such as claude, gpt, gemini, qwen, or ollama help auto-routing. |
| Local fallback | Configured local providers with an apiBase can handle plain local model names. |
| Gateway fallback | Gateways such as OpenRouter can route many models once credentials exist. |
| OAuth providers | OpenAI Codex and GitHub Copilot require explicit selection and stored OAuth tokens. |
Provider credential API
curl http://localhost:8900/api/v1/credentials/providers \
-H "Authorization: Bearer $FACIO_MANAGEMENT_TOKEN"Use PUT /api/v1/credentials/providers/{name} to upsert a provider API key or base URL:
curl -X PUT http://localhost:8900/api/v1/credentials/providers/openrouter \
-H "Authorization: Bearer $FACIO_MANAGEMENT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"value":"sk-or-...","apiBase":"https://openrouter.ai/api/v1"}'For create-only behavior, use POST /api/v1/credentials/providers with a body that includes name.
Provider groups
| Page | Use it for |
|---|---|
| Hosted providers | OpenAI, Anthropic, OpenRouter, Azure, Bedrock, Gemini, DeepSeek, and other managed APIs. |
| Local providers | Ollama, LM Studio, vLLM, OVMS, and custom OpenAI-compatible endpoints. |
| OAuth providers | OpenAI Codex and GitHub Copilot login flows. |
Practical setup order
- Pick the provider family and model.
- Add the provider key or OAuth login.
- Set
apiBasewhen the provider requires it. - Set the default
modeland optional forcedprovider. - Run
/checkor a small Placet test task. - Add subagent, vision, image, or video model overrides only when needed.