API 参考

工具端点

所有 /v1/tools 端点、工具对象和运行对象的参考。

工具 API 用于列出、搜索和运行数据工具。请求和响应均为 JSON。Base URL 为 https://lovelyrouter.com/v1。

身份验证。 目录端点（列出、获取、搜索和规划）是公开的。运行工具和读取运行需要在 Authorization: Bearer 请求头中提供 API 密钥。工具运行与模型从同一个预付费余额中扣费。

错误。 失败的请求会返回一个包含 type 和 message 的 error 对象。参见错误。

语言。 目录端点接受 lang（zh 或 ja），用于本地化工具名称和描述：GET 请求中作为查询参数，POST 请求中作为请求体字段。

cURL

curl https://lovelyrouter.com/v1/tools/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY"

工具对象#

目录中的一个工具。列出和搜索端点返回摘要字段。获取工具还会额外返回输入结构、示例输入、时间限制和一个现成的运行请求。

属性

idstring

工具 id，用于运行路径中。例如 google-maps-places。

namestring

显示名称，随 lang 本地化。

platformstring

工具读取的网站或数据源，例如 Google Maps 或 TikTok。

categorystring

取值为 social-media、search、ecommerce、lead-generation、reviews、jobs、travel、web 之一。

descriptionstring

工具返回的内容，随 lang 本地化。

priceobject

实时价格。

default_resultsinteger

未设置 max_results 时，运行使用的结果上限。

max_resultsinteger

该工具单次运行可接受的最高结果上限。

featuredboolean

该工具是否在工具页面上作为热门工具突出显示。

input_schemaobject

运行 input 的 JSON Schema。仅在获取单个工具时返回。

example_inputobject

可直接使用的输入。仅在获取单个工具时返回。

timeout_sinteger

运行的时间限制，单位为秒。超时的运行以 timed_out 结束。仅在获取单个工具时返回。

runobject

现成的运行请求：method、path，以及包含示例输入和默认上限的 body。仅在获取单个工具时返回。

The tool object

{
  "id": "google-maps-places",
  "name": "Search Google Maps places",
  "platform": "Google Maps",
  "category": "search",
  "description": "Find local businesses on Google Maps by keyword and location: name, address, phone, website, rating, review count, opening hours, coordinates.",
  "price": {
    "per_call_usd": 0.00075,
    "per_result_usd": 0.000238,
    "unit": "place",
    "label": "$0.000238 / place + $0.00075 / call"
  },
  "default_results": 10,
  "max_results": 200,
  "featured": true
}

列出工具#

GET/v1/tools

返回所有可用工具。无需密钥。

查询参数

categorystring

只返回该分类下的工具，例如 reviews。

qstring

关键词。返回按相关度排序的匹配工具，最多 100 个。

langstring默认 en

传 zh 或 ja 以本地化名称和描述。

返回一个列表对象，工具位于 data 中。

Shell

curl "https://lovelyrouter.com/v1/tools?category=reviews"

Response

{
  "object": "list",
  "data": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": {
        "per_call_usd": 0,
        "per_result_usd": 0.000675,
        "unit": "review",
        "label": "$0.000675 / review"
      },
      "default_results": 20,
      "max_results": 500,
      "featured": false
    }
  ]
}

获取工具#

GET/v1/tools/{id}

返回单个工具，包含其 input_schema、example_input、timeout_s 和一个现成的 run 请求。无需密钥。id 不存在时返回 404。

路径参数

idstring必填

工具 id。

查询参数

langstring默认 en

传 zh 或 ja 以本地化名称和描述。输入结构保持英文。

cURL

curl https://lovelyrouter.com/v1/tools/trustpilot-reviews

Response

{
  "id": "trustpilot-reviews",
  "name": "Trustpilot reviews",
  "platform": "Trustpilot",
  "category": "reviews",
  "description": "Trustpilot reviews of a company by domain: stars, text, date, reply.",
  "price": {
    "per_call_usd": 0.0075,
    "per_result_usd": 0.0015,
    "unit": "review",
    "label": "$0.0015 / review + $0.0075 / call"
  },
  "default_results": 20,
  "max_results": 500,
  "featured": false,
  "input_schema": {
    "type": "object",
    "properties": {
      "companyUrls": {
        "type": "array",
        "title": "Company URLs or Domains",
        "description": "Enter Trustpilot company URLs (e.g., https://www.trustpilot.com/review/example.com) or just the domain (e.g., example.com). One per line."
      },
      "maxReviewsPerCompany": {
        "type": "integer",
        "title": "Max reviews per company (reviews)",
        "default": 0,
        "minimum": 0
      }
    },
    "required": ["companyUrls"]
  },
  "example_input": {
    "companyUrls": ["pipedrive.com"],
    "maxReviewsPerCompany": 20
  },
  "timeout_s": 300,
  "run": {
    "method": "POST",
    "path": "/v1/tools/trustpilot-reviews/run",
    "body": {
      "input": { "companyUrls": ["pipedrive.com"], "maxReviewsPerCompany": 20 },
      "max_results": 20
    }
  }
}

搜索工具#

POST/v1/tools/discover

在目录中按关键词搜索。返回最佳匹配项，每项带有相关度 score。无需密钥。

请求体参数

querystring必填

用几个词描述你的需求，例如 tiktok comments。只使用前 1,000 个字符。

limitinteger默认 5

结果数量，1 到 40。

langstring默认 en

传 zh 或 ja 以本地化名称和描述。

返回 query、count 和 results：带有 score 的工具对象。分数只在同一次查询内可比。请求体缺少 query 时返回 400。

cURL

curl https://lovelyrouter.com/v1/tools/discover \
  -H "content-type: application/json" \
  -d '{"query": "google maps reviews", "limit": 2}'

Response

{
  "query": "google maps reviews",
  "count": 2,
  "results": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "default_results": 20,
      "max_results": 500,
      "featured": false,
      "score": 0.889
    },
    {
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "description": "Find local businesses on Google Maps by keyword and location: name, address, phone, website, rating, review count, opening hours, coordinates.",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "default_results": 10,
      "max_results": 200,
      "featured": true,
      "score": 0.717
    }
  ]
}

规划任务#

POST/v1/tools/suggest

用平实的语言描述任务，即可获得一份有序方案：首先运行的工具、可选的第二个工具以及相近的替代工具，每项都附有示例输入和预估费用。免费，每个 API 密钥限流为每分钟 100 次请求。不带密钥的调用方共享同一个每分钟 100 次的额度。超出限制时，端点返回 429 并附带 retry-after 响应头。

请求体参数

taskstring必填

任务描述，最多 2,000 个字符。超长时返回 413。

limitinteger默认 5

最多返回的建议数，1 到 8。

langstring默认 en

传 zh 或 ja 以本地化名称和描述。

返回值

taskstring

你发送的任务。

sourcestring

ai 表示由规划器生成的方案，keyword 表示规划器不可用时的关键词匹配结果。

cachedboolean

方案是否来自相同任务的缓存（缓存保留一天）。

countinteger

建议数量。没有适合该任务的工具时为 0。

suggestionsarray

按顺序排列的方案。每一项都是一个工具对象，外加以下字段：

total_est_cost_usdnumber

primary 和 next 步骤的费用之和，不含替代项。

cURL

curl https://lovelyrouter.com/v1/tools/suggest \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"task": "Find vegan restaurants in Austin and summarize what their reviews complain about"}'

Response

{
  "task": "Find vegan restaurants in Austin and summarize what their reviews complain about",
  "source": "ai",
  "cached": false,
  "count": 2,
  "suggestions": [
    {
      "step": 1,
      "role": "primary",
      "match": 0.961,
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "input": {
        "searchTerms": ["coffee shop"],
        "location": "Austin, Texas, USA",
        "maxResults": 3,
        "language": "en"
      },
      "input_required": [],
      "max_results": 10,
      "est_cost_usd": 0.00313,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-places/run",
        "body": { "input": { "searchTerms": ["coffee shop"], "location": "Austin, Texas, USA", "maxResults": 3, "language": "en" }, "max_results": 10 }
      }
    },
    {
      "step": 2,
      "role": "next",
      "match": 0.875,
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" },
      "input_required": [],
      "max_results": 20,
      "est_cost_usd": 0.0135,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-reviews/run",
        "body": { "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" }, "max_results": 20 }
      }
    }
  ],
  "total_est_cost_usd": 0.01663
}

运行对象#

工具的一次运行。由运行、获取、停止和列出端点返回。

属性

idstring

运行 id：run_ 后跟 24 个字符。

objectstring

始终为 tool_run。

toolstring

工具 id。

tool_namestring

工具的显示名称。

statusstring

running、succeeded、failed、timed_out（达到工具的时间限制）或 stopped（被你停止）。

inputobject or null

本次运行实际使用的输入：工具旧版本的字段名已映射为当前字段名，工具的数量字段已按结果上限填入（对按每次搜索计数的工具，上限会平分到各个搜索）。可用它把运行和你的查询对应起来，例如连接中断之后。2026 年 10 月 20 日之前的部分运行为 null。

resultsinteger

已返回并计费的结果数。运行结束前为 0。

max_resultsinteger

本次运行适用的结果上限。它可能与你请求的值不同：会被降到工具的最大值，或提高到工具的最小运行规模。

charge_usdnumber or null

本次运行的费用。结算前为 null。

reserved_usdnumber

运行未结算期间从你的余额中预留的金额。结算后为 0。

errorstring or null

运行提前结束的原因。状态为 running 和 succeeded 的运行为 null。

created_atstring

运行开始的时间，ISO 8601 格式。

finished_atstring or null

运行结束的时间，ISO 8601 格式。运行中为 null。

pollstring

用于轮询结果的路径。仅出现在 202 响应中。

itemsarray or null

结果，采用工具自身的格式。仅在运行结束后返回，列出端点中不包含。结果暂时不可用时为 null，参见 items_error。

offsetinteger

items 中第一条结果的索引。仅在运行有结果时出现。

next_offsetinteger or null

下一页结果的偏移量；最后一页为 null。

items_errorstring

仅在 items 为 null 时出现。再次请求该运行即可加载结果。

reportobject

部分工具在 items 之外返回的整次运行信息。网站引荐工具（site-referrals、site-outgoing）：查询的 site、period、列表中的网站数 sites、unattributed（未归属到任何网站的引荐访问，或 null），以及 site-referrals 的 monthly：该站每月的引荐访问总量，例如 [{"month": "2026-04", "visits": 55133}]（site-outgoing 为 null）。它们的每条结果也带 monthly：该网站每月的访问量；没有月度数据时为 null。

The run object

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "succeeded",
  "input": {
    "searchTerms": ["coffee shop"],
    "location": "Austin, Texas, USA",
    "maxResults": 20,
    "language": "en",
    "radius": 20
  },
  "results": 20,
  "max_results": 20,
  "charge_usd": 0.00551,
  "reserved_usd": 0,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:38.917Z",
  "items": [
    {
      "title": "Godsent Coffee",
      "categoryName": "Coffee shop",
      "address": "9817 Anderson Mill Rd, Austin, TX 78750",
      "totalScore": 5,
      "reviewsCount": 237,
      "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE"
    }
  ],
  "offset": 0,
  "next_offset": null
}

运行工具#

POST/v1/tools/{id}/run

启动一次运行，并最多等待 wait 秒。运行的最高费用（每次调用费加上每条结果费乘以上限）会从你的余额中预留，并在运行结束时结算。需要 API 密钥。

返回 200 时附带已结束的运行对象及其 items；返回 202 时附带仍在运行的运行对象和一个 poll 路径。200 中的运行也可能是 failed 或 timed_out，请检查 status。任何错误状态码都表示运行未启动，也未产生任何费用。

也可以在请求体中传入工具 id：向 POST /v1/tools/run 发送 "tool": "google-maps-places"。

运行 browser-agent 则会返回 202 和一个浏览器运行，max_results 用作最大步数。参见浏览器智能体。

路径参数

idstring必填

工具 id。

请求体参数

inputobject默认 {}

工具的输入，需符合其 input_schema。input_schema.required 中的字段必须设置。序列化为 JSON 后最多 50,000 个字符。

max_resultsinteger

最多返回并计费的结果数，不超过工具的 max_results。默认为工具的 default_results；对于接收条目列表、每个条目返回一条结果的工具，默认为列表长度。

waitinteger默认 60

等待运行结束的秒数，0 到 300。也可以通过 ?wait= 查询参数传入。

Shell

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
  }'

Response (202)

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "running",
  "results": 0,
  "max_results": 20,
  "charge_usd": null,
  "reserved_usd": 0.00551,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": null,
  "poll": "/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60"
}

获取运行#

GET/v1/tools/runs/{run_id}

返回一次运行，可选择等待其结束。轮询一个已结束但尚未结算的运行会触发结算。运行进行中时返回 202，结束后返回 200，结果位于 items 中。属于其他账户的运行返回 404。

对于 browser-agent 运行，此端点返回浏览器运行。参见浏览器智能体。

路径参数

run_idstring必填

运行 id。

查询参数

waitinteger默认 0

等待运行中的运行结束的秒数，0 到 300。

offsetinteger默认 0

返回的第一条结果的索引。

limitinteger

返回的结果数，从 1 到该运行的 max_results，默认值也是 max_results。

cURL

curl "https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60&offset=0&limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "succeeded",
  "results": 20,
  "max_results": 20,
  "charge_usd": 0.00551,
  "reserved_usd": 0,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:38.917Z",
  "items": [
    { "title": "Godsent Coffee", "totalScore": 5, "reviewsCount": 237, "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE" }
  ],
  "offset": 0,
  "next_offset": null
}

停止运行#

POST/v1/tools/runs/{run_id}/stop

停止一个正在进行的运行。它以 stopped 结束，你只需为停止前已返回的结果支付每条结果费，不收每次调用费。返回已结算的运行及这些结果；如果约 10 秒后仍在收尾，则返回 202。停止一个已结束的运行会原样返回它。

路径参数

run_idstring必填

运行 id。

cURL

curl -X POST https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d/stop \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "stopped",
  "results": 4,
  "max_results": 20,
  "charge_usd": 0.018,
  "reserved_usd": 0,
  "error": "The run was stopped. You are billed only for results delivered before it stopped.",
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:19.630Z",
  "items": [
    { "title": "Godsent Coffee", "totalScore": 5, "reviewsCount": 237, "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE" }
  ],
  "offset": 0,
  "next_offset": null
}

列出运行#

GET/v1/tools/runs

返回你账户下的运行，最新的在前，不含结果条目。包括用你任意一个密钥启动的运行。

查询参数

limitinteger默认 20

运行数量，1 到 100。

beforeinteger

游标：上一页返回的 next 值。

返回一个列表对象，运行对象位于 data 中；next 是下一页的游标，没有更多运行时为 null。

cURL

curl "https://lovelyrouter.com/v1/tools/runs?limit=2" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
      "object": "tool_run",
      "tool": "google-maps-places",
      "tool_name": "Search Google Maps places",
      "status": "succeeded",
      "results": 20,
      "max_results": 20,
      "charge_usd": 0.00551,
      "reserved_usd": 0,
      "error": null,
      "created_at": "2026-10-11T15:02:11.204Z",
      "finished_at": "2026-10-11T15:02:38.917Z"
    },
    {
      "id": "run_51d0b9e4c3a2f1e0d9c8b7a6",
      "object": "tool_run",
      "tool": "trustpilot-reviews",
      "tool_name": "Trustpilot reviews",
      "status": "succeeded",
      "results": 20,
      "max_results": 20,
      "charge_usd": 0.0375,
      "reserved_usd": 0,
      "error": null,
      "created_at": "2026-10-11T14:48:03.512Z",
      "finished_at": "2026-10-11T14:48:21.077Z"
    }
  ],
  "next": 1791730083512
}

错误#

所有错误的结构都相同。type 是稳定的，可以放心用于分支判断。message 供人阅读，可能会变化。

状态码	`type`	原因
`400`	`invalid_request_error`	请求体不是 JSON、`input` 不是对象、缺少必填的输入字段、工具拒绝了输入，或缺少 `query` / `task`
`401`	`authentication_error`	API 密钥缺失、无效、已吊销或已过期
`402`	`insufficient_quota`	余额或密钥的消费上限不足以覆盖运行的预留金额
`404`	`not_found`	工具 id 不存在，或你的账户下没有该 id 的运行
`413`	`invalid_request_error`	`input` 超过 50,000 个字符，或 `task` 超过 2,000 个字符
`429`	`rate_limit_exceeded`	你的账户已有 10 个运行在进行中，或触发了规划器的限流
`500`	`api_error`	意外错误。请重试。
`502`	`tool_unavailable`	工具无法启动，不会收费。请稍后重试。

返回错误的运行请求不会收费。整个 API 的错误说明见错误。

Error

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required input: companyUrls. See GET /v1/tools/trustpilot-reviews."
  }
}