MCP 工具

MCP 服务器的十一个工具:各自接受什么、返回什么,以及何时会拒绝。

MCP 服务器的地址是 https://binference.io/api/mcp。连接客户端的方法见 MCP 服务器。

请求

  • Streamable HTTP,不使用会话。它支持 MCP 的 2026-07-28 版本和所有 2025 年的版本。每个请求都是独立的,所以每条消息都是一个 POST。GET 和 DELETE 返回 405。
  • 每个请求都要带上密钥,格式为 Authorization: Bearer binf_... 或 x-api-key。
  • 请求体要小。超过 64 KB 的请求返回 413。
  • 每个密钥每分钟 60 个请求,暂停一段时间后最多可以一次发 20 个。超过这个速度返回 429。
  • 工具列表固定。连接期间工具不会变化,所以服务器不发送变更通知,也不打开监听流。
  • 可以从任何地方调用。和 API 的其他部分一样,任何来源(origin)都可以调用它。
  • 文件夹的密钥只在自己的文件夹内。为 Agent 文件夹(在驾驶舱中)创建的密钥,只能查看和管理该文件夹的密钥和调用记录。它的余额和用量仍是整个账户的。

HTTP 返回

每个工具都返回 200,即使它拒绝了请求(见拒绝)。其他状态码都出现在工具运行之前:

状态码error何时出现
401unauthorized没有发送密钥
401invalid_token密钥错误或已撤销
403该密钥所属的 Agent 文件夹已暂停。请在它的驾驶舱中恢复
405GET 或 DELETE 请求
413请求体超过 64 KB
429该密钥每分钟超过 60 个请求。在 retry-after 之后重试
503temporarily_unavailable无法验证密钥。在 retry-after(2 秒)之后重试

401 带有 WWW-Authenticate: Bearer realm="binference"。没有 OAuth 登录:密钥是唯一的访问方式。

429 会带上以秒为单位的 retry-after 和精确的 retry-after-ms,以及一个说明等待时间的 JSON-RPC 错误:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "This key is making MCP requests faster than 60 a minute. Retry in 2 seconds."
  }
}

结果

每个工具都会返回两份结果:一份是 structuredContent,符合该工具的输出 schema;另一份是放在文本块中的相同 JSON,供只读取文本的客户端使用。

  • 金额以美元计,用精确的十进制字符串表示,比如 "0.0012"。不要把它转成浮点数再转回来。
  • 时间为 UTC 的 ISO 8601 格式。日期是 UTC 日期,比如 "2026-09-30"。
  • 读取类工具标记为只读,所以客户端可以不经询问直接运行。revoke_key 标记为破坏性操作,所以客户端知道要先询问。

拒绝

工具无法完成请求时,会返回 isError: true 和一句说明原因的话。请把它展示给用户,或者据此处理:

{
  "content": [
    {
      "type": "text",
      "text": "This key has a spending limit, so it can only read. Use a key without a limit to create, change or revoke keys, or manage them at https://binference.io/account/keys."
    }
  ],
  "isError": true
}
消息开头原因
This key has a spending limit只有不设消费上限的密钥才能创建、修改或撤销密钥
No key 12 belongs to this agent该密钥 ID 属于其他 Agent,或者不存在
This agent already has 10 active keys先撤销一个
This agent made 20 keys over MCP在任意 24 小时内最多创建 20 个。稍后再试,或者在 API 密钥页面创建
This agent is not active已暂停的 Agent 无法获得新密钥
label: 或 spending_limit.usd:该输入有误。这句话的其余部分会说明原因
Input validation error某个输入缺失、类型错误或超出范围
bInference could not finish this right now你这边没有问题。稍后重试

get_balance

密钥能花多少。没有输入。它的返回体与查询余额相同。

{
  "object": "balance",
  "agent": {
    "id": 42,
    "name": "Nova",
    "token": "0x9f3c7e2b8a41d05c6e1f9a8b7c2d3e4f50617777",
    "status": "active"
  },
  "spendable_usd": "18.40211",
  "balance_usd": "18.42211",
  "reserved_usd": "0.02",
  "running_calls": 1,
  "expiring": [
    { "at": "2026-10-02T00:00:00.000Z", "usd": "2.1084" },
    { "at": "2026-10-03T00:00:00.000Z", "usd": "4.92" }
  ],
  "key_limit": null
}
  • spendable_usd 是新调用现在可以预留的金额:余额减去运行中的调用占用的部分。
  • expiring 是每天的额度还剩多少、何时过期,最早过期的排在前面。额度有效期 7 天。
  • key_limit 是这个密钥的消费上限,没有则为 null。它的字段与下文的 spending_limit 相同。
  • 账户的 agent.token 为 null。

get_limits

这个密钥及其 Agent 的限制。没有输入。

{
  "key": {
    "id": 12,
    "label": "prod-server",
    "prefix": "binf_7Hq2xYv9aB",
    "can_manage_keys": false,
    "spending_limit": {
      "limit_usd": "5",
      "reset": "daily",
      "spent_usd": "1.2",
      "reserved_usd": "0.02",
      "remaining_usd": "3.78",
      "resets_at": "2026-10-01T00:00:00.000Z"
    }
  },
  "agent": {
    "calls_per_minute": 600,
    "burst": 60,
    "max_running_calls": 8,
    "running_calls": 1,
    "max_active_keys": 10,
    "active_keys": 3
  },
  "request": { "max_body_mb": 4, "max_stream_minutes": 30, "max_call_minutes": 13 },
  "mcp": { "requests_per_minute": 60, "burst": 20, "keys_per_day": 20 },
  "images": {
    "uploads_per_day": 200,
    "max_upload_mb": 20,
    "upload_link_hours": 24,
    "result_link_days": 7,
    "max_results_gb": 5
  }
}
  • 密钥没有消费上限时,can_manage_keys 为 true。
  • spending_limit.remaining_usd 是该密钥在本周期内还可以发起的金额:上限减去已花费的金额和运行中的调用占用的金额。
  • agent 中的限制由该 Agent 的所有密钥共享。参见速率限制。
  • mcp 是这个服务器自己的限制:每个密钥的请求数,以及 Agent 在 24 小时内可以在这里创建的密钥数。
  • images 是图像存储允许该 Agent 使用的量。

get_usage

Agent 按天和按模型统计的花费。它统计该 Agent 的所有密钥。

输入类型默认值含义
daysinteger7往回统计多少个 UTC 日,包括今天:1 到 90。1 表示只看今天
{
  "from": "2026-09-24",
  "to": "2026-09-30",
  "total": { "usd": "3.4102", "calls": 212, "tokens": 1840210 },
  "days": [
    { "day": "2026-09-29", "usd": "1.9", "calls": 130, "tokens": 1102400 },
    { "day": "2026-09-30", "usd": "1.5102", "calls": 82, "tokens": 737810 }
  ],
  "models": [
    {
      "model": "anthropic/claude-sonnet-5.5",
      "name": "Claude Sonnet 5.5",
      "usd": "3.1",
      "calls": 120,
      "tokens": 1400000
    },
    {
      "model": "google/gemini-3.8-flash",
      "name": "Gemini 3.8 Flash",
      "usd": "0.3102",
      "calls": 92,
      "tokens": 440210
    }
  ]
}

没有调用的日子不会列出。模型按花费从高到低排列。调用的费用确定后才会计入,通常在一分钟内。

list_calls

Agent 的调用,最新的在前。

输入类型默认值含义
key_idinteger只看这个密钥的调用
limitinteger20每页的调用数,1 到 50
beforestring上一页的 next 值,用于获取更早的调用
{
  "calls": [
    {
      "id": 88412,
      "started_at": "2026-09-30T11:02:41.118Z",
      "duration_ms": 2840,
      "key": { "id": 12, "label": "prod-server", "prefix": "binf_7Hq2xYv9aB" },
      "model": "anthropic/claude-sonnet-5.5",
      "model_name": "Claude Sonnet 5.5",
      "endpoint": "messages",
      "stream": true,
      "outcome": "ok",
      "http_status": 200,
      "error_code": null,
      "tokens": {
        "prompt": 8120,
        "completion": 412,
        "reasoning": null,
        "cached": 6400
      },
      "reserved_usd": "0.1",
      "charge_usd": "0.0142"
    }
  ],
  "next": "88412"
}
  • outcome 为 running、pending(已结束,费用尚未确定)、ok、stopped(你这边断开了连接)或 failed。失败的调用带有 http_status 和 error_code,它们的含义见错误。
  • reserved_usd 是调用开始时预留的金额。charge_usd 是它的实际费用,计价完成前为 0。
  • 最后一页的 next 为 null。

list_keys

Agent 的有效密钥,最早创建的在前。没有输入。密钥的完整内容永远不会显示。

{
  "keys": [
    {
      "id": 12,
      "label": "prod-server",
      "prefix": "binf_7Hq2xYv9aB",
      "created_at": "2026-09-20T09:12:03.000Z",
      "last_used_at": "2026-09-30T11:02:41.000Z",
      "month_usd": "24.8",
      "spending_limit": null,
      "this_key": true,
      "created_by_key_id": null
    }
  ],
  "max_active": 10
}
  • 对于当前连接使用的密钥,this_key 为 true。
  • created_by_key_id 是通过 MCP 创建它的密钥;在 API 密钥页面创建的密钥则为 null。
  • month_usd 是该密钥在本自然月(UTC)的花费。
  • spending_limit 的字段与 get_limits 中的相同,没有则为 null。

create_key

为 Agent 创建一个新密钥。需要使用没有消费上限的密钥。

输入类型含义
labelstring,必填用来辨认它的名称,一行,最多 60 个字符
spending_limitobject不传则创建没有上限的密钥
spending_limit.usdstring 或 number每个周期最多可以花费的金额,范围 0.01 到 1000000,比如 "5"
spending_limit.resetstringdaily、weekly 或 monthly。周期从 UTC 时间 00:00 开始,每周从周一开始
{
  "key": "binf_...",
  "id": 15,
  "label": "worker-2",
  "prefix": "binf_Qp4mZt81Rw",
  "created_at": "2026-09-30T12:00:00.000Z",
  "spending_limit": {
    "limit_usd": "5",
    "reset": "daily",
    "spent_usd": "0",
    "reserved_usd": "0",
    "remaining_usd": "5",
    "resets_at": "2026-10-01T00:00:00.000Z"
  }
}

key 只显示这一次,之后不会再显示。在做其他任何事情之前,先把它保存好。一个 Agent 最多可以有 10 个有效密钥,并且在任意 24 小时内最多通过 MCP 创建 20 个。新密钥会记录为由你当前连接使用的密钥创建。

update_key

重命名 Agent 的某个密钥,或者设置、修改或移除它的消费上限。需要使用没有消费上限的密钥。

输入类型含义
key_idinteger,必填密钥的 id,来自 list_keys
labelstring新名称
spending_limitobject 或 null新上限,格式同 create_key;传 null 则移除上限

传入 label、spending_limit 或两者都传。它返回的密钥与 list_keys 中显示的格式相同。在周期中途设置上限时,会计入该密钥在本周期内已经花掉的金额。

revoke_key

撤销 Agent 的某个密钥。需要使用没有消费上限的密钥。

输入类型含义
key_idinteger,必填密钥的 id,来自 list_keys
{ "key_id": 15, "revoked": true, "this_key": false }

密钥在下一次调用时就会停止工作;已经在运行的调用会继续完成。对同一个密钥撤销两次,返回的结果相同。如果 this_key 为 true,你正在使用的连接也会停止工作。

create_upload

获取一个上传单张图像的链接,让模型可以通过链接读取较大或本地的图像。任何密钥都可以使用,前提是该 Agent 有额度。

输入类型含义
content_typestring,必填image/png、image/jpeg、image/webp 或 image/gif
sizeinteger,必填图像的精确大小,以字节计,最大 20 MB(20,971,520)

它返回的内容与 POST /uploads 相同:

{
  "object": "upload",
  "id": "upl_BTSNzIeW9d7D_ShZQ8fJEQ",
  "upload_url": "https://...r2.cloudflarestorage.com/binference-images/uploads/42/BTSNzIeW9d7D_ShZQ8fJEQ.png?X-Amz-...",
  "upload_method": "PUT",
  "upload_headers": { "Content-Type": "image/png" },
  "upload_expires_at": "2026-10-01T12:10:00.000Z",
  "url": "https://...r2.cloudflarestorage.com/binference-images/uploads/42/BTSNzIeW9d7D_ShZQ8fJEQ.png?X-Amz-...",
  "expires_at": "2026-10-02T12:00:00.000Z",
  "content_type": "image/png",
  "size": 3400000
}

在 upload_expires_at 之前,用 PUT 把图像的字节连同 upload_headers 发送到 upload_url,然后在 expires_at 之前,在任意模型调用中把 url 作为图像发送。PUT 必须正好携带 size 个字节,且类型一致,否则存储会拒绝。一个 Agent 在任意 24 小时内最多可以发起 200 次上传。

create_video

发起一个视频,与 POST /videos 相同。任何密钥都可以使用,前提是该 Agent 有额度。它会立即返回任务;用 get_video 读取。

输入类型含义
modelstring,必填GET /videos/models 中的模型
promptstring,必填视频中发生什么,最多 2,000 个字符
durationinteger,必填秒数,必须是模型列出的值
resolutionstring,必填模型列出的值,例如 720p
aspect_ratiostring,必填模型列出的值,例如 16:9
generate_audioboolean声音,在模型支持时
seedinteger同样的种子和设置会生成相似的视频
first_frame_urlstring视频开始时的图片
last_frame_urlstring视频结束时的图片,在模型支持时
reference_urlsstring[]最多 3 张要保留的人物、物品或风格的图片
previous_video_idstring要继续延长的、此 Agent 已完成的视频
idempotency_keystring8 到 64 个字符:同一个键不会生成第二个视频

它返回任务:id、status、estimated_cost(最高花费),以及 POST /videos 返回的其他字段。

get_video

按 id 读取视频:先是 pending 或 in_progress,然后是 completed 或 failed。已完成的视频带有 download_url,一个有效期一小时的文件链接。失败的视频带有 error.code,从不扣费。每隔约 10 秒读取一次。

list_routes

这个密钥能调用的 bRoute:先是密钥主人自己的,然后是任何人都能调用的预设 bRoute。没有输入。

{
  "routes": [
    {
      "model": "broute/coding",
      "name": "Coding",
      "starter": true,
      "version": 1,
      "compare_model": "anthropic/claude-sonnet-5.5",
      "lanes": [
        {
          "lane": 1,
          "description": "Hard coding work: designing a system or API, changes across many files",
          "models": ["anthropic/claude-sonnet-5.5", "openai/gpt-6.1-sol"]
        },
        { "lane": 3, "description": "Anything else", "models": ["openai/gpt-6-luna"] }
      ]
    }
  ]
}
  • model 是调用它时用的名字,适用于 API 的任何格式。
  • models 先是通道的模型,然后是它的备用模型。最后一个通道是“其他”。

get_route_usage

密钥主人自己的一个 bRoute 在最近 7 天或 30 天内的情况:完成结算的调用、它们的扣费,以及与对比模型相比节省了多少。

输入类型说明
modelstringbRoute 的模型名,例如 broute/my-coder
daysinteger7(默认)或 30
{
  "model": "broute/my-coder",
  "days": 7,
  "calls": 1520,
  "spent_usd": "4.21",
  "saved_usd": "11.36",
  "baseline_usd": "15.57",
  "lanes": [
    { "lane": 1, "calls": 210, "spent_usd": "3.9", "saved_usd": "0" },
    { "lane": 2, "calls": 1310, "spent_usd": "0.31", "saved_usd": "11.36" }
  ]
}
  • baseline_usd 是同样的调用用对比模型要花的钱;saved_usd 是它减去实际扣费。某个通道花得更多时,它会低于零。
  • 不是密钥主人自己的 bRoute(包括预设 bRoute)会被拒绝:list_routes 会列出一个密钥能调用的 bRoute。

本页目录