开放 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

字段	类型	说明
snapshotId	string	快照 ID，本次检测报告的固定标识
snapshotUrl	string	快照页路径，拼接站点域名后即为永久访问地址
report.domain	string	规范化后的域名
report.totalScore	number	综合分（0~100）：爬虫可达性 ×40% + AI 认知 ×60%
report.crawlerScore	number	爬虫可达性分（0~100），由基础设施检测项折算
report.memoryScore	number	AI 认知度分（0~100），由各平台认知问答折算
report.checks[]	array	基础设施检测项；status ∈ pass / warn / fail / info（info 为参考项，不计分）
report.bots[]	array	39 只 AI 爬虫的 robots 放行判定；access ∈ allowed / partial / blocked / none
report.memory[]	array	各 AI 平台认知问答结果；status ∈ known / unknown / error，含回答文本与口碑判定
report.issues[]	array	问题与修复建议清单，按严重度排序；level ∈ critical / warning
report.keywords / sources / citedPages	array	认知关键词、AI 推荐信源、本站被引页面；旧快照或数据不足时缺省
report.pageSignals / agentFiles / retrieval / advisor	mixed	页面语义信号、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);

接口当前免费、无需鉴权，请勿用于批量探测他人站点；限流策略可能随使用情况调整，调整时会更新本页说明。检测数据来自公开网络请求与 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 引用率、优化建议）	不限流