接入文档
MaxMind API 使用与 OpenAI 兼容的 API 格式。通过修改配置，您可以使用 OpenAI SDK 来访问 MaxMind API，或使用任何与 OpenAI API 兼容的软件。
| 参数 | 值 |
| --- | --- |
| Base URL (OpenAI) | `https://api.maxmind.online/v1` |
| api_key | 在控制台申请一个 [API Key](https://maxmind.online/) |
| model | `maxmind-2.1-flash-0924`(1)
`maxmind-2.0-pro-preview-0925`(2) |
(1) MaxMind 2.1 Flash —— 最新旗舰模型。
(2) MaxMind 2.0 Pro-Preview —— 旗舰级推理模型。
模型 ID 与显示名称不同，调用时填模型 ID。用 `GET /models` 可随时拿到最新清单。
## 接入 Agent 工具
MaxMind 可接入多种主流 AI Agent 与编程助手工具。如果你使用 Claude Code、GitHub Copilot、OpenCode、RikkaHub 等工具，可以直接将 MaxMind 作为后端模型，无需编写代码即可开始使用。
## 鉴权
每个请求都必须在 HTTP 头里带上你的 API Key：
```http
Authorization: Bearer sk-你的钥匙
```
- 钥匙等同密码，不要写进前端代码、公开仓库或截图。
- 钥匙可以随时在控制台删除，删除后立即生效。怀疑泄露就立刻删掉重建，成本为零。
- 一把钥匙可以配独立的额度上限与每分钟请求数（RPM），与账号共享同一份总额度。
- 不要把 Key 放在浏览器端（fetch 直连）、App 安装包或任何用户能看到的地方。正确做法是自己的后端持有 Key，浏览器只调用你自己的后端。
## 调用对话 API
在创建 API Key 之后，你可以使用以下样例脚本，通过 OpenAI API 格式来访问 MaxMind 模型。样例为非流式输出，您可以将 stream 设置为 true 来使用流式输出。
#### curl
```bash
curl https://api.maxmind.online/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${MAXMIND_API_KEY}" \
-d '{
"model": "maxmind-2.1-flash-0924",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
"thinking": {"type": "enabled"},
"reasoning_effort": "high",
"stream": false
}'
```
#### python
```python
# Please install OpenAI SDK first: `pip3 install openai`
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get('MAXMIND_API_KEY'),
base_url="https://api.maxmind.online/v1")
response = client.chat.completions.create(
model="maxmind-2.1-flash-0924",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "Hello"},
],
stream=False,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}}
)
print(response.choices[0].message.content)
```
#### nodejs
```javascript
// Please install OpenAI SDK first: `npm install openai`
import OpenAI from "openai";
const openai = new OpenAI({
baseURL: 'https://api.maxmind.online/v1',
apiKey: process.env.MAXMIND_API_KEY,
});
async function main() {
const completion = await openai.chat.completions.create({
messages: [{ role: "system", content: "You are a helpful assistant." }],
model: "maxmind-2.1-flash-0924",
thinking: {"type": "enabled"},
reasoning_effort: "high",
stream: false,
});
console.log(completion.choices[0].message.content);
}
main();
```
## 推理模式（思考）
有些模型在正式回答前会先「想一遍」。这段思考会通过流式的 `delta.reasoning_content`（非流式则是 `message.reasoning_content`）单独下发，和正文分开，方便你决定是显示还是折叠。
- 不是每个模型都支持思考；本站已按模型做好映射，你只需要传 `reasoning_effort`，具体参数由本站自动处理。
- 想少想点或不想：传 `reasoning_effort: "minimal"` 或 `"low"`。
- 思考过程计入输出用量，开启思考会消耗更多额度。
## 模型列表
`GET /models` 返回当前可用的模型，向下兼容 OpenAI 的 `object: "list"` 结构。
```bash
curl https://api.maxmind.online/v1/models \
-H "Authorization: Bearer ${MAXMIND_API_KEY}"
```
| 模型 ID | 名称 | 思考 |
| --- | --- | --- |
| `maxmind-2.1-flash-0924` | MaxMind 2.1 Flash | 可调档位 |
| `maxmind-2.0-pro-preview-0925` | MaxMind 2.0 Pro-Preview | 可调档位 |
以接口返回的清单为准：某个模型不在清单里，就是当前不可用。
## 计费与额度
- 计费口径：按实际用量（输入 + 输出，含思考输出）实时折算成额度扣减，不同模型的折算比例不同。具体比例与单价为内部设置，不在文档中公开。
- 实时扣减：边生成边记账。生成过程中打开控制台「用量」页，能看到剩余额度百分比在一格格降，不用等回答结束。
- 失败不白扣：请求在产出任何内容前就失败（服务繁忙 / 超时 / 连不上），这条预记会退掉，不扣你的额度。
- 账号额度同时受三个窗口约束，任一触顶即暂停，等窗口滚动后自动恢复：5 小时（滚动窗口，拦短时间大批量调用）、日（自然日，按你所在时区）、周（滚动一周，拦长期慢性高消耗）。
- 请求前超限：直接拒绝，返回 429 与结构化额度错误（含窗口名与重置时间），不会产生任何消耗。
- 生成中途越线：服务立刻停止输出，已产出的部分按实际用量结算，紧跟一条 `insufficient_quota` 错误块。不会悄悄继续烧。
## 错误处理
出错时返回标准错误结构，并带上对应的 HTTP 状态码：
```json
{
"error": {
"message": "API Key 无效或已被删除",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
```
| 状态码 | 含义 | 怎么处理 |
| --- | --- | --- |
| 400 | 请求体不合法：缺 model / messages，或参数类型不对 | 按 error.message 修正请求 |
| 401 | Key 无效、已被删除 | 检查 Authorization 头，或到控制台重建钥匙 |
| 403 | 账号被停用 / 模型未授权 / 维护中 | 联系管理员 |
| 404 | 模型不存在，或模型当前不可用 | 用 GET /models 拿当前可用的模型列表 |
| 429 | 触发速率限制或额度耗尽 | 指数退避重试；额度耗尽请到控制台查看用量 |
| 500 | 服务端异常 | 可安全重试；持续失败请联系管理员 |
| 502 / 504 | 服务超时或不可达 | 重试；若持续，换一个模型 |
流式中途额度越线时，输出立即停止，服务端会在同一个 SSE 流里补发一个错误块再收尾，客户端应检查 `error.code == "insufficient_quota"` 并停止重试直到额度重置。
## 限流与并发
- 速率限制：按 IP、按账号、按 Key 三个维度分别限流，超限返回 429。
- 并发限制：同时进行中的请求数有上限，超出会排队或拒绝。
- 流式输出节奏：为保护服务链路，下行速度会被平滑；第一个 token 永远立即返回。
- 遇到 429 时请用指数退避重试：第一次等 1 秒，之后每次翻倍并加随机抖动，最多重试 5 次。不要用固定间隔狂重试。
## 客户端接入
常见的桌面 / 网页客户端都按「OpenAI 兼容自定义供应商」接入，三项配置：
| 配置项 | 填什么 |
| --- | --- |
| API 地址 / Base URL | `https://api.maxmind.online/v1`（已含 /v1，不要再拼路径） |
| API Key | 你的 sk- 开头钥匙 |
| 模型 / Model | 本站模型 ID（见模型列表），部分客户端要手动添加 |
- Cherry Studio：设置 → 模型服务 → 添加「OpenAI 兼容」供应商，填上面三项后点「管理」可自动拉取模型列表。
- ChatBox：设置 → 模型 → 「使用自定义 API Key」，模式选 OpenAI 兼容，模型名手动填本站模型 ID。
- LobeChat / 其它：凡是支持「自定义 OpenAI Base URL」的都一样：地址 + 钥匙 + 模型 ID。
客户端里如果模型列表拉取失败，多半是 Base URL 多了或少了 /v1。本站的 Base URL 已经包含 /v1。
## 常见问题
- 调用返回 404，说模型不存在？三种可能：① 模型名填错了，要填模型 ID 不是显示名称，先用 `GET /models` 拿一份最新列表；② 这个模型当前不可用；③ 模型被停用了。
- SDK 报 Connection error 或证书错误？确认 base_url 用的是 https:// 且以本站地址结尾、不带 /chat/completions。本站 OpenAI 的 /v1 已经包含在 Base URL 里。
- 回答是流式的，但我想等完整结果？不要传 stream（或传 false），服务端会一次性返回完整 JSON。
- 思考内容能单独关掉吗？能，传 `reasoning_effort: "minimal"` 或 `"low"`。
- 为什么同样的问题，字数一样但扣费不同？扣费按各模型的实际用量折算，不同模型的折算比例不同，是否开启思考也会影响。
- 回答生成到一半突然停了，还收到「额度已用完」？这是额度实时闸门在工作：生成过程中你的消耗越过了某个窗口的上限，服务立即停止生成避免继续扣额度，已产出的部分照实结算。等窗口重置（错误信息里有具体时间），或升级套餐提高额度。
- 用量页的百分比在跳动，正常吗？正常，而且是特性 —— 本站边生成边计费，剩余百分比实时反映当前这次请求已经消耗了多少，回答结束后会按真实用量精确结算一次。
- 换了模型要不要改代码？只改请求里的 model 字段即可，协议完全一致。