跳到主内容
QVSO
开始检测

开放 API

以编程方式获取 AI 收录检测报告。接口与网页版「AI收录综合查询」走同一条检测管线，结果一致。本页所有示例均可直接复制运行。

端点与参数

POST https://qvso.com/api/v1/check
Content-Type: application/json

{
  "url": "example.com"
}
http
  • url 必填：待检测域名或网址，支持 example.com、https://example.com 等形式。
  • 检测全程约 40~100 秒（含实时联网检索与 5 家 AI 平台问答），客户端超时应设置在 120 秒以上。
  • 每次成功检测会留存快照，可通过返回的 snapshotUrl 永久访问。

响应与字段

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 2026-02-11T13:00:00.000Z

{
  "snapshotId": "50c2be03-1ef6-45b0-b90c-f9a655958486",
  "snapshotUrl": "/report/50c2be03-1ef6-45b0-b90c-f9a655958486",
  "report": {
    "domain": "example.com",
    "totalScore": 64,
    "crawlerScore": 72,
    "memoryScore": 50,
    "checks": [ { "id": "robots", "name": "robots.txt", "status": "pass", ... } ],
    "bots":   [ { "token": "GPTBot", "access": "allowed", ... } ],
    "memory": [ { "platform": "豆包", "status": "known", ... } ],
    "issues": [ { "level": "warning", "text": "...", "fix": "..." } ],
    ...
  }
}
json
字段类型说明
snapshotIdstring快照 ID，本次检测报告的固定标识
snapshotUrlstring快照页路径，拼接站点域名后即为永久访问地址
report.domainstring规范化后的域名
report.totalScorenumber综合分（0~100）：爬虫可达性 ×40% + AI 认知 ×60%
report.crawlerScorenumber爬虫可达性分（0~100），由基础设施检测项折算
report.memoryScorenumberAI 认知度分（0~100），由各平台认知问答折算
report.checks[]array基础设施检测项；status ∈ pass / warn / fail / info（info 为参考项，不计分）
report.bots[]array39 只 AI 爬虫的 robots 放行判定；access ∈ allowed / partial / blocked / none
report.memory[]array各 AI 平台认知问答结果；status ∈ known / unknown / error，含回答文本与口碑判定
report.issues[]array问题与修复建议清单，按严重度排序；level ∈ critical / warning
report.keywords / sources / citedPagesarray认知关键词、AI 推荐信源、本站被引页面；旧快照或数据不足时缺省
report.pageSignals / agentFiles / retrieval / advisormixed页面语义信号、Agent 接入探测、联网检索集、定制建议等可选字段

限流与错误码

免费额度每 IP 每小时 10 次，限额状态通过 X-RateLimit-* 响应头返回。

状态码含义处理方式
200检测完成，report 为完整报告正常解析
400请求体缺少 url 或格式不正确检查 JSON 体与 Content-Type
422目标站点无法访问或域名格式非法error 字段给出具体原因
429超出限流额度响应体 resetAt 为额度恢复时间
HTTP/1.1 422 Unprocessable Entity
{ "error": "无法访问目标站点，请检查域名是否正确或站点是否在线" }

HTTP/1.1 429 Too Many Requests
{ "error": "超出限流额度", "resetAt": "2026-02-11T14:00:00.000Z" }
json

调用示例

curl -X POST https://qvso.com/api/v1/check \
  -H 'Content-Type: application/json' \
  -d '{"url": "example.com"}' \
  --max-time 150
bash
// Node.js / 浏览器 fetch
const res = await fetch('https://qvso.com/api/v1/check', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'example.com' }),
});
const { snapshotId, snapshotUrl, report } = await res.json();
console.log(report.totalScore, snapshotUrl);
js

接口当前免费、无需鉴权，请勿用于批量探测他人站点；限流策略可能随使用情况调整， 调整时会更新本页说明。检测数据来自公开网络请求与 AI 平台实时应答，各项结果仅供分析参考。

流式检测（SSE）

需要向终端用户展示检测进度时，使用 Server-Sent Events 流式接口：与网页版完全同款管线，进度事件逐条推送，最后一个事件携带完整报告。

接口与请求体说明限流
POST /api/check · {url}站点检测，与网页版同一条流式管线每 IP 20 次/小时
POST /api/keywords · {keyword, brand, domain?}品牌 GEO 诊断：问题扩展、多平台实测、结论与行动计划每 IP 10 次/小时
POST /api/article-check · {url}文章 GEO 检测：抓取正文、生成提问、双口径引用判定每 IP 20 次/小时
  • 响应头 Content-Type: text/event-stream，每个事件为一行 data: <JSON>。
  • 站点检测依次推送 step 事件（管线进度）与 report 事件（完整报告，与 /api/v1/check 的 report 字段同构）。
  • 品牌与文章检测推送进度事件后，以 summary 事件给出完整报告（含 reportId，可拼固定快照链接）。
curl -N -X POST https://qvso.com/api/check \
  -H 'Content-Type: application/json' \
  -d '{"url": "example.com"}'
bash

MCP Server（AI 客户端直接调用）

本站同时提供 MCP（Model Context Protocol）端点，Claude Desktop、Cursor 等支持 MCP 的 AI 客户端配置后可直接调用检测与榜单能力。协议为 JSON-RPC 2.0 over HTTP POST，方法： initialize / tools/list / tools/call / ping。

// 客户端配置（Claude Desktop / Cursor）
{
  "mcpServers": {
    "qvso": { "url": "https://qvso.com/api/mcp" }
  }
}
json
# 协议级调用示例：读取 example.com 最新快照摘要
curl -X POST https://qvso.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": { "name": "get_latest_report", "arguments": { "domain": "example.com" } }
  }'
bash
工具说明限流
check_site(domain)跑一次完整检测（与 /api/v1/check 同管线），返回 markdown 摘要每 IP 5 次/小时
get_latest_report(domain)读取该域名最近一次检测快照摘要，只读秒回不限流
get_rankings(limit)获取 AI 可见性榜单（默认 10 条，最大 50），只读不限流
get_brand_report(id)按快照 ID 读取品牌 GEO 诊断报告摘要（提及率、首推率、SOV、阶段）不限流
get_article_report(id)按快照 ID 读取文章 GEO 检测报告摘要（覆盖率、URL 引用率、优化建议）不限流