Providers

Spirit is BYOK. You create a key in a provider console, paste it into Desktop or the CLI, and Spirit stores it in the operating system keyring. Switching houses does not change how you open a workspace, approve edits, or run the agent.

The connect wizard is Settings → Models on Desktop, or /model add / spirit model add in the CLI. Extra fields appear only when that provider needs them.

Spirit talks to providers over one of four transports. The wizard either fixes the type or lets you pick.

The Google and Vertex AI presets pin Chat Completions — the wizard offers no transport picker for them.

Some houses add a second dimension on top of the key:

• Regional sites — Moonshot AI, SiliconFlow, MiniMax (China / International); Alibaba (region + workspaceId); Tencent TokenHub (Guangzhou / Singapore)
• Plan endpoints — Alibaba Token Plan, StepFun Step Plan, Z.ai / Zhipu AI GLM Coding Plan
• Cloud fields — Bedrock region, Azure resource name, Cloudflare account (and optional gateway), Vertex project / location

If a provider has none of these, the wizard is just key → import models → pick an active language model.

Spirit imports the model catalog and lets you assign the active language model, plus image / video / secondary language model slots when the catalog marks those capabilities. Reasoning options follow each model's declared supportedReasoningEfforts. Provider-exposed tools such as web search are declared per provider and gated by the Provider Tools toggle — see Tools.

What the wizard writes into config.json is a fully declarative entry: the final API base, the transport, the SDK adapter, and any provider tools / file upload / generation API declarations. The runtime reads those declarations as-is and never re-derives them from the provider's identity — your edits survive, except the wizard-owned keys that a reconnect resets (see Config).

Catalog

These are the houses in the connect picker, in the same order. Each section is that house's key, transport, extra fields, and what the wizard declares beyond the key. Unless a section says otherwise, the credential form is a single API key stored in the keyring. The Desktop and CLI wizard above is the same for every house.

OpenAI

Create an API key in the OpenAI platform. Spirit does not sell OpenAI usage.

The wizard fixes Responses API (open-responses). There is no transport picker. Default base: https://api.openai.com/v1.

Chat after import. Reasoning follows the model. Image and video generation appear only when the catalog marks those capabilities — assign them in the image / video model slots.

Declares: the Web Search provider tool (executed by the upstream inside the request) and the image generation API.

Anthropic

Create an API key in the Anthropic console.

Fixed Messages API (anthropic). Default base: https://api.anthropic.com/v1.

Chat after import. Reasoning follows the model. No Spirit-side image or video generation slot unless a later catalog entry marks it.

Google

Create an API key in Google AI Studio.

Fixed Chat Completions API (openai-compatible); the wizard offers no transport picker. Default base: https://generativelanguage.googleapis.com/v1beta.

Chat after import. Image generation is assigned only when the catalog marks it. For Vertex AI (GCP project / location), use Google Vertex AI.

SpaceXAI

Create an API key in the SpaceXAI console.

Fixed Open Responses API (open-responses). Default base: https://api.x.ai/v1.

Chat after import. Reasoning, image, and video follow the imported catalog — assign slots when they appear.

Declares: the Web Search provider tool (executed by the upstream inside the request).

Vercel AI Gateway

Create a key in the Vercel AI Gateway dashboard.

Fixed Open Responses API (open-responses). Default base: https://ai-gateway.vercel.sh/v1.

Chat plus whatever the gateway catalog exposes. Image generation is taken from catalog type=image, not from tags.

Do not infer vision or image generation from tags. MiniMax M3 through this gateway does not return a displayable thinking stream on Open Responses.

Declares: the Perplexity Search provider tool (executed by the gateway inside the request) and the image / video generation APIs.

Cloudflare AI Gateway

Create an API token in the Cloudflare dashboard. You also need the account ID.

Picker: Chat Completions, Open Responses, or Messages. Base is built from the account: https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/v1.

• Account ID (required) — 32-character hex
• Gateway ID (optional) — written as a literal cf-aig-gateway-id request header

Without an account ID the wizard cannot build the API base. Chat and other capabilities follow the models the gateway exposes.

DeepSeek

Create an API key on the DeepSeek platform.

The connect default is Chat Completions API (openai-compatible). Default base: https://api.deepseek.com/v1. Explicit alternatives are Open Responses (open-responses, base https://api.deepseek.com) and Messages (anthropic, base https://api.deepseek.com/anthropic).

Chat after import. Reasoning follows the model.

Declares: the Web Search provider tool (a static function declaration; Spirit executes calls with POST /v1/tools/search).

OpenRouter

Create a key at OpenRouter.

Picker: Chat Completions, Open Responses, or Messages. Default base: https://openrouter.ai/api/v1.

Chat plus catalog-marked image or video generation when OpenRouter exposes those models.

Declares: the video generation API.

Fireworks AI

Create an API key in the Fireworks console.

Picker: Chat Completions, Messages, or Open Responses. Chat / Responses base: https://api.fireworks.ai/inference/v1. Messages base: https://api.fireworks.ai/inference.

Chat after import. Other capabilities follow the Fireworks catalog.

Together AI

Create an API key in the Together AI console.

Fixed Chat Completions API. Default base: https://api.together.ai/v1.

Chat after import. Assign image or video slots only when the catalog marks them.

Declares: the image and video generation APIs.

Groq

Create an API key in the Groq console.

Fixed Chat Completions API. Default base: https://api.groq.com/openai/v1.

Chat after import. Reasoning follows the model when Groq exposes it.

DeepInfra

Create an API key in the DeepInfra Dashboard.

Fixed Chat Completions API. Default base: https://api.deepinfra.com/v1/openai.

Chat after import. Other capabilities follow the catalog.

Declares: the image and video generation APIs.

Baseten

Create an API key in the Baseten console.

Fixed Chat Completions API. Default base: https://inference.baseten.co/v1.

Chat after import. Other capabilities follow the catalog.

Hugging Face

Create a token in Hugging Face settings.

Fixed Open Responses API. Default base: https://router.huggingface.co/v1.

Chat after import. Other capabilities follow the router catalog.

Declares: the image and video generation APIs.

Moonshot AI

Create an API key in the Moonshot console for the site you will use: China or International.

Fixed Chat Completions API. No transport picker.

• International (default) — https://api.moonshot.ai/v1
• China — https://api.moonshot.cn/v1

This is the Moonshot Open Platform provider, not Kimi Code. A Kimi Code key and a Moonshot Open Platform key are different connections.

Declares: the Web Search provider tool (a static function tool schema; Spirit executes calls with POST /v1/tools/search_pro) and video file upload (ms:// file references).

Kimi Code

Create a Kimi Code API key in the Kimi Code console.

Fixed Chat Completions API. Default base: https://api.kimi.com/coding/v1. A Messages base exists at https://api.kimi.com/coding but the wizard does not offer a picker.

Chat after import. The hosted search here is specific to this provider — not moonshot-ai.

Declares: the Web Search provider tool (host-executed against the declared search endpoint), video file upload (ms:// file references), and a literal stream_options request-body merge.

Z.ai

Create an API key in the Z.ai console. Coding Plan notes: GLM Coding Plan.

Fixed Chat Completions API. Default base: https://api.z.ai/api/paas/v4.

Turn on GLM Coding Plan in the wizard to use https://api.z.ai/api/coding/paas/v4 instead of the default PaaS base.

Chat after import. Reasoning follows the model.

Declares: the Web Search provider tool (host-executed; max_results 1–50).

Zhipu AI

Create an API key in the Zhipu AI console. Coding Plan notes: GLM Coding Plan.

Fixed Chat Completions API. Default base: https://open.bigmodel.cn/api/paas/v4.

Turn on GLM Coding Plan to use https://open.bigmodel.cn/api/coding/paas/v4.

Chat after import. Reasoning follows the model.

Declares: the Web Search provider tool (host-executed; max_results 1–50).

Alibaba

Create an API key in Alibaba Cloud Model Studio / Bailian.

Fixed Chat Completions API. Compatible default: https://dashscope.aliyuncs.com/compatible-mode/v1.

• cn-beijing (default) — https://{workspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 (workspace id required)
• ap-southeast-1 — workspace id required
• us-virginia — https://dashscope-us.aliyuncs.com/compatible-mode/v1 (no workspace id)
• eu-central-1 — workspace id required

Token Plan switches to https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 and ignores site / workspace. Notes: Token Plan. Token Plan always uses the cn-beijing plan endpoint, even if you picked another site.

Chat after import. Other capabilities follow the catalog.

Declares: the Web Search and Code Interpreter provider tools (request-body switches executed by the upstream).

MiniMax

Create an API key in the MiniMax console for the site you will use: China or International.

Fixed Messages API (anthropic). International Messages base: https://api.minimax.io/anthropic/v1.

• International (default) — https://api.minimax.io/v1 (Chat-shaped) / https://api.minimax.io/anthropic/v1 (Messages)
• China — https://api.minimax.cn/v1

Chat after import. The upstream /models list has no multimodal flags; only M3 is treated as supporting image / video input. Through Vercel AI Gateway on Open Responses, MiniMax M3 does not return a displayable thinking stream.

Declares: the Web Search provider tool (a Messages API server tool, executed by the upstream) and video file upload (mm_file:// file references).

Xiaomi

Create an API key in the Xiaomi MiMo console.

Fixed Chat Completions API. Default base: https://api.xiaomimimo.com/v1.

Chat after import. Other capabilities follow the catalog.

SiliconFlow

Create an API key in the SiliconFlow console for the site you will use: International or China.

Picker: Chat Completions or Messages.

• International (default) — https://api.siliconflow.com/v1
• China — https://api.siliconflow.cn/v1

Chat after import. Other capabilities follow the catalog.

Declares: the image and video generation APIs.

StepFun

Create an API key on the StepFun China platform or the International platform. Step Plan notes: Step Plan.

Fixed Chat Completions API.

• International (default) — https://api.stepfun.ai/v1
• China — https://api.stepfun.com/v1

Step Plan keeps the /step_plan/v1 path and only changes the host (api.stepfun.com vs api.stepfun.ai).

Chat after import. Reasoning follows the model.

Declares: the Web Search provider tool (host-executed; max_results 1–20), video file upload (stepfile:// file references, 128 MiB cap), and the image generation API.

Volcengine

Create an API key in the Volcengine Ark console.

Picker: Chat Completions or Responses API. Default base: https://ark.cn-beijing.volces.com/api/v3.

Chat after import. Other capabilities follow the catalog.

Declares: the video generation API.

BytePlus

Create an API key in the BytePlus Ark console.

Picker: Chat Completions or Responses API. Default base: https://ark.ap-southeast.bytepluses.com/api/v3.

Chat after import. Other capabilities follow the catalog.

Declares: the video generation API.

Meituan

Create an API key in the LongCat console.

Fixed Chat Completions API. Default base: https://api.longcat.chat/openai/v1.

Chat after import. Other capabilities follow the catalog.

Declares: the thinking on/off wire encoding (thinkingSwitch), so models with a thinking switch get a working toggle.

Tencent TokenHub

Create an API key in the Tencent TokenHub console.

Fixed Chat Completions API. The wizard does not offer Responses or Messages.

• Guangzhou (default) — https://tokenhub.tencentmaas.com/v1
• Singapore — https://tokenhub-intl.tencentmaas.com/v1

Chat after import. Do not rely on Chat-injected web search. TokenHub documents Chat web_search_options and Responses web_search, but Chat injection does not work in practice, and Responses is only on a few models. Spirit therefore keeps Chat Completions only.

Mistral

Create an API key in the Mistral console.

Fixed Chat Completions API. Default base: https://api.mistral.ai/v1.

Chat after import. Other capabilities follow the catalog.

Cohere

Create an API key in the Cohere dashboard.

Fixed Chat Completions API. Default base: https://api.cohere.com/v2.

Chat after import. Other capabilities follow the catalog.

Azure

Create a key for your Azure OpenAI resource in the Azure portal.

Fixed Responses API (open-responses). No transport picker.

• Resource name (required) — 2–64 characters, letters, numbers, and hyphens; cannot start or end with a hyphen

Spirit builds https://{resource}.openai.azure.com/openai/v1. Chat after import. Image generation follows the Azure catalog when marked.

Amazon Bedrock

In the AWS Bedrock console, create a Bearer API key or an IAM user that can call Bedrock.

Fixed Amazon Bedrock (bedrock). Default host shape: https://bedrock.us-east-1.amazonaws.com.

• AWS Region (required), for example us-east-1
• Authentication: Bearer or IAM
  • Bearer — paste a Bedrock API key and a model id. Models are not fetched automatically.
  • IAM — Access Key ID + Secret Access Key. Spirit lists foundation models from the account.

Chat after you pick a model. Other capabilities follow that model. Bearer keys work for inference only. ListFoundationModels does not accept Bearer, so the catalog import needs IAM.

The region is baked into the final API base and options.awsRegion. Bearer is stored as the provider key; IAM is stored as accessKeyId / secretAccessKey credential slots.

Google Vertex AI

Use a GCP project that has Vertex AI enabled. Auth is ADC, a service account, or an Express API key — not a generic OpenAI key.

Fixed Chat Completions API; the wizard offers no transport picker. Base becomes https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}.

• GCP Project ID and Location (required), for example us-central1
• Authentication
  • ADC — Application Default Credentials on this machine (GOOGLE_APPLICATION_CREDENTIALS)
  • Service Account — client email + private key; used to fetch the model list
  • Express API Key — cannot fetch the catalog; add a model id by hand

Chat after a model is selected. For AI Studio keys without a GCP project, use Google. Express mode cannot import the model list. Service account mode needs both email and private key to list models.

A service account is stored as clientEmail / privateKey credential slots with options.project / options.location. Express mode writes the Express API base and needs no project / location.

Custom

Use the API key your endpoint expects. There is no Spirit-hosted custom provider.

Picker: Chat Completions, Open Responses, or Messages. You must supply the Base URL. The placeholder default is https://api.openai.com/v1 if you leave it empty.

Enter the root the vendor documents, including the version suffix when they require it (/v1, /v1/openai, …). Spirit does not guess a path for custom endpoints.

You can also set a display name for the provider entry so several custom endpoints stay distinguishable.

After connect, import or type model ids. Mark chat / image / video capabilities in the wizard when the endpoint does not publish a catalog Spirit understands.