工具 API 参考

基础地址 https://tokentosea.com/api/v1/tool-api。所有接口都需要 Authorization: Bearer <工具密钥或全能密钥>，见鉴权。调用流程与计费规则见工具 API 概览。

搜索工具目录#

GET /catalog

查询参数	类型	说明
`q`	string	关键词，最多 160 个字符，匹配名称、服务商、简介、接口路径与别名；多个词之间为「且」
`connected`	`1`	只返回已接通、可通过 `/invoke` 调用的工具
`category`	string	分类：`search`、`web`、`automation`、`development`、`communication`、`data`、`media`、`social`、`seo`、`news`、`ai`、`business`、`commerce`、`travel`、`property`、`auto`、`weather`、`finance`、`blockchain`、`legal`、`other`
`featured`	`1`	只返回精选工具
`saved`	`1`	只返回当前账号收藏的工具
`offset`	integer	分页偏移，0–100000，默认 0；每页 24 条

GET /catalog?connected=1（节选）

{
  "items": [
    {
      "id": "public_github",
      "name": "GitHub",
      "provider": "GitHub",
      "summary": "公开仓库、发布版本、议题和开发者资料",
      "category": "development",
      "protocol": "REST",
      "pricing": "usage",
      "callableCount": 6,
      "endpointCount": 6,
      "docsUrl": "https://docs.github.com/en/rest",
      "status": "approved",
      "source": "curated",
      "saved": false
    }
  ],
  "total": 12,
  "offset": 0,
  "categories": [{ "id": "development", "count": 5 }],
  "stats": { "tools": 12, "providers": 12, "endpoints": 45 }
}

目录也收录了尚未接通的工具（callableCount 为 0），它们只提供资料，不能调用。

字段	说明
`id`	工具 ID，用于 `/actions/{toolId}`
`name` / `provider` / `summary` / `description`	名称、服务商与说明
`category` / `protocol` / `pricing`	分类；接入方式（`REST`、`MCP`、`SDK`、`Web`）；服务商的收费方式（`free`、`usage`、`subscription`、`contact`）
`pricingNote`	收费说明
`callableCount`	已接通、可调用的操作数
`endpoints` / `endpointCount`	目录收录的接口（列表中最多返回 8 个）与总数；这是资料，不等于可调用的操作
`websiteUrl` / `docsUrl` / `iconPath`	官网、文档与图标
`featuredRank` / `saved`	精选排序；当前账号是否收藏
`status` / `source`	审核状态；`curated`（平台收录）或 `seller`（卖家提交）

列出操作#

GET /actions/{toolId}

返回工具的全部操作（操作对象数组）。只有 enabled 为 true 的操作可以调用。工具不存在时返回 404 tool_not_found。

响应（节选）

[
  {
    "id": "github.search",
    "toolId": "public_github",
    "name": "搜索公开仓库",
    "description": "搜索公开仓库，返回结构化结果与来源。",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "搜索关键词", "maxLength": 200 },
        "limit": { "type": "integer", "description": "返回条数（1–10）", "minimum": 1, "maximum": 10 }
      },
      "required": ["query"],
      "additionalProperties": false
    },
    "exampleInput": { "query": "typescript", "limit": 3 },
    "priceUsd": "0.001000",
    "priceVersion": "public-20261010-v1",
    "enabled": true,
    "sourceUrl": "https://docs.github.com/en/rest"
  }
]

查询余额#

GET /wallet

响应

{ "balanceUsd": "12.500000", "reservedUsd": "0.003000", "availableUsd": "12.497000", "currency": "USD" }

字段	说明
`balanceUsd`	账户余额（美元，6 位小数）
`reservedUsd`	进行中的模型与工具调用已预留的金额
`availableUsd`	可用余额 = 余额 − 预留

余额是账号级的，与模型调用共用。

调用操作#

POST /invoke

参数	类型	必填	说明
`actionId`	string	必填	操作 ID，例如 `github.search`
`input`	object	必填	输入，必须符合操作的 `inputSchema`；规范化后最大 16 KiB
`requestKey`	string	必填	16–128 个字符，账号内唯一，用于幂等
`priceVersion`	string	必填	从 `/actions` 读取的价格版本
`maxCostUsd`	string	必填	你愿意为本次调用支付的上限，美元十进制字符串，最多 6 位小数（例如 `"0.001000"`），不能小于操作的 `priceUsd`

请求体不能包含其他字段，否则返回 400 tool_invalid_request。

输入校验规则：必填字段必须出现；不能有 inputSchema 之外的字段；string 不超过 maxLength（未声明时 200）；integer 为安全整数；数值在 minimum 与 maximum 之间；声明了 enum 时只能取其中的值。

成功受理时返回 201 与调用对象。HTTP 201 不代表调用成功：外部数据源出错时同样返回 201，status 为 failed 且 chargedUsd 为 "0.000000"。

响应示例

{
  "id": "cm2…",
  "actionId": "github.search",
  "actionName": "搜索公开仓库",
  "toolName": "GitHub",
  "requestKey": "6f0d6c1e-…",
  "status": "succeeded",
  "priceUsd": "0.001000",
  "chargedUsd": "0.001000",
  "input": { "query": "typescript", "limit": 3 },
  "output": {
    "data": { "total_count": 1234, "items": ["…"] },
    "source": { "url": "https://api.github.com/search/repositories?q=typescript&per_page=3", "retrievedAt": "2026-10-21T08:00:00.000Z", "operation": "github.search" }
  },
  "errorCode": null,
  "createdAt": "2026-10-21T08:00:00.000Z",
  "completedAt": "2026-10-21T08:00:01.000Z"
}

调用记录#

GET /runs?offset={offset}

按创建时间倒序返回当前账号的调用记录，每页 20 条，offset 为 0–100000。列表中的 output 为 null，完整结果用 /runs/{id} 获取。

响应

{ "items": [{ "id": "cm2…", "status": "succeeded", "output": null, "…": "…" }], "total": 57, "offset": 0 }

单次调用#

GET /runs/{id}

返回包含 output 的完整调用对象。记录不存在或不属于当前账号时返回 404 tool_run_not_found。

对象#

操作对象#

字段	类型	说明
`id`	string	操作 ID，调用时作为 `actionId`
`toolId`	string	所属工具
`name` / `description`	string	名称与说明
`inputSchema`	object	输入结构：`{ type: "object", properties, required, additionalProperties: false }`。每个属性有 `type`（`string`、`number`、`integer`、`boolean`）与 `description`，可选 `maxLength`、`minimum`、`maximum`、`enum`
`exampleInput`	object	一个有效的输入示例
`priceUsd`	string	单次成功调用的价格（美元，6 位小数）
`priceVersion`	string	价格版本，调用时原样传回
`enabled`	boolean	是否可调用
`sourceUrl`	string	外部数据源的官方文档

调用对象#

字段	类型	说明
`id`	string	调用 ID
`actionId` / `actionName` / `toolName`	string	操作与工具
`requestKey`	string	你提供的幂等键
`status`	string	`running`、`succeeded`、`failed`
`priceUsd`	string	调用时的价格
`chargedUsd`	string	实际扣费；失败为 `"0.000000"`
`input`	object	校验后的输入
`output`	object \| null	成功时为 `{ data, source }`：`data` 是外部数据源返回的数据，`source` 记录请求地址、获取时间与操作
`errorCode`	string \| null	失败原因，见错误码
`createdAt` / `completedAt`	string	ISO 8601 时间

外部数据按来源原样返回，不代表 TokenToSea 对其内容的背书；汇率等参考数据以来源公布为准。

错误码#

HTTP 错误的响应体为 { "statusCode", "message", "error" }，message 为下表中的错误码。

状态码	`message`	原因与处理
`400`	`tool_invalid_request`	请求体不是对象，或包含未定义的字段
`400`	`tool_invalid_actionId`、`tool_invalid_requestKey`、`tool_invalid_priceVersion`	字段缺失或长度不符（`requestKey` 16–128）
`400`	`tool_invalid_amount`	`maxCostUsd` 不是合法的十进制字符串
`400`	`tool_input_too_large`	输入超过 16 KiB
`400`	`tool_missing_input`、`tool_unknown_input`、`tool_invalid_input_<字段>`	输入不符合 `inputSchema`
`400`	`tool_operation_unavailable`	输入格式不被该操作接受（例如 GitHub 仓库名不是 `owner/repo`）
`400`	`tool_invalid_query`、`tool_invalid_category`、`tool_invalid_connected_filter`、`tool_invalid_featured_filter`、`tool_invalid_saved_filter`、`tool_invalid_offset`	目录或列表的查询参数不合法
`401`	`tool_key_required`	缺少 `Authorization: Bearer`，或密钥格式不对
`401`	`tool_key_invalid`	密钥不存在、已撤销、已删除或已过期，或账号不可用
`403`	`tool_access_not_allowed`	`sk-relay_…` 密钥没有工具权限
`403`	`tool_key_budget_exceeded`	全能密钥在当前周期内的费用或 token 限额已用尽（模型调用与工具调用共用这把密钥的限额）
`404`	`tool_not_found`、`tool_run_not_found`	工具或调用记录不存在
`409`	`tool_not_connected`	操作未接通或已停用
`409`	`tool_price_changed`	`priceVersion` 已过期，或 `priceUsd` 高于 `maxCostUsd`。重新读取 `/actions`
`409`	`tool_request_key_reused`	同一个 `requestKey` 用于了不同的请求
`409`	`tool_rate_limited`	超过并发或频率限制，稍后重试
`409`	`tool_insufficient_balance`	可用余额不足

调用失败时（HTTP 201，status: "failed"）的 errorCode：

`errorCode`	含义
`tool_provider_failed`	外部数据源返回错误
`tool_provider_rate_limited`	外部数据源限流（HTTP 429）
`tool_empty_response`、`tool_no_result`	外部数据源没有返回数据
`tool_result_too_large`	外部响应超过 1.5 MB
`tool_invalid_base64`	`utility.base64decode` 的输入不是合法 Base64
`tool_execution_failed`	执行失败（包括 12 秒超时、响应不是 JSON）
`tool_interrupted`	调用超过 2 分钟未完成，已标记失败

失败的调用不扣费；同一个 requestKey 重试会返回同一条失败记录，修正后请使用新的 requestKey。

当前可调用的操作#

截至 2026-10-21 已接通 12 个工具、45 个操作，价格版本均为 public-20261010-v1。以 GET /catalog?connected=1 与 GET /actions/{toolId} 的实时返回为准。? 表示可选输入；limit 均为 1–10。

工具	操作 ID	名称	输入	价格
GitHub (`public_github`)	`github.search`	搜索公开仓库	`query`、`limit`?	USD 0.001
GitHub (`public_github`)	`github.repository`	仓库资料	`repository`	USD 0.001
GitHub (`public_github`)	`github.issues`	公开议题	`repository`、`limit`?	USD 0.001
GitHub (`public_github`)	`github.releases`	发布版本	`repository`、`limit`?	USD 0.001
GitHub (`public_github`)	`github.commits`	最近提交	`repository`、`limit`?	USD 0.001
GitHub (`public_github`)	`github.user`	公开开发者资料	`username`	USD 0.001
npm (`public_npm`)	`npm.search`	搜索 npm 包	`query`、`limit`?	USD 0.001
npm (`public_npm`)	`npm.package`	npm 包元数据	`package`	USD 0.001
npm (`public_npm`)	`npm.downloads`	每周下载统计	`package`	USD 0.001
PyPI (`public_pypi`)	`pypi.package`	Python 包元数据	`package`	USD 0.001
PyPI (`public_pypi`)	`pypi.version`	Python 指定版本	`package`、`version`	USD 0.001
crates.io (`public_crates`)	`crates.search`	搜索 Rust crate	`query`、`limit`?	USD 0.001
crates.io (`public_crates`)	`crates.package`	Rust crate 元数据	`package`、`limit`?	USD 0.001
crates.io (`public_crates`)	`crates.versions`	Rust crate 版本	`package`、`limit`?	USD 0.001
Crossref (`public_crossref`)	`crossref.search`	检索论文元数据	`query`、`limit`?	USD 0.001
Crossref (`public_crossref`)	`crossref.doi`	解析 DOI	`doi`	USD 0.001
Crossref (`public_crossref`)	`crossref.journals`	检索期刊	`query`、`limit`?	USD 0.001
DataCite (`public_datacite`)	`datacite.search`	检索研究数据	`query`、`limit`?	USD 0.001
DataCite (`public_datacite`)	`datacite.doi`	解析数据 DOI	`doi`	USD 0.001
Europe PMC (`public_europepmc`)	`europepmc.search`	检索生命科学文献	`query`、`limit`?	USD 0.001
Europe PMC (`public_europepmc`)	`europepmc.article`	查询 PubMed 文章	`id`	USD 0.001
Europe PMC (`public_europepmc`)	`europepmc.citations`	查询文章引用	`id`、`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.top`	热门技术新闻	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.new`	最新技术新闻	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.best`	精选技术新闻	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.ask`	社区问答	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.show`	社区作品	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.jobs`	招聘信息	`limit`?	USD 0.001
Hacker News (`public_hn`)	`hn.item`	新闻或评论详情	`id`	USD 0.001
Hacker News (`public_hn`)	`hn.user`	社区用户资料	`username`	USD 0.001
World Bank (`public_worldbank`)	`worldbank.countries`	国家资料	`limit`?	USD 0.001
World Bank (`public_worldbank`)	`worldbank.indicators`	指标目录	`limit`?	USD 0.001
World Bank (`public_worldbank`)	`worldbank.series`	国家年度指标	`country`、`indicator`、`year`?、`limit`?	USD 0.001
USGS (`public_usgs`)	`usgs.recent`	最近一周显著地震	—	USD 0.001
USGS (`public_usgs`)	`usgs.search`	检索地震事件	`startDate`、`minMagnitude`?、`limit`?	USD 0.001
Frankfurter (`public_frankfurter`)	`frankfurter.currencies`	参考汇率币种	—	USD 0.001
Frankfurter (`public_frankfurter`)	`frankfurter.latest`	最新公布参考汇率	`base`?、`symbols`?	USD 0.001
Frankfurter (`public_frankfurter`)	`frankfurter.history`	历史参考汇率	`base`?、`symbols`?、`date`	USD 0.001
TokenToSea 数据工具 (`public_utility`)	`utility.json`	解析并格式化 JSON	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.sha256`	SHA-256 文本摘要	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.base64encode`	Base64 编码	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.base64decode`	Base64 解码	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.textstats`	文本统计	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.url`	解析 URL	`text`	免费
TokenToSea 数据工具 (`public_utility`)	`utility.uuid`	生成 UUID	—	免费

下一步#

工具 API 概览
委托接口：OAuth 应用代用户调用工具