API 是什么
API（Application Programming Interface）是一条「对话通道」：KOA 把你说的话通过这条通道发给大语言模型（比如 DeepSeek、GPT、Gemini），模型思考后把 ta 的回复传回来。
你可以这么理解：KOA 是 ta 的家，API 是 ta 的大脑连接线。没有 API，ta 就没有思考能力。
配置 API 你只需要三样东西：
- API 地址：服务商提供的网址。KOA 的地址栏下拉里列着几家常用的，选一下就填好了。
- API Key：一串密钥字符串（类似
sk-xxxxxxxx），是你的「通行证」，服务商靠它识别是谁在用、从谁的余额里扣费。 - 模型名称：同一家服务商往往有多个模型，选一个填进去。
为什么 KOA 需要你自备 API？因为每次对话都会消耗模型服务商的算力（按 token 计费），这部分费用由你直接付给服务商。好处是：你可以自由选择喜欢的模型，而且对话内容只经过你自己的 API 通道，不经过 KOA 服务器。
模型怎么选
选模型主要看三件事：文字能力（聊天是否自然）、识图能力（多模态，能不能看懂图片）、价格。
| 模型 | 文字能力 | 识图 | 价格参考 |
|---|---|---|---|
| DeepSeek（deepseek-chat） | 中文效果好 | 不支持 | 很低，日常几毛到几块/天 |
| GPT-4o | 综合能力强 | 支持 | 中等 |
| GPT-4o-mini | 够用且快 | 支持 | 低 |
| Claude | 文字表现力强 | 支持 | 中等偏上 |
| Gemini | 能力均衡 | 支持 | 有免费额度可体验 |
识图能力什么时候用得上？在虚拟手机里给 ta 发照片、在电脑的「一起看看」App 里给 ta 看你的屏幕、在线下场景发图片，这些都需要模型能看懂图。只在游戏里陪玩、纯文字聊天的话，DeepSeek 完全够用。
不同模型的「人格表现力」也有差异：同一张角色卡，换个模型性格气质会略有不同。可以多试试找到你喜欢的：KOA 支持随时切换模型，已有的记忆和设定不会丢失。
DeepSeek 注册取 Key
性价比之选，适合作为第一个 API。
-
注册账号
打开 DeepSeek 开放平台官网（deepseek.com 进入「开放平台」），用手机号注册。
-
充值
在「充值」页面充入少量金额，建议先充 10 元体验，熟悉消耗速度后再按需充值。
-
创建 API Key
在「API Keys」页面点「创建 API Key」，得到一串
sk-开头的密钥。立刻复制保存，它只完整显示这一次。
模型名选 deepseek-chat。
OpenAI
GPT 系列的官方渠道。到 OpenAI Platform（platform.openai.com）注册账号，充值后在「API keys」页面创建密钥，同样是 sk- 开头、只显示一次。
模型推荐 gpt-4o（能力全面）或 gpt-4o-mini（更便宜），两者都支持识图。
OpenAI 官方注册和付款对部分地区有门槛。如果不方便，可以考虑使用兼容 OpenAI 格式的其它服务商（见下文）。
Google Gemini
Google 出品，有免费额度，适合想先零成本体验的姊妹。
用 Google 账号登录 Google AI Studio（aistudio.google.com），点「Get API key」即可创建密钥。Gemini 系列模型支持识图。
Claude
Anthropic 的官方渠道。到 Claude 开发者平台（platform.claude.com）注册账号，在「Billing」里充值，再到「API keys」页面创建密钥。密钥以 sk-ant- 开头，只完整显示一次。
在 KOA 的 API 页选「Claude」，地址会自动填好。贴上 Key，点「获取模型」，从列表里选一个。价格从低到高是名字里带 haiku、sonnet、opus、fable 的，具体数字看官网的价格页。都能识图。
要的是开发者平台里创建的 API Key。Claude 网页版和 App 的会员不带 API 额度，那边的登录也不能当 Key 用。
Anthropic 官方只对部分国家和地区开放。不在范围内的话，可以用提供 Claude 的兼容服务商（见下文）。那种情况按「其它兼容服务商」填地址，不选「Claude」这一项。
新一些的 Claude 型号不接受温度这类采样设置。KOA 在这条线路上不发送它们，界面里对应的设置不起作用。
其它兼容服务商
任何兼容 OpenAI 接口格式的服务商都可以在 KOA 里使用，包括各类国产大模型平台和聚合服务。KOA 也适配了很多非官方 API 格式。
使用这类服务商时，先向服务商拿到三样东西：API 地址、Key、模型名。在 KOA 的 API 页自己把地址粘进「API 地址」，不用从下拉里选。
选择第三方服务商时注意甄别信誉，你的对话内容会经过它们的服务器。不确定的话，优先用本页介绍的官方渠道。
填进 KOA
-
打开 API 页
点启动器主页的「API」。最上面是「API 预设」，往下依次是「游戏模型」「聊天模型」「创作模型」，再往下是语音识别、远程中继和网络代理。
-
填「游戏模型」
「API 地址」点开下拉选你的服务商，地址自己会填好；用中转站或自建代理，就直接把地址粘进去。「API Key」贴上 Key，点「获取模型」，从列表里选一个。
-
要不要分开用模型
「聊天模型」底下写着「用于线下聊天，推荐文笔好的模型」，「创作模型」写着「用于克姐工作台，推荐更聪明的模型」。两块默认都是「同游戏模型」，不想分开就不用动。
-
选语音识别语言
顺手把「语音识别 STT」的识别语言和触发方式选好（详见《语音全指南》）。
-
不用点保存
改完自己会存，页面最下面「测试连接」旁边会写「已保存」或「已自动应用」。想确认通不通，点一下「测试连接」。
「API 预设」能存好几套：点「添加」，填「名称」、地址、Key 和模型，点「保存」。之后每一块的「API 预设」下拉里都能直接选它。比如一套 DeepSeek 用来打游戏省钱，一套能看图的模型留着发照片的时候换上。
费用与省钱
大模型按 token 计费（可以粗略理解为字数）。KOA 消耗的 token 量是普通文本量，不会花费太多。以 DeepSeek 为例，日常陪玩每天大约几毛到几块钱。
- 线下场景的对话攒到一定量，KOA 会问你要不要把它们整理成记忆，整理过的旧对话不再整段发给模型，上下文不会无限变长。
- 「我们的故事」里写卡片、改记忆时，文字框下面有一行「约 N tokens」。一直记得的卡片每一轮都要算钱，写长了心里有个数。
- 第一次充值别充多，先小额体验，看清自己的消耗节奏再补。
- 在我的世界里暂时不想让 ta 说话时，可以用
/koa quiet暂停 LLM 调用，省下这段时间的 token。
报错对照表
API 出问题时，大多能从错误码直接看出原因：
| 错误码 | 原因 | 怎么办 |
|---|---|---|
| 401 / 403 | Key 不正确或已过期 | 检查 Key 是否复制完整、有没有多余空格 |
| 404 | API 地址或模型名不对 | 确认拼写；用第三方服务商时核对地址格式 |
| 429 | 请求太频繁或额度用完 | 等一等再试，或去服务商后台充值 |
| 500 / 502 | 服务商自身故障 | 稍后再试，换个时间段 |
看不出原因时，到启动器的「日志」页查看详细错误信息，通常能直接定位问题。实在解决不了，在「日志」页点「提交反馈」，诊断包会跟着一起发给开发者，见《数据与维护》。