Fundamentals
先分清三种 Token
在 API 文档和模型账单中，Token 经常指向不同概念。先确认上下文，再判断它是在说身份凭证、认证格式，还是模型用量。
API Token / API Key
由平台账户创建的秘密凭证，用于证明请求来自你的账号。在 MuxLLM 文档中，“API Key”和“令牌”通常指这个概念。
Bearer Token
一种 HTTP 认证写法，表示把 API Token 放在 Authorization: Bearer ... 请求头中。它不是另一把新密钥。
模型 Token
模型拆分和处理文本时使用的计量单位，常见于输入、输出、上下文限制和文本模型计费。
不要混用
“创建一个 Token”通常是创建 API 凭证；“消耗了多少 Token”通常是在说模型输入和输出用量。两者名称相同，但用途完全不同。
API Credential
API Token 用来做什么
API Token 连接你的账户与客户端或代码项目。平台根据它识别调用者、检查可用分组与权限，并把用量记录到对应账户。
-
登录账户
进入 MuxLLM 控制台，确认账户状态和余额正常。
-
创建 Token
打开 Token 管理页面，按当前客户端、项目或环境创建独立凭证。
-
清楚命名
名称应能说明用途，例如开发环境、生产服务或某个客户端，方便后续识别和停用。
-
安全配置
把 Token 写入客户端安全存储或服务端环境变量，不要放进公开文件。
-
最小请求测试
先使用低成本的文本请求确认 Base URL、模型名、认证头和分组都正确，再投入正式使用。
建议拆分
不要让所有客户端、项目和团队共用同一个 Token。按用途拆分后，更容易查看用量、定位异常，并只停用受影响的入口。
Authentication
同一把 Key，认证头可能不同
认证头由调用协议决定。模型名称相同，也不能因此把 OpenAI、Claude 和 Gemini 的请求头混在一起使用。
| 协议或端点 |
请求头 |
填写格式 |
| openai |
Authorization |
Bearer YOUR_API_KEY |
| openai-response |
Authorization |
Bearer YOUR_API_KEY |
| anthropic |
x-api-key |
YOUR_API_KEY |
| gemini |
x-goog-api-key |
YOUR_API_KEY |
OpenAI: Authorization: Bearer YOUR_API_KEY
Claude: x-api-key: YOUR_API_KEY
Gemini: x-goog-api-key: YOUR_API_KEY
只填一次
如果客户端已有独立的 API Key 输入框，不要再把 Token 拼进 Base URL，也不要同时在多个认证位置重复填写。
Security
安全保存、拆分与轮换
API Token 应按密码级别保护。它一旦被泄露，其他人可能以你的账户身份发起请求并消耗余额。
客户端使用
只保存到可信客户端提供的密钥字段或系统安全存储，不要把配置页面连同完整 Token 截图分享。
服务端使用
优先使用环境变量或服务端密钥管理，不要直接写进源码、镜像、构建产物或日志。
代码仓库
不要提交到 Git 仓库、示例配置或前端 JavaScript。需要示例时统一使用 YOUR_API_KEY。
定期检查
通过 Token 名称和用量日志识别长期不用或异常使用的凭证，及时停用并替换。
怀疑 Token 泄露时
- 立即停用先阻止旧 Token 继续产生请求，不要等待排查完成。
- 创建替代项为受影响的客户端或服务创建新 Token，并更新安全配置。
- 检查用量查看异常时间段、模型、分组和请求错误，不要在工单或聊天中提供完整 Token。
- 缩小范围确认泄露来源并移除公开文件、截图、日志或错误配置中的凭证。
前端禁区
不要把长期有效的 API Token 写入公开网页、浏览器前端代码或可下载的静态资源。浏览器中的任何访问者都可能读取这些内容。
Model Usage
模型 Token 是怎样产生的
文本模型会把内容拆分成内部可处理的片段。Token 不是固定字数，也不等于一个汉字或一个英文单词；拆分结果会随语言、符号、代码和模型而变化。
输入 Token
通常包括系统提示词、用户消息、历史对话、工具定义和随请求发送的其他文本内容。
输出 Token
模型实际生成的回复内容。更长的回答和更高的输出上限通常会提高潜在用量。
上下文窗口
模型一次请求能够处理的总内容范围。输入、历史消息和计划输出通常会共同占用可用空间。
缓存 Token
部分模型或协议可能单独报告可复用输入，并使用不同计费规则；是否支持应以实时模型信息和调用日志为准。
| 内容 |
通常影响 |
优化方向 |
| 长系统提示词 |
每次请求的输入用量 |
删除重复规则，保留真正生效的约束 |
| 完整历史对话 |
上下文长度和输入用量 |
按任务保留必要历史，适时总结旧内容 |
| 大段工具定义 |
输入 Token 和上下文空间 |
只加载当前任务需要的工具 |
| 过高输出上限 |
潜在输出量和请求延迟 |
根据任务设置合理上限 |
不能硬换算
不要用固定的“一个 Token 等于几个字”估算所有模型。需要准确用量时，优先查看兼容响应中的 usage 信息和 MuxLLM 用量日志。
Context & Billing
上下文、用量与费用
对按文本 Token 计费的模型，可以用下面的简化关系理解费用组成。实际账单还可能受到模型、分组、缓存规则和平台计费方式影响。
文本模型费用 ≈ 输入用量 × 输入单价 + 输出用量 × 输出单价
先看模型
不同模型的输入、输出和缓存规则可能不同，不能把一个模型的价格套用到另一个模型。
再看分组
同一模型在不同分组下可能有不同倍率或可用性，调用前应确认实际选择的分组。
核对日志
响应中的 usage 便于程序观察单次用量，控制台用量日志用于核对平台实际记录。
媒体模型例外
图片、视频和音频模型可能按次、尺寸、时长、清晰度或其他规格计费，不应套用文本 Token 公式。
动态信息
本文不保存固定价格、模型数量、上下文长度或通用换算比例。调用前请以实时模型广场展示的信息为准。
Troubleshooting
Token 相关错误怎么排查
不要把所有失败都归因于“Token 不对”。状态码只能帮助缩小范围，还要结合账户、分组、模型、端点和用量日志判断。
| 现象 |
常见原因 |
优先检查 |
| 401 |
API Token 缺失、无效，或认证头与协议不匹配 |
Token 是否完整、请求头名称、Bearer 前缀 |
| 403 |
账号、分组、模型权限或网络防护限制 |
账号状态、Token 分组、目标模型权限 |
| 429 |
请求频率、可用额度、分组负载或上游暂时繁忙 |
余额与额度、并发、日志错误、稍后重试 |
| 上下文错误 |
输入内容和计划输出超过模型可处理范围 |
缩短历史、提示词、工具定义或输出上限 |
| 费用高于预期 |
历史对话过长、输出较多、分组或计费规格不同 |
模型、分组、usage、平台用量日志和实时价格 |
- 1
确认凭证检查使用的是目标 Token，并确认认证头与调用协议一致。
- 2
确认账户检查账号状态、余额和 Token 当前是否可用。
- 3
确认模型核对模型名、分组和模型广场显示的端点标签。
- 4
检查日志记录请求时间、模型名和错误信息，排查时不要提供完整 Token。
FAQ
常见问题
API Token 和 API Key 是同一个东西吗？
在 MuxLLM 的调用场景中，两者通常都指账户创建的 API 凭证。Bearer Token 则是 OpenAI 兼容协议中携带这把 Key 的认证写法。
一把 Token 可以用于 OpenAI、Claude 和 Gemini 协议吗？
取决于账户、分组和目标模型是否支持对应端点。即使使用同一把 Key，不同协议的 Base URL、路径、认证头和请求体仍必须分别正确配置。
为什么 Token 有效，调用仍然失败？
有效凭证只解决身份认证，还需要同时满足账户余额、分组权限、模型可用性和端点匹配。请结合错误信息与用量日志排查。
模型 Token 能精确换算成汉字或英文单词吗？
不能使用一个固定比例覆盖所有语言和模型。标点、代码、空格、词形和模型分词方式都会影响结果，准确用量应以实际 usage 和平台日志为准。
max_tokens 是 API Token 吗？
不是。它通常表示模型允许生成的最大输出 Token 数，属于请求参数；API Token 则是身份认证凭证。
怀疑 API Token 泄露后，可以只修改客户端配置吗？
不够。应先停用旧 Token，再创建并安全配置替代项，同时检查异常用量和泄露来源。
