# 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 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 | 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](./agent/tools.mdx#provider-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](./config.mdx)). ## Catalog [#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 [#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. Declares: the **Web Search** provider tool (executed by the upstream inside the request) and the image generation API. ### 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`); 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](#google-vertex-ai). ### SpaceXAI [#spacexai] Create an API key in the [SpaceXAI console](https://console.x.ai/team/default/api-keys). 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 [#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. Declares: the **Perplexity Search** provider tool (executed by the gateway inside the request) and the image / video generation APIs. ### 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) — 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 [#deepseek] Create an API key on the [DeepSeek platform](https://platform.deepseek.com/api-keys). 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 [#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. Declares: the video generation API. ### 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. Declares: the image and video generation APIs. ### 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. Declares: the image and video generation APIs. ### 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. Declares: the image and video generation APIs. ### 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). 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 [#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. 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 [#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. Declares: the **Web Search** provider tool (host-executed; `max_results` 1–50). ### 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. Declares: the **Web Search** provider tool (host-executed; `max_results` 1–50). ### 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. Declares: the **Web Search** and **Code Interpreter** provider tools (request-body switches executed by the upstream). ### MiniMax [#minimax] Create an API key in the MiniMax console for the site you will use: [China](https://platform.minimax.cn/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.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 [#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. Declares: the image and video generation APIs. ### StepFun [#stepfun] Create an API key on the [StepFun China platform](https://platform.stepfun.com) or the [International platform](https://platform.stepfun.ai). Step Plan notes: [Step Plan](https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api). 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 [#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. Declares: the video generation API. ### 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. Declares: the video generation API. ### 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. Declares: the thinking on/off wire encoding (`thinkingSwitch`), so models with a thinking switch get a working toggle. ### 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. 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 [#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](#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 [#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.