功能特性

• 🤖 多接口对话：同时支持 OpenAI Chat Completions、Anthropic Messages、OpenAI Responses 三种兼容接口
• 🖼️ 多模态生成：除文本对话外，支持图像生成、视频生成（文生/图生/首尾帧/参考素材）异步任务
• 🔍 模型与计费查询：列出可用模型、查看模型详情、账户余额、用量扣费明细、充值交易流水
• 🔑 按 header 传 key：每次调用从请求 header 读取 API Key，同一部署可被多个不同账号共用，服务器不落盘、不缓存任何 key

快速开始

在 Claude Code 中使用（推荐）。用 -s user 加到 user scope（所有项目可用）。

步骤 1：添加连接

复制claude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <你的 BasicRouter API key>" \
  -s user

步骤 2：确认连接

复制claude mcp list          # 应显示 ✓ Connected
claude mcp get basicrouter  # 看到 Scope: User config (available in all your projects)

步骤 3：开始使用

在 Claude 中可以这样提问：

• "用 BasicRouter 调一下 claude-sonnet-5，写一首关于秋天的诗"
• "列一下我 BasicRouter 账户里可用的模型"
• "查一下我 BasicRouter 的余额和最近用量"
• "用 BasicRouter 生成一张赛博朋克风格的城市夜景图"

Claude 会自动调用对应的 MCP 工具并返回结果。

在 Claude Desktop 中使用

在 mcpServers 部分添加配置：

复制{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<你的 BasicRouter API key>"
      }
    }
  }
}

在 Codex CLI 中使用

推荐写法：用 env_http_headers 从环境变量读 key

先在 shell 里 export 环境变量：

复制export BASICROUTER_API_KEY=<你的 BasicRouter API key>

然后在 ~/.codex/config.toml 里：

复制[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

备选写法：用 http_headers 把 key 直接写进配置（不想单独管环境变量时可以把 key 静态写死，注意 key 会明文落在配置文件里）：

复制[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<你的 BasicRouter API key>" }

如果通过 Codex 设置界面添加：

• 类型：HTTP / Streamable HTTP
• 名称：basicrouter
• URL：https://api.basicrouter.ai/mcp
• Header 名称：X-Basicrouter-Api-Key
• Header 值：你的 BasicRouter API key

验证连接

启动 Codex CLI 后，/mcp 命令可以列出已配置的 MCP server 及其连接状态，确认连接已正常加载即可。调用方式与 Claude 一致——Codex 会自动选用对应的工具。

如果配置文件里已有其他 MCP server，按平级追加即可。改完完全退出 Claude Desktop 再重新打开。

工具说明

这个 MCP server 提供了 14 个工具。按用途分五组：

一、对话接口

1. chat_completion — Chat Completions

发送一次对话请求，返回模型完整回复（不支持流式）。除纯文本外，还支持传入图片和视频做多模态理解（需模型支持对应 vision/video 能力，可先 list_models 查看 input_modalities）——把消息的 content 从字符串改为内容块数组，混合 text 与 image_url / video_url。

多模态输入（text / image / video）

图片输入（URL 方式）：

复制{"role": "user", "content": [
  {"type": "text", "text": "这张图片里有什么？"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

图片输入（Base64 方式）：

复制{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

支持的图片格式：PNG、JPEG、GIF（仅首帧）、WebP。单张图片大小限制 20MB。

注意：大图片的 Base64 编码字符串非常长，可能因请求体过大而失败，建议优先使用 URL 方式传入。

detail 参数（可选，写在 image_url 对象上）控制图片处理精度："auto"（默认，模型按图片大小自动决定）/ "low"（512x512 缩略图，快、省，适合简单分类）/ "high"（全分辨率，适合读小字、抠细节）。一条消息的 content 数组里可放多个 image_url 块传入多张图片。

视频输入（URL 方式）：

复制{"role": "user", "content": [
  {"type": "text", "text": "描述这个视频里的内容。"},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

视频输入（Base64 方式）：

复制{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

BasicRouter 上支持 video 输入的模型包括 Qwen、Doubao（dola-seed）、Kimi、MiniMax 等系列的部分模型，具体以 list_models 返回的 input_modalities 为准。OpenAI 官方 Chat Completions 标准不原生支持视频，但 BasicRouter 网关通过

复制{"type": "video_url", "video_url": {"url": "..."}}

扩展格式支持视频输入，该格式与 OpenRouter、NVIDIA NIM、vLLM 等平台的 video_url 格式一致。

2. create_message — Anthropic Messages 兼容

调用 Anthropic Messages 兼容接口（不支持流式）。内容块支持 text、image、tool_use、tool_result、thinking、redacted_thinking。图片通过

复制{"type": "image", "source": {...}}

内容块传入。

多模态输入（text / image / video）

图片输入支持三种 source 类型：

1. Base64 编码（注意：data 字段为纯 Base64 字符串，不含 data: 前缀），media_type 支持 image/jpeg、image/png、image/gif、image/webp：

复制{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. URL 引用：

复制{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID（需先通过 Files API 以 purpose="vision" 上传图片获取 file_id）：

复制{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

一条消息的 content 数组里可放多个 image 块传入多张图片。

注意：大图片的 Base64 编码字符串非常长，可能因请求体过大而失败，建议优先使用 URL 方式传入。

视频输入：Anthropic Messages API 不支持视频文件。如需视频理解，先用 ffmpeg 等工具抽取关键帧，把每帧作为 image 内容块传入。BasicRouter 上支持视频输入的模型（可通过 list_models 查看 input_modalities 中是否包含 video）建议改用 chat_completion 或 create_response 接口以原生支持视频。

3. create_response — OpenAI Responses 兼容

用 input 代替 messages，用 instructions 代替系统消息，用 text.format 代替 response_format。除纯文本外，还支持传入图片和视频做多模态理解（需模型支持对应 vision/video 能力，可先 list_models 查看 input_modalities）——把 input 设为消息对象数组，content 用内容块数组，混合文本与图片/视频。

多模态输入（text / image / video）

注意：Responses API 的内容块类型用 input_text / input_image / input_video（而非 Chat Completions 的 text / image_url / video_url），且 image_url / video_url 直接为字符串而非嵌套对象。

图片输入（URL 方式）：

复制[{"role": "user", "content": [
  {"type": "input_text", "text": "这张图片里有什么？"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

图片输入（Base64 方式）：

复制{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

支持的图片格式：PNG、JPEG、GIF（仅首帧）、WebP。单张图片大小限制 20MB。

注意：大图片的 Base64 编码字符串非常长，可能因请求体过大而失败，建议优先使用 URL 方式传入。

图片输入（File ID 方式）：

复制{"type": "input_image", "file_id": "<file_id>"}

file_id 需通过 Files API 以 purpose="vision" 上传图片获取。

detail 参数（可选，写在 input_image 对象上）控制图片处理精度："auto"（默认）/ "low"（512x512 缩略图，快、省）/ "high"（全分辨率，读小字、抠细节）/ "original"（原始分辨率，仅部分新模型支持）。一条消息的 content 数组里可放多个 input_image 块传入多张图片。

视频输入（URL 方式）：

复制[{"role": "user", "content": [
  {"type": "input_text", "text": "描述这个视频里的内容。"},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

视频输入（Base64 方式）：

复制{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

视频输入（File ID 方式）：

复制{"type": "input_video", "file_id": "<file_id>"}

BasicRouter 上支持 video 输入的模型包括 Qwen、Doubao（dola-seed）、Kimi、MiniMax 等系列的部分模型，具体以 list_models 返回的 input_modalities 为准。OpenAI 官方 Responses API 标准不原生支持视频，但 BasicRouter 网关通过

复制{"type": "input_video", "video_url": "..."}

扩展格式支持视频输入，该格式与 BytePlus/Volcengine 等平台的 input_video 格式一致。

二、模型与账户查询

4. list_models — 列出可用模型

返回当前账户可用模型，含厂商、模态、支持的能力和定价等元数据。无参数。列表每项含 price_tiers 价格档位，返回的是当前调用方的有效计费价，与实际扣费一致（见价格档位字段说明）。

5. get_model — 查询单个模型详情

出参含 price_tiers 价格档位（见价格档位字段说明）；模型不存在时返回 404，不含价格字段。

6. get_balance — 查询账户余额

返回当前账户的用量和余额。无参数。

三、计费流水

7. list_usage — 模型调用扣费明细

分页查询模型调用计费详情，按订单创建时间倒序。仅含正常用量扣费，不含充值/调整。

8. list_transactions — 充值/套餐交易记录

分页查询已支付的充值 / 套餐购买交易记录，按创建时间倒序。

四、图像生成

9. list_image_models — 列出图像模型

返回支持的图像生成模型，含分辨率、宽高比、单次最大图片数（maxCount）、最大参考图数（fileMax）。无参数。调用图像生成前先查这个，只能传规格里公布的值。列表每项含 priceTiers 价格档位（见价格档位字段说明）。

10. create_image_generation — 提交图像生成任务

异步提交，立即返回 taskId，会消耗账户额度。

11. get_image_generation — 轮询图像任务

返回：status 为 pending（进行中）/ success（成功）/ failed（失败）；images 是图片 URL 数组的 JSON 字符串；text 携带模型附加描述（如 Gemini 多模态输出）。

五、视频生成

12. list_video_models — 列出视频模型

返回支持的视频生成模型，含 allowedVideoTypes、时长范围（videoDurationMin/Max）、分辨率、宽高比、参考素材上限（fileMax）。无参数。调用视频生成前先查这个。列表每项含 priceTiers 价格档位（见价格档位字段说明）。

13. create_video_generation — 提交视频生成任务

异步提交，立即返回 taskId，会消耗账户额度。

video_type 含义：

14. get_video_generation — 轮询视频任务

价格档位字段说明

list_models、get_model、list_image_models、list_video_models 这 4 个模型查询工具的出参会返回当前调用方（API Key 用户）的有效计费价，与实际扣费完全一致，且返回该模型的全部价格档位。

字段命名差异：list_models / get_model 沿用 OpenAI 风格下划线命名（price_tiers）；list_image_models / list_video_models 沿用 camelCase 命名（priceTiers）。两者结构完全相同。

price_tiers / priceTiers 为数组，每个元素是一个价格档位：

三种模型类型共用同一结构，仅描述字段填充不同，不适用字段为 null：

价格含义：返回的 inputPrice / outputPrice / cacheReadPrice / cacheWritePrice 等，是经价格链（chain）→ guidance → 基础价逐级解析后，针对当前 API Key 用户的最终计费单价，与实际扣费一致。调用方看到的单价会因自身所属的定价链（reseller / distributor / 企业 / 用户级配置）不同而不同。

实际扣费额 = 用量 ÷ quantity × 对应单价 × ratio。视频按秒计费时，实际扣费 = duration × outputPrice × ratio。

边界与异常处理（只读接口不会因价格配置问题返回 500）：

响应示例（list_models，文本模型）：

复制{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "每千 token",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

响应示例（list_image_models，图片模型，priceTiers 结构同上，unit 为 image）：

复制{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "每张",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

使用示例

示例 1：一次普通对话

提问："用 BasicRouter 调 claude-sonnet-5，问它 Python 的 GIL 是什么"

AI 会调用 chat_completion，参数为：

复制{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "Python 的 GIL 是什么？"}]
}

示例 2：用 Anthropic Messages 接口带工具调用

提问："用 BasicRouter 的 Messages 接口，让模型自己决定要不要查天气"

AI 会调用 create_message，传入 tools 定义和 tool_choice，返回中会包含 tool_use 内容块。

示例 3：查可用模型

提问："列一下我 BasicRouter 账户里有哪些模型"

AI 会调用 list_models，返回所有可用模型的 ID、厂商、模态、定价等信息。

示例 4：查余额和用量

提问："查一下我 BasicRouter 这个月的用量明细"

AI 会调用 get_balance 查余额，再调用 list_usage（带 start_time 限定本月）查扣费明细。

示例 5：生成图片

提问："用 BasicRouter 生成一张赛博朋克风格的城市夜景图"

AI 会先调用 list_image_models 查规格，再调用 create_image_generation 拿到 taskId，最后轮询 get_image_generation 拿到图片 URL。

示例 6：文生视频

提问："用 BasicRouter 生成一段 5 秒的太空星云视频"

AI 会先调用 list_video_models 查规格，再调用 create_video_generation（video_type=1，duration=5），拿到 taskId 后轮询 get_video_generation。

常见问题

调用工具时报 "缺少 BasicRouter API Key"

• 用 claude mcp add 时没带 --header，或 key 写错了
• 直接编辑 JSON 配置时，headers 字段名写错（应为 X-Basicrouter-Api-Key）
• 本地运行时没设环境变量 BASICROUTER_API_KEY

调用工具报 "BasicRouter 返回 401 未授权"

API Key 本身不对或已失效，去 BasicRouter 控制台重新生成。

Claude 没有调用 BasicRouter 工具怎么办？

• 用 claude mcp list 确认连接是 ✓ Connected
• 确认连接状态：claude mcp get basicrouter
• 尝试明确要求："用 BasicRouter 的 chat_completion 工具调 claude-sonnet-5 …"

图像/视频生成一直 pending

• 图像任务用 get_image_generation、视频任务用 get_video_generation 轮询，注意视频任务进行中时 status 是 "running" 不是 "pending"
• 生成需要时间，通常几秒到几十秒，视频更久
• 如果带了 callback_url，任务完成会主动回调，不需要轮询

list_image_models / list_video_models 报错

这两个工具本身不会消耗额度，报错一般是 key 或网络问题。先确认 list_models 能正常返回。

注意事项

• Header 名称：MCP 用 X-Basicrouter-Api-Key 传 key。
• 额度消耗：chat_completion / create_message / create_response / create_image_generation / create_video_generation 都会消耗账户额度，调用前可以先 get_balance 看一下余额。
• 先查规格再生成：图像/视频生成的 model、resolution、ratio、count、duration、video_type 等参数只能传 list_image_models / list_video_models 公布的值，否则会报错。
• 不支持流式：三个对话接口都不支持流式响应，一次性返回完整结果。
• 无状态设计：每次请求都是独立的，不保存会话信息；多轮对话靠 create_response 的 previous_response_id 或自己在 messages 里维护历史。