API Key 入门教程

本文介绍 Matpool API Token 的获取、充值、调用方式，以及消费记录和账单查看方法。

1. 概述及计费规则

API Key 是身份验证凭据，用于调用 Matpool 提供的大规模语言模型接口。模型调用成功后，系统会根据实际产生的资源消耗（Token 数量），自动从您的账户中扣除对应的“模力豆”。

1.1 基础说明

计费单位：模力豆（兑换比例：1 模力豆 = 1 元人民币）。
扣费方式：后付费模式。模型调用产生消耗后，系统将自动从账户中的模力豆余额内扣减对应费用。（注：目前不支持直接扣除账户资金余额，请确保模力豆数量充足）。
模型单价：不同模型的定价有所差异，具体计费单价请以官网模型广场公布的实时价格为准。

1.2 模型计费公式

不同架构的模型计费细节略有不同，主要分为以下三种情况：

基础计费规则（适用于绝大部分模型）

单次结算费用 = (输入 Token 数 ÷ 1,000,000) × 输入单价 + (输出 Token 数 ÷ 1,000,000) × 输出单价

阶梯计费（针对上下文长度动态调价）

部分模型支持较长上下文且采用阶梯计费规则，此类模型会根据用户单次请求的 实际输入 Token 数量 匹配对应的单价。 例如：某模型规定输入 Token < 32k 时，单价为 4 元 / 百万 Token；当输入 Token ≥ 32k 时，单价将调整为 8 元 / 百万 Token。

2. 使用前准备

在调用 API 前，请先完成以下准备工作：

注册并登录 Matpool 账户
充值模力豆
创建并保存 API Token
使用 Token 调用接口

3. 充值

Token 调用产生的消耗会扣除模力豆，因此请先确保账户中采购足量的模力豆。

充值入口：

Key- 打开 Matpool 工作空间

在左上角点击“采购算力豆/模力豆”
按页面提示完成充值

说明：

模力豆数量不足时，接口调用可能失败，或无法继续发起请求
充值、模力豆和其他费用明细均可在我的账户中查看

alt text

4. API Key 管理

API Key 管理入口：

Matpool 工作空间（左侧菜单）-模型API

你可以在该页面完成以下操作：

创建新的 API Token
查看已有 Token
管理或停用不再使用的 Token

使用建议：

为不同项目分别创建独立 Token，便于隔离和排查
不要在前端代码中暴露 Token
不要将 Token 提交到 Git 仓库
如怀疑泄露，请立即在 Key 管理页面停用并重新生成

alt text

创建 API Key

在API Key 管理页面点击创建按钮即可创建使用建议：

Key的名称请认真填写，便于识别（如生产/测试）
当前不支持限制可用模型：用户可以按需在调度时指定模型，具体支持模型请查看模型广场
过期时间：可按需进行配置，打开开关即设置为永久过期
额度：可按需进行配置，打开开关即设置为无限额度（不推荐）（最终可用额度为配置额度和模力豆余数的最大值）

alt text

5. 接口地址

当前调用地址示例：

text
复制代码
https://token.matpool.com/v1/chat/completions

鉴权方式：

http
复制代码
Authorization: Bearer YOUR_API_TOKEN

请求头中需要包含：

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

6. API 调用

curl 示例

bash
复制代码
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "kimi-k2.5",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant" },
      { "role": "user", "content": "给我一段产品发布文案" }
    ],
    "temperature": 0.7
  }'

** 请求参数说明**

model：要调用的模型名称，例如 kimi-k2.5
messages：对话消息列表
temperature：生成随机性，数值越高结果越发散

** messages** 字段示例

system：系统提示词，用于设定模型行为
user：用户输入内容

示例：

json
复制代码
[
  { "role": "system", "content": "You are a helpful assistant" },
  { "role": "user", "content": "给我一段产品发布文案" }
]

Python 原生请求示例 (requests)

python
复制代码
import requests

url = "https://token.matpool.com/v1/chat/completions"
token = "your_api_key_here"

payload = {
    "model": "kimi-k2.5",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "给我一段产品发布文案"},
    ],
    "temperature": 0.7,
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

response = requests.post(url, json=payload, headers=headers, timeout=60)

print(response.status_code)
print(response.text)

推荐：使用 OpenAI Python SDK

因为 Matpool 接口与 OpenAI 规范完全兼容，绝大多数开发者更倾向于使用官方的 openai Python 库进行丝滑切换。你只需要覆盖 base_url 即可：

python
复制代码
from openai import OpenAI

client = OpenAI(
    api_key="your_api_key_here",
    # 替换 Base URL 为 Matpool 接口地址
    base_url="https://token.matpool.com/v1" 
)

response = client.chat.completions.create(
    model="kimi-k2.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "给我一段产品发布文案"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

推荐：使用 OpenAI Node.js SDK

同理，对于前端或 Node 端开发者，建议通过官方 openai npm 包进行调用：

javascript
复制代码
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "your_api_key_here",
  baseURL: "https://token.matpool.com/v1" // 替换为 Matpool 接口地址
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "kimi-k2.5",
    messages: [
        { role: "system", content: "You are a helpful assistant" },
        { role: "user", content: "给我一段产品发布文案" }
    ],
    temperature: 0.7,
  });

  console.log(completion.choices[0].message.content);
}

main();

7. 常见 AI 编程工具接入与配置指南

在使用诸如 Claude Code、Codex 等 AI 辅助开发工具时，只需将它们的地址请求指向 Matpool API 即可无缝享受本平台的算力。这里提供使用 CC-Switch 可视化应用（推荐）或直接使用 原生 CLI 配置 两种方式供你选择。

7.1 CC-Switch 客户端配置指南（推荐）

CC-Switch 是一款集成多种 AI 工具（Claude Code/Codex/Gemini）的跨平台可视化应用。使用该工具可以最大程度简化并管理你的模型供应商。

通用步骤

下载并运行 CC-Switch 客户端。
导航至 Providers (供应商) 页面，点击新增自定义 Provider。
名称：填写 Matpool。
Base URL：填写 https://token.matpool.com。
API Key：填入在此前管理后台生成的专属 Token。
点击保存，稍后再在具体的辅助工具模块下将供应商指定为 Matpool。

Claude Code 配置

在 CC-Switch 主界面顶部，切换到 Claude Code 工作台标签页。
在提供商（Provider）下拉菜单中选中刚才预设的 Matpool。
在模型文本框里输入希望调用的确切模型（如 kimi-k2.5 等）。
保存配置并启动即可生效。其他配置同理

Codex 配置

在主界面顶部切换至 Codex 标签页。
将提供商选项指定为 Matpool。
在文本框指定你想选用的模型 ID（模型全称拼写见模型广场）。
保存配置后，启动工具即可。

Gemini 配置

切换至 Gemini CLI 工作面板。
同样将底层数据源 (Provider) 设定为 Matpool。
补充所需模型名并启动客户端。

CC-Switch CLI 使用

下载与安装，以MacOs为例：

bash
复制代码
# 下载 Universal Binary（推荐，支持 Apple Silicon + Intel）
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-darwin-universal.tar.gz
# 解压
tar -xzf cc-switch-cli-darwin-universal.tar.gz
# 添加执行权限
chmod +x cc-switch
# 移动到 PATH
sudo mv cc-switch /usr/local/bin/
# 如遇 "无法验证开发者" 提示
xattr -cr /usr/local/bin/cc-switch

常用命令

bash
复制代码
cc-switch provider list              # 列出供应商
cc-switch provider switch <id>       # 切换供应商
cc-switch mcp sync                   # 同步 MCP 服务器

# 使用全局 `--app` 参数来指定目标应用：
cc-switch --app claude provider list    # 管理 Claude 供应商
cc-switch --app codex mcp sync          # 同步 Codex MCP 服务器
cc-switch --app gemini prompts list     # 列出 Gemini 提示词

# 支持的应用：`claude`（默认）、`codex`、`gemini`

安装好CC Switch CLI后，在终端运行以下命令进入TUI界面(这里以claude code的配置为例，codex与gemini配置同理)

bash
复制代码
cc-switch

根据提示输入a新增 cc-switch-6 模版选择自定义 cc-switch-7 填写URL、模型信息以及APIkey,与cc-switch同理 cc=swicth-8 填写之后保存即可

若你开发偏好在 Linux 终端全键盘操作，也可通过 cc-switch 的 CLI 指令令通道快速生效：

bash
复制代码
# 全局设置默认数据源为 Matpool
cc-switch set default-provider matpool
# 注射环境变量映射
cc-switch set matpool-token "YOUR_API_TOKEN"
cc-switch set matpool-base "https://token.matpool.com"

7.2 独立原生环境配置教程

如果不使用或未安装 CC-Switch，通过直接导出终端当前会话的底层环境变量同样可以实现请求转发。

** 环境检查** 在修改环境前，请确保：

本地连接状态正常且可以访问公共域名 token.matpool.com。
检查此前项目中是否携带死板的 .env 约束或者系统级环境（如全局的 ~/.anthropic 缓存）。这可能会覆盖你马上配置的环境变量，排错时请首查此类残留文件。

Claude Code 配置

因其强绑定 Anthropic SDK 发送请求，配置以下环境变量会将请求自动重新路由至 Matpool。

bash
复制代码
# Mac/Linux 终端环境配置
export ANTHROPIC_BASE_URL="https://token.matpool.com"
export ANTHROPIC_API_KEY="your_api_key_here"

# 临时作用于你的终端，配置后即可启动
claude

Codex 配置

多数通用底层兼容标准 OpenAI 请求路径规范。

bash
复制代码
export OPENAI_BASE_URL="https://token.matpool.com"
# 不同实现版本可能用到这个备用名：
export OPENAI_API_BASE="https://token.matpool.com/v1"

export OPENAI_API_KEY="your_api_key_here"

Gemini 配置

对于 Gemini CLI 或调用 SDK 发起请求的插件：

bash
复制代码
export GEMINI_API_KEY="your_api_key_here"
# 注意：若原始工具不支持 Base URL 重定向更改，建议你配合 LiteLLM 做端口转发。否则可以直接使用以下变量：
export GOOGLE_GENAI_BASE_URL="https://token.matpool.com"

8. 消费日志

你可以在消费日志页面实时查看 Token 调用产生的消费记录。

入口：

消费日志

通常可用于查看：

某个时间段内的调用消耗
调用记录对应的费用情况
累计消费金额

alt text

9. 账单与余额查看

除了消费日志外，你还可以在用户中心查看整体账单和模力豆充值记录。

入口：

Matpool 用户中心

可关注的信息包括：

当前模力豆余额
模力豆充值记录
模力豆消费明细

alt text

10. 模型信息

模型信息以平台实际提供的模型列表为准。模型信息详见模型广场模型广场入口：导航栏-产品服务-模型广场 alt text

使用说明：

调用时的模型id，请复制ID

11. 常见问题

401 Unauthorized

可能原因：

Token 无效
Token 已停用
Authorization 请求头缺失
未按 Bearer YOUR_API_TOKEN 格式传递

403 Forbidden

可能原因：

当前 Token 没有对应权限
账户状态受限

余额不足

可能原因：

模力豆余额不足

建议处理方式：

前往用户中心充值模力豆
再次发起请求

取消请求或 429 Too Many Requests

可能原因：

并发请求数量超过了平台针对该模型设置的限流（Rate Limit）或 QPS 限制
账户模力豆耗尽并强行继续请求被拦截（通常抛出 429 提示额度不足）

建议处理方式：

在代码中加入重试机制（Retry logic）与指数退避（Exponential backoff）
前往用户中心检查当前模力豆余额

请求成功但结果不符合预期

建议优先检查：

model 是否填写正确
messages 是否符合预期
system 提示词是否限制过多
temperature 是否设置过高

12. 安全建议

使用环境变量保存 Token，不要写死在代码里
不要在前端网页直接暴露 Token
不要通过聊天工具明文传播正式环境 Token
按项目、环境或团队拆分 Token，便于管理
对不再使用的 Token 及时停用

入门指引

教程与案例

参考资料

联系我们

API Key 入门教程

1. 概述及计费规则

1.1 基础说明

1.2 模型计费公式

基础计费规则（适用于绝大部分模型）

阶梯计费（针对上下文长度动态调价）

2. 使用前准备

3. 充值

4. API Key 管理

创建 API Key

5. 接口地址

6. API 调用

curl 示例

Python 原生请求示例 (requests)

推荐：使用 OpenAI Python SDK

推荐：使用 OpenAI Node.js SDK

7. 常见 AI 编程工具接入与配置指南

7.1 CC-Switch 客户端配置指南（推荐）

通用步骤

Claude Code 配置

Codex 配置

Gemini 配置

CC-Switch CLI 使用

7.2 独立原生环境配置教程

Claude Code 配置

Codex 配置

Gemini 配置

8. 消费日志

9. 账单与余额查看

10. 模型信息

11. 常见问题

401 Unauthorized

403 Forbidden

余额不足

取消请求或 429 Too Many Requests

请求成功但结果不符合预期

12. 安全建议

Command Palette