配置第一個 API
Tavern Studio 作為一個本地優先的客户端，本身并不直接提供大语言模型的推理算力。要让你的角色卡產生思维并開始對話，你需要為其配置一個模型大脑。本篇文档将指導你配置第一個雲端 API 連接，打通與大语言模型的通信链路。
适合誰阅读
- 准備使用雲端模型（如 OpenAI、Anthropic、DeepSeek 或各類中转 API）进行角色扮演的用户。
- 遇到了“模型未連接”、“API 校验失败”或“連接超时”等报错的排查者。
- 想要為不同角色卡配置獨立模型以后端以节省成本的高級玩家。
你将学会什么
- 雲端 API 與本地大模型之间的选擇權衡及隱私边界。
- 获取并正确填写 API 配置的核心三要素：API Key、Base URL 和 Model Name。
- 使用 OpenAI-compatible API（兼容 OpenAI 的通用格式）接入各种大模型。
- 进行聊天級（Chat-Level）模型覆盖配置，针對單個角色使用特定模型。
- 排查并修複常见的 API 連接故障。
為什么需要配置 API？
在角色扮演的工作流中，Tavern Studio 扮演的是“渲染层與管理器”的角色（它负责拼接系統提示詞、检索世界書設定、维护聊天上下文歷史），而 API（Application Programming Interface，應用程序介面） 则充當“计算器”的角色。
當你點击發送消息时，客户端会将整理好的上下文數據通过网络發送给 API 介面，API 服务商在雲端超級计算机上完成文本推理后，再将生成的角色回複传回 Tavern Studio 呈现在你的螢幕上。
常见的 API 提供商（Provider）類型
在設置界面中，你可以看到几种預設的模型提供商：
- 原生服务商（如 OpenAI、Anthropic）：适合直接拥有官方充值账户并能正常访问其网络服务的用户。
- 第三方中转服务商：国內用户常用的选擇。通过国內可直接访问的网络网關，将請求转發给国外的模型。
- OpenAI-compatible API（通用兼容模式）：這是一种行业標准协议。几乎所有第三方大模型平台（例如 DeepSeek、零一万物，或者你自建的本地大模型服务）都提供這一標准介面。只要介面符合該標准，你都可以在 Tavern Studio 中接入。
核心配置三要素：Key、URL 與模型
點击螢幕底部 TabBar 最右侧的 Settings（設置） 圖標（或使用觸摸板双指左右滑動切換至設置頁），下滑至 API 模块。我们将以最通用的 OpenAI-compatible API 為例进行配置：
- 选擇 Provider：在下拉列表中选擇
OpenAI-compatible API。 - 填写 Base URL：
- 這是大模型服务的入口地址。
- 注意：原生的 OpenAI 地址為
https://api.openai.com/v1。如果你使用的是第三方中转服务或国內的大模型平台，請查阅其官方文档提供的 API 基址，并填入此处。
- 填写 API Key：
- 輸入你在服务商后台申請的 API 密钥（通常以
sk-開头）。請确保複制时没有遗漏字符，也没有夹雜多余的空格。
- 刷新并选擇模型：
- 填好上述两項后，點击 Refresh Models（刷新模型列表） 按钮。
- 客户端会向填写的 URL 發送一個握手請求。如果配置无误，下方的 Model 下拉菜單将被激活，并展示出該密钥下所有可用的模型名称。
- 从列表中选擇你希望使用的模型（例如：进行角色扮演通常推荐上下文長、對人設理解好的模型）。
- 保存并連接：點击 Save & Connect。此时，如果螢幕底部的状態指示球變為绿色，说明連接成功。
聊天級（Chat-Level）模型配置覆盖
默认情况下，所有的角色聊天都会使用你在全局設置里配置的 API 和模型。但在实际使用中，你可能会遇到不同的需求：比如“雷神托尔”這個角色需要高拟真度的模型，而一些日常闲聊的角色只需要基础模型即可。
Tavern Studio 支持單個聊天覆盖配置：
- 打開與特定角色的 Chat 窗口。
- 若在寬螢幕下，直接查看右侧并列的 Chat Settings 面板；若在窄螢下，向左滑動切換至 Chat Settings 面板。
- 在面板頂部的模型覆盖配置區中，勾选 Override Global Connection（覆盖全局配置） 開關。
- 此时，您可以為這個聊天單獨指定不同的 API Provider、Base URL 甚至不同的模型名。這不会影响其他角色的默认聊天配置。
故障排查：解决常见的 API 連接失败
如果你的連接状態指示球變红，或者點击“刷新模型”没有任何反應，請按照以下步骤排查：
1. 检查 Base URL 是否漏写或多写了 /v1
這是最常见的错误。有些服务商提供的基址是 https://api.domain.com，而有些要求必须是 https://api.domain.com/v1。如果刷新报错，請尝試添加或去掉 /v1 后缀再試。
2. 网络連接與代理設置
如果你連接的是原生 OpenAI 或 Anthropic，通常需要你的本地設備能够访问海外服务。請检查你的代理软件是否正常工作，或者是否需要在 Tavern Studio 的“設置 - 网络設置”中配置代理服务器端口。
3. API Key 余额不足或过期
請登錄你的 API 服务商后台，检查當前账户是否还有余额。许多新注册的 API 账号在試用额度过期后，即使密钥正确也会返回 401 (Unauthorized) 或 429 (Quota Exceeded) 错误。
常见问题
Q1：為什么刷新模型成功了，但聊天發送消息时报错 "Model not found"？
這代表你选中的模型名称在服务商端可能被下線了，或者你的 API 密钥无權調用該特定模型。請在設置中重新點击“刷新模型”，并在下拉菜單中选擇一個當前确切可用的模型。
Q2：我能不能直接在 Model Name 輸入框里手動填模型名字？
可以的。如果你的服务商介面不支持自動获取模型列表（即刷新模型按钮无效），你可以勾选“手動指定模型（Manual Model Input）”複选框，然后在文本框中直接輸入模型服务商提供的模型標识符（如 deepseek-chat）。
Q3：換了模型之后，AI 突然開始重複说过的對話？
這通常不是 API 本身的问题，而是模型對上下文的处理方式，或者由于新模型的上下文長度（Context Window）较小，導致丢掉了歷史記憶。你可以尝試在設置中調小“最大上下文 Token 數（Max Context Tokens）”，或者尝試在“預設”中微調取樣參數。
下一步
- 開始第一次聊天：打通模型大脑后，立刻開始你的第一次對話。
- 預設入門：深入学习通过預設參數控制 API 輸出的字數、随机度與逻輯稳定性。
- 本地 GGUF 模型入門：如果你觉得雲端 API 费用太高或注重离線隱私，可以尝試配置本地大语言模型。