配置第一个 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 费用太高或注重离线隐私，可以尝试配置本地大语言模型。