联网搜索

这页能做什么

你可以搜索公开网页并取回结构化结果，或抓取指定 URL 的标题和正文。

前置条件

已有 LokoSpace API Key，请求头使用 Authorization: Bearer <你的 LokoSpace API Key>
账号积分足够支付本次调用
账号没有被搜索工具的限流规则拦截
搜索和抓取都不需要传 model，工具模型由服务端固定
请求体使用 Content-Type: application/json

可用模型

联网搜索没有 model 参数，也没有 /web/models 接口。网关固定使用两个工具模型：

工具模型	用途	计费模式
`loko-web-search`	网页搜索	`per_unit`
`loko-web-fetch`	网页抓取	`per_unit`

这两个 id 不写在请求体里，只用于说明计费和排查。能否调用以账号权限和服务端配置为准。

可用性检查用模型总表：

curl https://sheverai.com/8811c8/api/llm/v1/models \
  -H "Authorization: Bearer $LOKO_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "loko-web-search",
      "object": "model",
      "created": 0,
      "owned_by": "lokospace"
    }
  ]
}

字段	类型	说明
`object`	string	固定为 `list`
`data`	array	当前账号可用的模型
`data[].id`	string	模型 ID。出现 `loko-web-search` 或 `loko-web-fetch` 表示该工具可用
`data[].object`	string	固定为 `model`
`data[].created`	integer	固定为 0
`data[].owned_by`	string	固定为 `lokospace`

搜索接口

请求

curl https://sheverai.com/8811c8/api/llm/v1/web/search \
  -H "Authorization: Bearer $LOKO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-20261022-001" \
  -d '{
    "query": "LokoSpace API 文档",
    "count": 10,
    "need_content": false
  }'

字段	类型	必填	说明
`query`	string	是	搜索词，1 到 128 字符
`count`	integer	否	返回条数，1 到 50，默认 10
`limit`	integer	否	`count` 的别名。两者同时传时以 `count` 为准
`ori_question`	string	否	原始问题，最长 128 字符，超出会截断
`localization`	string	否	地域或语言偏好，最长 128 字符，超出会截断
`need_content`	boolean	否	是否要求返回正文内容，默认 `false`
`Idempotency-Key`	string	否	请求头。建议传。有结果时相同键重试返回缓存结果

count 不是整数时按 10 处理。小于 1 按 1，大于 50 按 50。

{
  "results": [
    {
      "url": "https://example.com/article",
      "title": "示例文章",
      "snippet": "摘要片段",
      "summary": "较长的内容摘要",
      "site_name": "Example",
      "authority": 0.8,
      "rerank_score": 0.92,
      "date": "2026-10-20"
    }
  ],
  "lokospace_billing": {
    "requestId": "<请求 ID>",
    "creditsUsed": "<本次扣除积分>",
    "balanceAfter": "<扣除后余额>"
  }
}

字段	类型	说明
`results`	array	搜索结果。没有结果时为空数组
`results[].url`	string \| null	页面地址。上游也可能用 `link` 字段
`results[].title`	string \| null	页面标题
`results[].snippet`	string \| null	摘要片段。上游也可能用 `description` 字段
`results[].summary`	string \| null	较长的内容摘要
`results[].site_name`	string \| null	站点名称
`results[].authority`	number \| string \| null	权威度评分或等级，具体口径由上游决定
`results[].rerank_score`	number \| null	重排分数
`results[].date`	string \| null	页面日期
`results[].content`	string	可选。`need_content=true` 时可能返回的正文片段
`lokospace_billing.requestId`	string	本次请求 ID
`lokospace_billing.creditsUsed`	number	本次实际扣除积分
`lokospace_billing.balanceAfter`	number \| null	扣除后余额

结果为空时 creditsUsed 为 0，不扣费。

首次返回可能使用 link 或 description 作为别名；相同幂等键重放时会归一化为 url 和 snippet。

抓取接口

请求

curl https://sheverai.com/8811c8/api/llm/v1/web/fetch \
  -H "Authorization: Bearer $LOKO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fetch-20261022-001" \
  -d '{
    "url": "https://example.com/article"
  }'

字段	类型	必填	说明
`url`	string	是	要抓取的地址，1 到 8192 字符，必须是 http(s)
`Idempotency-Key`	string	否	请求头。建议传。有结果时相同键重试返回缓存结果

url 不能带账号密码。只接受带 host 的 http 或 https 地址。

{
  "title": "示例文章",
  "content": "正文内容……",
  "lokospace_billing": {
    "requestId": "<请求 ID>",
    "creditsUsed": "<本次扣除积分>",
    "balanceAfter": "<扣除后余额>"
  }
}

字段	类型	说明
`title`	string \| null	页面标题
`content`	string	正文文本。抓不到正文时为空字符串
`lokospace_billing.requestId`	string	本次请求 ID
`lokospace_billing.creditsUsed`	number	本次实际扣除积分
`lokospace_billing.balanceAfter`	number \| null	扣除后余额

content 为空时 creditsUsed 为 0，不扣费。

计费说明

搜索和抓取都按 per_unit 计费，一次成功调用扣一次。搜索只在 results 非空时扣费，抓取只在 content 非空时扣费；空结果不扣积分。

单价从 model_pricing 读取，文档不写死具体价格。模型可用性以 GET /models 返回为准，实际扣费以响应里的 lokospace_billing.creditsUsed 为准。

1 元 = 100 积分。有扣费的成功调用会按幂等键缓存，重试不会重复扣费；空结果不落库，重试会重新请求。

成功响应带 x-lokospace-request-id；有扣费时还会带 x-lokospace-credits-used。

错误与常见问题

状态	含义	处理
400	`query` 为空或超过 128 字符，`url` 非法或超过 8192 字符	按返回的 `message` 修正
401	密钥缺失、无效、已撤销或已过期	重新创建或更换密钥
402	积分不足	充值后重试。响应里的 `available_credits` 是可用余额
403	目标地址被安全策略拦截	换一个公开页面，不要重试同一地址
404	抓取不到可提取内容，或工具模型不存在	确认页面可公开访问，或联系管理员检查工具模型
429	触发搜索限流，或上游模型服务频率受限	按 `Retry-After` 或指数退避后重试
502	上游模型服务连接失败、超时，或返回异常	稍后重试。搜索和抓取共用约 4.5 秒上游预算
503	没有配置按次定价，或工具渠道凭证不可用	联系管理员检查模型定价与渠道

常见问题：

搜索和抓取为什么共用超时？两个接口走同一条工具链，单次请求的上游总预算约 4.5 秒，超时返回 502。
count 和 limit 有什么区别？没有区别，limit 是兼容别名。两个都传时以 count 为准。
相同幂等键重放会拿到什么？有结果时才会重放：搜索最多保留 20 条结果，且不保留 content；抓取正文最多保留 20000 字。空结果不缓存，重试会重新请求。需要完整内容时换一个新的幂等键。
403 和 404 怎么区分？403 是安全策略拦截，换地址；404 是页面没有可提取内容，或工具模型不可用。

开发者文档