Developers

API 文档

基础地址 https://seolift.pages.dev。所有接口返回 JSON，同一域名下支持 CORS。认证用 Authorization: Bearer <key>，无密钥时按 IP 计免费额度。

接口总览

方法	路径	用途	额度
GET	/api/health	健康检查	免费
POST	/api/audit	页面 SEO 审计（18 项）	1
POST	/api/redirect	跳转链追踪	免费
POST	/api/links	死链扫描	2
POST	/api/signup	领取免费密钥	免费
GET	/api/me	当前套餐与额度	免费
POST	/api/billing/checkout	创建订阅结账页	免费

POST /api/audit

抓取目标页面原始 HTML，执行 18 项加权检查并返回 0–100 分。

请求体

url

必填，可省略协议

keyword

可选，用于判断关键词布局

curl -X POST https://seolift.pages.dev/api/audit \ -H "Authorization: Bearer sk_free_xxx" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/pricing","keyword":"定价"}'

{ "ok": true, "url": "https://example.com/pricing", "score": 86, "grade": "A", "meta": { "status": 200, "ttfb": 212, "bytes": 84213 }, "content": { "title": "定价 — Example", "titleLength": 22, "headings": { "h1": ["定价"], "h2": ["套餐对比"] }, "images": { "total": 12, "missingAlt": 1 }, "links": { "internal": 34, "external": 6 } }, "checks": [ { "id": "title", "label": "Title 标签", "status": "pass", "weight": 12, "detail": "22 字符：定价 — Example", "fix": "控制在 15–65 字符…" } ], "quota": { "used": 3, "limit": 20, "remaining": 17, "reset": "2026-10-21" } }

POST /api/redirect

curl -X POST https://seolift.pages.dev/api/redirect \ -H "Content-Type: application/json" \ -d '{"url":"http://example.com/old"}' # → { "ok":true, "hops":2, "loop":false, "final":"https://example.com/new", # "chain":[{ "hop":0, "status":301, "ms":88 }, ...], "issues":["存在 2 次跳转…"] }

POST /api/links

curl -X POST https://seolift.pages.dev/api/links \ -H "Authorization: Bearer sk_free_xxx" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/blog","limit":40}' # → { "ok":true, "scanned":40, "brokenCount":3, # "broken":[{"url":"https://example.com/x","status":404}], "results":[...] }

GET /api/me

curl https://seolift.pages.dev/api/me -H "Authorization: Bearer sk_free_xxx" # → { "ok":true, "plan":"free", "email":"you@co.com", # "usage":{ "used":12, "limit":200, "remaining":188, "date":"2026-10-21" } }

错误码

HTTP	error	含义
400	invalid_url	URL 无法解析或协议不支持
415	not_html	目标不是 HTML 页面
429	quota_exceeded	当日额度用尽
429	invalid_api_key	密钥无效或已撤销
502	fetch_failed	目标站点不可达或被拦截
501	billing_not_configured	支付通道未配置

CI/CD 集成范式

在部署后跑一次审计，得分低于阈值就让流水线失败——这是最容易落地的 SEO 回归测试。

#!/usr/bin/env bash # .github/workflows/seo.yml 中调用 set -euo pipefail URL="$1"; MIN="${2:-80}" SCORE=$(curl -s -X POST https://seolift.pages.dev/api/audit \ -H "Authorization: Bearer $SEOLIFT_KEY" \ -H "Content-Type: application/json" \ -d "{\"url\":\"$URL\"}" | jq -r '.score') echo "SEO score: $SCORE (min: $MIN)" [ "$SCORE" -ge "$MIN" ] || { echo "SEO 回归，阻断发布"; exit 1; }

限流与成本

免费 20 次/天（按 IP），注册密钥 200 次/天，Pro 5,000 次/天。计数存于 Cloudflare KV，UTC 零点重置，48 小时后自动过期。单次审计 Worker CPU 时间通常在 10ms 以内，不消耗额外费用。

认证方式

所有需要额度的接口都支持两种身份：匿名（按来源 IP 计 20 次/天）和API 密钥。密钥通过 Authorization: Bearer sk_xxx 头传递，没有密钥时接口仍然可用，只是额度更低。在控制台领取的免费密钥会把额度提升到 200 次/天，有效期与额度每天 UTC 零点重置。

密钥只在签发时完整显示一次，服务端只保存哈希。如果你把密钥提交进了公开仓库，直接在控制台吊销即可，不需要更换其他配置。

评分是如何在中英文之间切换的

标题与描述这两项检查不按字符数判定，而按渲染像素判定。原因是 Google 按像素截断：桌面端标题约 580px、描述约 920px。一个汉字约占 1em，西文平均只有约 0.48em，所以英文站那条「标题 60 字符」的经验值搬到中文站会严重超标——中文标题大约 29 字就到顶了。

接口会自动逐字符累加宽度，因此像 Disallow/Allow、GPTBot 这类西文术语不会让一条中文描述被误判成超长。返回体里会带上估算的像素值，方便你自己复核。

常见问题

接口会把我的 URL 存下来吗？

不会。抓取、解析、评分在同一个请求内完成，结果只返回给调用方。我们只存一个按天滚动的计数键，不存被检测的域名。

目标站点拦截了爬虫怎么办？

部分站点会对无 UA 的请求返回 403。这类情况接口会返回 fetch_failed（HTTP 502）。它反映的是我们取不到页面，不代表该站点的 SEO 有问题。

可以批量提交吗？

单次请求只处理一个 URL。批量巡检是 Pro 的能力，或者你在自己的 CI 里并发调用——每次调用独立计额度。