矩池云

API Key 入门教程

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

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 前，请先完成以下准备工作：

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

3. 充值

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

充值入口：

Key- 打开 Matpool 工作空间

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

说明：

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

alt text

4. API Key 管理

API Key 管理入口：

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

  • 创建新的 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 CLI 使用** 待完善

7.2 独立原生环境配置教程

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

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

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

** Claude Code 配置** 待完善

** Codex 配置** 待完善

** Gemini 配置** 待完善

8. 消费日志

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

入口：

通常可用于查看：

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

alt text

9. 账单与余额查看

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

入口：

可关注的信息包括：

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

alt text

10. 模型信息

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

使用说明：

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

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 及时停用
Copyright © 2019-2026 matpool.com. All rights reserved.

Command Palette

Search for a command to run...