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 发照片、和 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 系列模型支持识图。
其它兼容服务商
任何兼容 OpenAI 接口格式的服务商都可以在 KOA 里使用——包括各类国产大模型平台和聚合服务。KOA 也适配了很多非官方 API 格式。
使用这类服务商时，你需要向服务商拿到三样东西：API 地址、Key、模型名，然后在 KOA 的 API 页手动填写地址（选择「自定义」或直接修改地址栏）。
选择第三方服务商时注意甄别信誉——你的对话内容会经过它们的服务器。不确定的话，优先用本页介绍的官方渠道。
填进 KOA
-
选择服务商
打开启动器的 API 页，选择你的服务商——API 地址会自动装填。只有用非主流服务商或自建代理时才需要手动改地址。
-
填 Key、选模型
粘贴你的 API Key，填写或选择模型名称。
-
选语音识别语言
顺手把语音识别的语言和触发方式选好（详见《语音全指南》）。
-
一键应用
点「一键应用」保存。这套配置对游戏、虚拟手机、线下场景全局生效，不用到处重复填。
API 页支持保存多套配置：比如一套 DeepSeek 用来打游戏省钱，一套多模态模型用来在手机里发照片、一起看看。填好各自的地址和 Key 存成套，随时切换。
费用与省钱
大模型按 token 计费（可以粗略理解为字数）。KOA 消耗的 token 量是普通文本量，不会花费太多——以 DeepSeek 为例，日常陪玩每天大约几毛到几块钱。
- KOA 内置记忆总结机制，会定期压缩对话历史，不会让上下文无限增长白白烧钱。
- 第一次充值别充多，先小额体验，看清自己的消耗节奏再补。
- 在我的世界里暂时不想让 ta 说话时，可以用
/koa quiet暂停 LLM 调用，省下这段时间的 token。
报错对照表
API 出问题时，大多能从错误码直接看出原因：
| 错误码 | 原因 | 怎么办 |
|---|---|---|
| 401 / 403 | Key 不正确或已过期 | 检查 Key 是否复制完整、有没有多余空格 |
| 404 | API 地址或模型名不对 | 确认拼写；用第三方服务商时核对地址格式 |
| 429 | 请求太频繁或额度用完 | 等一等再试，或去服务商后台充值 |
| 500 / 502 | 服务商自身故障 | 稍后再试，换个时间段 |
看不出原因时，到启动器的「日志」页查看详细错误信息，通常能直接定位问题；实在解决不了，导出诊断包到帮助中心指引的渠道反馈。