数据工具

数据工具从网络返回结构化数据：Google 地图地点、TikTok 评论、LinkedIn 个人资料、Amazon 评论、招聘职位，以及转成 Markdown 的任意网页。你找到一个工具，发送 JSON 输入，就能拿回 JSON 结果。每次运行都从你的预付费余额中扣费：一笔每次调用费加上每条结果费，绝不会超过你设定的上限。

无需单独注册账户，也无需订阅。调用模型的 API 密钥同样可以调用工具，工具消费也计入同一个余额和密钥消费上限。

试一试#

目录是公开的，无需密钥即可列出：

curl https://lovelyrouter.com/v1/tools

运行工具需要密钥。下面这次运行最多查找奥斯汀的 20 家咖啡店，费用最多 $0.00551：

curl https://lovelyrouter.com/v1/tools/google-maps-places/run \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "input": {"searchTerms": ["coffee shop"], "location": "Austin, Texas, USA"},
    "max_results": 20
  }'

响应中包含运行状态、费用，以及 items 中的结果。长时间运行、轮询和分页请参阅运行工具。

目录里有什么#

每个工具都属于一个分类。用 GET /v1/tools?category=reviews 按分类 id 筛选，或在工具页面浏览。

工具会陆续增加。GET /v1/tools 和工具页面始终显示最新列表。

计费方式#

每个工具有两项价格，任意一项都可以为零：

• 每次调用费：运行成功时收取一次。
• 每条结果费：按运行返回的每条结果收取。单位取决于工具：一个地点、一条评论、一个页面、一份资料。

一次运行的费用为：

per-call fee + per-result fee × results returned

按当前价格举几个例子：

价格可能变动。工具页面和 GET /v1/tools 会在每个工具的 price 对象中给出实时价格。

用 max_results 限制费用#

每次运行都有一个结果上限 max_results。运行返回和计费的结果数永远不会超过这个上限。不填时使用工具的 default_results，你也可以调高它，最多到该工具自身的 max_results。

因此，一次运行最多花多少钱在开始前就已确定：per-call fee + per-result fee × max_results。

先预留，后结算#

1. 预留。 运行开始时，会从你的余额中预留它的最高费用。如果余额或密钥的消费上限不够支付，运行会被拒绝并返回 402，不产生任何扣费。请调低 max_results 或充值。
2. 结算。 运行结束时，按实际返回的结果扣费，预留的剩余部分退回你的余额。

一次上限为 20 个地点的 Google 地图搜索会预留 $0.00551。如果返回了 14 个地点，你支付 $0.004082，其余 $0.001428 退回余额。

失败与停止的运行#

没有返回任何结果的失败运行不收费。每次运行及其扣费都会显示在控制台的工具页面中。

一次运行的生命周期#

1. 1

   找到工具

   列出或搜索目录，或者把任务描述给规划服务。参阅找到合适的工具。

2. 2

   读取输入结构

   GET /v1/tools/{id} 返回工具的 input_schema、一个 example_input 及其价格。

3. 3

   启动运行

   带上你的 input 和 max_results 上限调用 POST /v1/tools/{id}/run。最高费用会从你的余额中预留。

4. 4

   等待或轮询

   请求默认最多等待 60 秒。在这段时间内完成的运行会返回 200 及其结果。耗时更长的运行返回 202，你需要轮询 GET /v1/tools/runs/{run_id}，直到它完成。

5. 5

   结算并读取结果

   完成的运行会报告 results、charge_usd，数据在 items 中。无人轮询的运行会在几分钟内自动结算，因此预留永远不会被一直占用。

浏览器智能体#

浏览器智能体也在同一目录中，id 为 browser-agent。给它一个目标和一个起始网址，它就会在真实浏览器中完成任务。它按步计费，而不是按结果计费：max_results 设定最大步数。完整 API（包括登录、结构化输出和人工批准）请参阅浏览器智能体。

限制#

超出并发上限的运行会被拒绝并返回 429。等其他运行结束后再重新启动。

后续步骤#