把页面质量审核接入你的工作流

这是一套面向外部开发者的异步完整页面质量审核接口。text、html 和公开 URL 都执行同一套 page-quality-review.full.v1 规则；公开 URL 还会补充桌面端、移动端、浏览器交互和可见加载证据。服务不会登录目标页面，也不会转发你的 Cookie 或登录态。

文档公开可见；只有创建和管理 API Key 的控制台需要登录。登录后在个人中心创建 Key，Secret 只会显示一次。

curl https://convertos.ai/api/v1/reviews/page-quality/REVIEW_ID \
  -H "Authorization: Bearer cvt_live_YOUR_KEY"

去个人中心创建或管理 API Key →

1. 01

   登录并创建一个 API Key。

2. 02

   提交 text、html 或公开 url，所有请求统一执行完整审核。

3. 03

   保存 job ID，轮询 statusUrl 直到 completed 或 failed。

curl -X POST https://convertos.ai/api/v1/reviews/page-quality \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-001" \
  -d '{
    "sourceType": "url",
    "url": "https://example.com/article",
    "language": "en",
    "mode": "standard",
    "pageType": "blog_article",
    "targetJob": "Answer the searcher’s question and give them a next action."
  }'

{
  "ok": true,
  "job": {
    "id": "8c1b...",
    "status": "queued",
    "creditCost": 20,
    "statusUrl": "/api/v1/reviews/page-quality/8c1b..."
  }
}

提交成功返回 202。任务会进入队列，积分在任务被接受时扣除；如果队列或审核失败，会自动退回本次积分。

请求头 Idempotency-Key 可选但推荐使用：网络重试时复用同一个 Key，不会重复创建任务或重复扣费。

batch 需要提交 3 到 5 个相关页面。每个页面都执行同一套完整审核，再执行跨页面结构相似度检查。批量结果可能因为页面重复而 Fail，即使单页分数都不错。

curl -X POST https://convertos.ai/api/v1/reviews/page-quality/batch \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-001" \
  -d '{
    "mode": "batch",
    "language": "en",
    "pages": [
      {"label":"Page A","sourceType":"url","url":"https://example.com/a","mode":"standard","pageType":"programmatic"},
      {"label":"Page B","sourceType":"url","url":"https://example.com/b","mode":"standard","pageType":"programmatic"},
      {"label":"Page C","sourceType":"url","url":"https://example.com/c","mode":"standard","pageType":"programmatic"}
    ]
  }'

使用创建任务返回的 job.id 或 statusUrl 查询。只有创建该任务的同一个 API Key 能读取它。

curl https://convertos.ai/api/v1/reviews/page-quality/REVIEW_ID \
  -H "Authorization: Bearer cvt_live_YOUR_KEY"

completed 任务的 result 对象包含 preflight、contracts、competitiveBaseline、七个维度、gates、caps、threshold、evidence、findings 和 aiAnalysis。固定规则负责技术事实和安全底线；AI 根据实际页面内容判断意图、准确性、证据、原创性和 E-E-A-T，并参与最终 verdict。

{
  "version": "page-quality-review.v1",
  "reviewProtocol": "page-quality-review.full.v1",
  "verdict": "iterate",
  "score": 74,
  "confidence": "medium",
  "mode": "standard",
  "sourceType": "html",
  "summary": "...",
  "gates": [{"name":"rendered_experience","outcome":"pass","reason":"..."}],
  "caps": {"applied": [], "finalScoreCap": null},
  "threshold": {"scoreRequired": 85, "minCoreDimension": 75, "coreDimensionsMeetMinimum": true},
  "aiAnalysis": {
    "provider": "agentsflare",
    "scope": "content_quality",
    "status": "completed",
    "verdict": "iterate",
    "score": 78,
    "summary": "...",
    "findings": [{
      "code": "AI_CONTENT_NEXT_STEP",
      "message": "The opening explains the topic but does not make the next action explicit.",
      "recommendation": "Add one concrete next step after the opening answer.",
      "evidence": "The opening section states the topic but contains no action instruction."
    }],
    "eeat": {
      "experience": {"score": 72, "status": "partial", "note": "Some practical examples are present, but first-hand experience is not established.", "evidence": "The page gives examples but does not identify a first-hand source."},
      "expertise": {"score": 80, "status": "partial", "note": "The topic is explained with relevant detail.", "evidence": "The page explains the criteria and tradeoffs."},
      "authoritativeness": {"score": 65, "status": "not_evidenced", "note": "No accountable authority is supplied.", "evidence": "No author organization or external citation is visible."},
      "trustworthiness": {"score": 74, "status": "partial", "note": "Claims are mostly bounded but proof is limited.", "evidence": "The page contains claims without nearby attributable sources."}
    }
  },
  "dimensions": {
    "contentIntent": { "score": 82, "status": "inspected", "notes": [] },
    "seoIndexability": { "score": 68, "status": "inspected", "notes": [] },
    "geoExtractability": { "score": 76, "status": "inspected", "notes": [] }
  },
  "metrics": {
    "wordCount": 820,
    "headingCount": 9,
    "h1Count": 1,
    "hasTitle": true,
    "hasDescription": true
  },
  "findings": [
    {
      "severity": "warning",
      "code": "IMAGE_ALT",
      "message": "...",
      "recommendation": "..."
    }
  ]
}

每条 finding 都有 severity、code、message 和 recommendation，适合直接映射到你自己的 issue、工单或发布门禁。

按输入类型计费，不按结果长度计费；所有输入都执行完整审核。任务被 API 接受时扣除；队列不可用或审核失败时自动退回。

这些限制用于保护共享队列和积分账户。页面和接口都应该明确处理 429、402、413 等状态。

部署提示：完整 URL 审核需要生产环境配置 PAGE_REVIEW_BROWSER_WS_URL 或 BROWSERLESS_URL。未配置远程浏览器时不会伪造渲染结果，也不会返回 500；结果会明确标记浏览器证据未完成并保持 iterate。

错误统一返回 JSON：ok=false、error.code、error.message，部分错误还会带 details。只有网络超时或 5xx 适合自动重试；参数错误和认证错误不要盲目重试。

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "This API key has reached 60 accepted reviews per minute.",
    "details": { "retryAfterSeconds": 60 }
  }
}