核子GEO API 文档

整站 GEO/SEO 评测与首页测评 API · v1

Bearer Token 鉴权 10次/60秒限速异步排队

📋 概览

Base URL	`https://www.heezi.cn/api/v1`
鉴权方式	Bearer Token（API Key，格式 `hz_` 开头）
限速策略	每个 API Key 每 60 秒最多 10 次请求（超限返回 `429`）
请求格式	`Content-Type: application/json`
响应格式	JSON
字符编码	UTF-8

🔑 鉴权

所有 API 请求需要在 HTTP Header 中携带 API Key：

Authorization: Bearer hz_your_api_key_here

获取 API Key

注册并登录核子GEO 账号
调用 POST /api/v1/api-keys 创建 API Key（需 session 登录）
API Key 仅在创建时显示一次，请妥善保管

⚠️ 安全提示：请勿在前端代码中暴露 API Key。建议在服务端调用 API 并转发结果。

⏱️ 限速

每个 API Key 每 60 秒最多 10 次请求
超限时返回 429 Too Many Requests
响应头包含 Retry-After（建议等待秒数）

// 429 响应示例
{
  "error": "rate_limited",
  "message": "请求过于频繁，每分钟最多 10 次，请 53 秒后重试",
  "retry_after": 53
}

📚 接口列表

POST /api/v1/analyze 提交首页测评

请求参数

参数	类型	必填	说明
`domain`	string	是	网站域名，如 `baidu.com`（无需 http 前缀，自动去除 www.）

请求示例

curl -X POST https://www.heezi.cn/api/v1/analyze \
  -H "Authorization: Bearer hz_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "baidu.com"}'

响应（202 Accepted）

{
  "task_id": "9b480796-d72",
  "status": "queued",
  "domain": "baidu.com",
  "poll_url": "/api/v1/analyze/status/9b480796-d72",
  "message": "测评已提交，请轮询 poll_url 查询进度"
}

GET /api/v1/analyze/status/<task_id> 查询首页测评状态

路径参数

参数	类型	说明
`task_id`	string	由 `POST /analyze` 返回的任务ID

响应（200）

{
  "task_id": "9b480796-d72",
  "status": "completed",
  "domain": "baidu.com",
  "report_id": "20260714183624",
  "overall_score": 27.0,
  "grade": "D",
  "scores": {
    "aeo": 15.4,
    "geo": 20.6,
    "seo": 44.6,
    "semantic": 41.8,
    "authority": 17.4,
    "corpus": 20.2
  },
  "report_url": "https://www.heezi.cn/report/baidu.com",
  "completed_at": 1784025384.37
}

status 取值： queued（排队中）→ analyzing（分析中）→ completed（完成）| failed（失败）

GET /api/v1/report/<domain> 获取最新首页测评报告

路径参数

参数	类型	说明
`domain`	string	域名，如 `baidu.com`

响应（200）

{
  "domain": "baidu.com",
  "url": "https://baidu.com",
  "overall_score": 27.0,
  "grade": "D",
  "scores": {
    "aeo": 15.4, "geo": 20.6, "seo": 44.6,
    "semantic": 41.8, "authority": 17.4, "corpus": 20.2
  },
  "source": "api",
  "created_time": "2026-07-14 18:36:24",
  "report_url": "https://www.heezi.cn/report/baidu.com"
}

POST /api/v1/fullsite-audit 提交整站测评

请求参数

参数	类型	必填	说明
`domain`	string	是	网站域名
`sitemap_url`	string	否	Sitemap URL，留空自动发现
`plan_type`	string	否	套餐：`basic`(10页) / `pro`(30页) / `enterprise`(100页)，默认 `basic`

请求示例

curl -X POST https://www.heezi.cn/api/v1/fullsite-audit \
  -H "Authorization: Bearer hz_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "plan_type": "basic"}'

响应（202 Accepted）

{
  "audit_id": 5,
  "status": "pending",
  "domain": "example.com",
  "plan_type": "basic",
  "poll_url": "/api/v1/fullsite-audit/status/5",
  "message": "整站评测已提交，请轮询 poll_url 查询进度"
}

⚠️ 排队规则：同一用户同时只能有一个进行中的整站评测任务，需等待完成才能提交下一个（返回 409 Conflict）。

GET /api/v1/fullsite-audit/status/<audit_id> 查询整站测评状态

响应（200 · 进行中）

{
  "audit_id": 5,
  "status": "analyzing",
  "domain": "example.com",
  "plan_type": "basic",
  "progress": "3/10",
  "total_urls_found": 4752
}

响应（200 · 已完成）

{
  "audit_id": 5,
  "status": "completed",
  "domain": "example.com",
  "progress": "10/10",
  "total_urls_found": 4752,
  "overall_score": 62.3,
  "grade": "B",
  "dimension_scores": {
    "aeo": 65.2, "geo": 63.1, "seo": 68.5,
    "semantic": 58.0, "authority": 40.3, "corpus": 45.0
  },
  "report_url": "/api/v1/fullsite-audit/report/5",
  "web_report_url": "https://www.heezi.cn/fullsite-audit/report/5"
}

GET /api/v1/fullsite-audit/report/<audit_id> 获取整站测评报告（JSON）

响应（200 · 摘要）

{
  "audit_id": 5,
  "domain": "example.com",
  "plan_type": "basic",
  "status": "completed",
  "overall_score": 62.3,
  "grade": "B",
  "urls_found": 4752,
  "urls_selected": 10,
  "urls_analyzed": 10,
  "dimension_scores": { "aeo": 65.2, "geo": 63.1, ... },
  "score_distribution": { "excellent": 1, "good": 3, ... },
  "common_issues": [{ "dimension": "权威度", "affected_pages": 10, ... }],
  "priority_actions": [{ "url": "https://...", "priority": 8, ... }],
  "pages": [
    {
      "id": 42, "url": "https://example.com/", "page_type": "homepage",
      "overall_score": 72.5, "grade": "B",
      "scores": { "aeo": 75.0, ... },
      "priority": 2,
      "detail_url": "https://www.heezi.cn/fullsite-audit/page/42"
    }
  ],
  "web_report_url": "https://www.heezi.cn/fullsite-audit/report/5"
}

POST /api/v1/api-keys 创建 API Key（需 session 登录）

请求参数

参数	类型	必填	说明
`name`	string	否	Key 名称备注，默认"默认"

响应（201）

{
  "api_key": "hz_23a6868eb12a5670840b698757ce164865960e6902e857b0",
  "name": "我的Key",
  "message": "请妥善保管API Key，仅显示一次"
}

GET /api/v1/api-keys 列出 API Keys（需 session 登录）

响应（200）

{
  "keys": [
    {
      "id": 1, "name": "我的Key", "is_active": 1,
      "total_requests": 42, "api_key_masked": "hz_23a686****",
      "created_at": 1784025000.0, "last_used": 1784025384.0
    }
  ]
}

DELETE /api/v1/api-keys/<key_id> 删除 API Key（需 session 登录）

响应（200）

{ "message": "API Key 已删除" }

❌ 错误码

HTTP状态码	error字段	说明
400	`missing_domain`	未提供 domain 参数
400	`invalid_domain`	域名格式不正确
401	`missing_or_invalid_auth`	未提供 Authorization 头
401	`invalid_api_key`	API Key 无效或已禁用
401	`login_required`	API Key 管理接口需 session 登录
403	`forbidden`	无权访问该资源
404	`task_not_found`	任务不存在或已过期
404	`report_not_found`	未找到测评报告
404	`audit_not_found`	评测任务不存在
409	`audit_in_progress`	已有进行中的整站评测
409	`not_completed`	评测尚未完成
429	`rate_limited`	请求频率超限

💡 完整调用示例

Python 示例

import requests
import time

API_KEY = "hz_your_api_key"
BASE = "https://www.heezi.cn/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交首页测评
resp = requests.post(f"{BASE}/analyze", json={"domain": "baidu.com"}, headers=HEADERS)
task_id = resp.json()["task_id"]
print(f"任务ID: {task_id}")

# 2. 轮询状态
while True:
    resp = requests.get(f"{BASE}/analyze/status/{task_id}", headers=HEADERS)
    data = resp.json()
    if data["status"] in ("completed", "failed"):
        break
    time.sleep(3)

print(f"评分: {data['overall_score']} ({data['grade']})")
print(f"报告: {data['report_url']}")

整站测评示例

# 1. 提交整站测评
resp = requests.post(f"{BASE}/fullsite-audit", json={
    "domain": "example.com",
    "plan_type": "pro"
}, headers=HEADERS)
audit_id = resp.json()["audit_id"]

# 2. 轮询状态（整站评测耗时较长，建议30秒轮询一次）
while True:
    resp = requests.get(f"{BASE}/fullsite-audit/status/{audit_id}", headers=HEADERS)
    data = resp.json()
    print(f"进度: {data.get('progress', '?')} | 状态: {data['status']}")
    if data["status"] in ("completed", "failed"):
        break
    time.sleep(30)

# 3. 获取完整报告
resp = requests.get(f"{BASE}/fullsite-audit/report/{audit_id}", headers=HEADERS)
report = resp.json()
print(f"综合分: {report['overall_score']} ({report['grade']})")
for p in report["pages"]:
    print(f"  {p['page_type']:10s} {p['overall_score']:5.1f} {p['url']}")

📊 评分说明

六大维度权重

维度	权重	说明
AEO（AI引擎可见性）	25%	网站在 ChatGPT/DeepSeek 等 AI 大模型中的可见性
GEO（生成式引擎优化）	25%	内容对 AI 引擎的优化程度
SEO（搜索引擎优化）	20%	传统搜索引擎表现
语义质量	15%	AI 模型对页面内容的理解度
权威度	10%	E-E-A-T 信号强度
语料库质量	5%	被 AI 引用的价值

评级标准

分数	评级	说明
≥85	A	优秀
70-84	B	良好
55-69	C	及格
40-54	D	较差
<40	F	极差