# Providers
URL: /en-US/docs/providers

Bring your own key, run the connect wizard, and keep the same agent workflow when you switch houses.



Spirit Agent 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.

| Transport           | Wizard label                       | Typical use                                                                |
| ------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| `openai-compatible` | Chat Completions API               | Most OpenAI-compatible endpoints                                           |
| `open-responses`    | Responses API / Open Responses API | OpenAI, Azure, Vercel AI Gateway, Hugging Face, and optional gateway paths |
| `anthropic`         | Messages API                       | Anthropic, MiniMax, and optional Messages-compatible endpoints             |
| `bedrock`           | Amazon Bedrock                     | Amazon Bedrock only                                                        |

Google Gemini and Vertex AI always use Chat Completions. If a profile asks for Responses or Messages, Spirit falls back to `openai-compatible`.

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 chat model.

Spirit imports the model catalog and lets you assign the active chat model, plus image / video / lightweight chat slots when the catalog marks those capabilities. Reasoning and built-in web search follow the model and transport, not a separate Spirit toggle.

## Catalog [#catalog]

These are the houses in the connect picker, in the same order. Each section is that house's key, transport, and extra fields. The Desktop and CLI wizard above is the same for every house.

### OpenAI [#openai]

Create an API key in the [OpenAI platform](https://platform.openai.com/api-keys). 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.

### Anthropic [#anthropic]

Create an API key in the [Anthropic console](https://console.anthropic.com/settings/keys).

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 [#google]

Create an API key in [Google AI Studio](https://aistudio.google.com/apikey).

Fixed **Chat Completions API** (`openai-compatible`). Asking for Responses or Messages falls back to Chat Completions. 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](#google-vertex-ai).

### SpaceXAI [#spacexai]

Create an API key in the [SpaceXAI console](https://console.x.ai/team/default/api-keys).

Fixed **Chat Completions API** (`openai-compatible`). Default base: `https://api.x.ai/v1`.

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

### Vercel AI Gateway [#vercel-ai-gateway]

Create a key in the [Vercel AI Gateway](https://vercel.com/docs/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.

### Cloudflare AI Gateway [#cloudflare-ai-gateway]

Create an API token in the [Cloudflare dashboard](https://developers.cloudflare.com/ai-gateway/). 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)

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

### DeepSeek [#deepseek]

Create an API key on the [DeepSeek platform](https://platform.deepseek.com/api-keys).

No picker. The connect default is **Open Responses** (`open-responses`). Compatible bases also exist at `https://api.deepseek.com/v1` (Chat) and `https://api.deepseek.com/anthropic` (Messages).

Chat after import. Reasoning follows the model.

### OpenRouter [#openrouter]

Create a key at [OpenRouter](https://openrouter.ai/keys).

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.

### Fireworks AI [#fireworks-ai]

Create an API key in the [Fireworks console](https://app.fireworks.ai/settings/users/api-keys).

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 [#together-ai]

Create an API key in the [Together AI console](https://api.together.ai/settings/api-keys).

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.

### Groq [#groq]

Create an API key in the [Groq console](https://console.groq.com).

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

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

### DeepInfra [#deepinfra]

Create an API key in the [DeepInfra Dashboard](https://deepinfra.com/dash/keys).

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

Chat after import. Other capabilities follow the catalog.

### Baseten [#baseten]

Create an API key in the [Baseten console](https://app.baseten.co/settings/api_keys).

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

Chat after import. Other capabilities follow the catalog.

### Hugging Face [#hugging-face]

Create a token in [Hugging Face settings](https://huggingface.co/settings/tokens).

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

Chat after import. Other capabilities follow the router catalog.

### Moonshot AI [#moonshot-ai]

Create an API key in the Moonshot console for the site you will use: [China](https://platform.kimi.com/console/api-keys) or [International](https://platform.kimi.ai/console/api-keys).

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](#kimi-code). Built-in search on moonshot-ai does not use the Kimi Code hosted search path. A Kimi Code key and a Moonshot Open Platform key are different connections.

### Kimi Code [#kimi-code]

Create a Kimi Code API key in the [Kimi Code console](https://www.kimi.com/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. Hosted search, when available, is specific to this provider — not moonshot-ai.

### Z.ai [#zai]

Create an API key in the [Z.ai console](https://z.ai/manage-apikey/apikey-list). Coding Plan notes: [GLM Coding Plan](https://docs.z.ai/devpack/quick-start).

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.

### Zhipu AI [#zhipu-ai]

Create an API key in the [Zhipu AI console](https://bigmodel.cn/console). Coding Plan notes: [GLM Coding Plan](https://docs.bigmodel.cn/cn/coding-plan/quick-start).

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.

### Alibaba [#alibaba]

Create an API key in [Alibaba Cloud Model Studio / Bailian](https://bailian.console.aliyun.com).

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](https://bailian.console.aliyun.com/cn-beijing?tab=doc#/doc/?type=model\&url=3029020). Token Plan always uses the cn-beijing plan endpoint, even if you picked another site.

Chat after import. Other capabilities follow the catalog.

### MiniMax [#minimax]

Create an API key in the MiniMax console for the site you will use: [China](https://platform.minimaxi.com/console/) or [International](https://platform.minimax.io/console/).

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.minimaxi.com/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.

### Xiaomi [#xiaomi]

Create an API key in the [Xiaomi MiMo console](https://platform.xiaomimimo.com/console/api-keys).

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

Chat after import. Other capabilities follow the catalog.

### SiliconFlow [#siliconflow]

Create an API key in the SiliconFlow console for the site you will use: [International](https://cloud.siliconflow.com/me/account/ak) or [China](https://cloud.siliconflow.cn/me/account/ak).

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.

### StepFun [#stepfun]

Create an API key on the [StepFun platform](https://platform.stepfun.com). Step Plan notes: [Step Plan](https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api).

Fixed **Chat Completions API**. Default base: `https://api.stepfun.com/v1`.

**Step Plan** switches to `https://api.stepfun.com/step_plan/v1`.

Chat after import. Reasoning follows the model.

### Volcengine [#volcengine]

Create an API key in the [Volcengine Ark console](https://console.volcengine.com/ark/apiKey).

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

Chat after import. Other capabilities follow the catalog.

### BytePlus [#byteplus]

Create an API key in the [BytePlus Ark console](https://console.byteplus.com/ark/apiKey).

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

Chat after import. Other capabilities follow the catalog.

### Meituan [#meituan]

Create an API key in the [LongCat console](https://longcat.chat/platform/api_keys).

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

Chat after import. Other capabilities follow the catalog.

### Tencent TokenHub [#tencent-tokenhub]

Create an API key in the [Tencent TokenHub console](https://console.cloud.tencent.com/tokenhub).

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 [#mistral]

Create an API key in the [Mistral console](https://console.mistral.ai).

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

Chat after import. Other capabilities follow the catalog.

### Cohere [#cohere]

Create an API key in the [Cohere dashboard](https://dashboard.cohere.com).

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

Chat after import. Other capabilities follow the catalog.

### Azure [#azure]

Create a key for your Azure OpenAI resource in the [Azure portal](https://portal.azure.com).

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 [#amazon-bedrock]

In the [AWS Bedrock console](https://console.aws.amazon.com/bedrock), 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.

### Google Vertex AI [#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**. Responses or Messages requests fall back to Chat Completions. 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](#google). Express mode cannot import the model list. Service account mode needs both email and private key to list models.

### Custom [#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 group 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.