SEO/GEO 接口用于让客户站点读取 GrowthOS 已发布的页面优化结果。连接器按 path 和 locale 查询 overlay，并在页面渲染或缓存刷新时注入到页面 head。 该接口只读取已经发布的 overlay。没有 overlay 时，客户站点应保持原页面 head 不变。

​
接口总览

能力方法路径调用方
查询已发布 overlayGET/seo/overlays插件或客户站点服务端

​
通用请求头

Header必填说明
Authorization: Bearer <site_token>是站点服务端 token

​
GET /seo/overlays

查询可注入到页面 head 的 SEO/GEO 数据。 
GET /api/connector/v1/seo/overlays?path=/archives/31&locale=zh-CN
Authorization: Bearer <site_token>

​
Query 参数

参数类型必填说明
pathstring否页面路径；传入后只返回匹配路径的 overlay
localestring否语种；传入后只返回匹配语种的 overlay
limitinteger否返回数量，1-200

​
请求示例

curl "$CONNECTOR_API_BASE/seo/overlays?path=/archives/31&locale=zh-CN" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN"

​
成功响应

{
  "ok": true,
  "data": {
    "siteId": "site_id",
    "overlays": [
      {
        "id": "overlay_id",
        "path": "/archives/31",
        "locale": "zh-CN",
        "title": "优化后的标题",
        "description": "优化后的描述",
        "canonical": "https://customer.example/archives/31",
        "robots": "index,follow",
        "aiSummary": "页面摘要",
        "openGraph": {
          "title": "OG 标题",
          "description": "OG 描述"
        },
        "twitter": {
          "card": "summary_large_image"
        },
        "faq": [
          {
            "question": "常见问题",
            "answer": "回答内容"
          }
        ],
        "schemaJsonLd": [
          {
            "@context": "https://schema.org",
            "@type": "Article"
          }
        ],
        "updatedAt": "2026-06-01T08:00:00.000Z"
      }
    ]
  },
  "requestId": "request_id"
}

​
Overlay 字段

字段说明
path匹配页面路径
locale匹配语种
title建议注入到 <title>
description建议注入到 meta description
canonicalcanonical URL
robotsrobots meta
aiSummaryAI 摘要，可用于页面摘要或内部展示
openGraphOpen Graph 标签数据
twitterTwitter Card 标签数据
faqFAQ 内容，可用于页面展示或 Schema
schemaGraphSchema graph 原始结构
schemaJsonLdJSON-LD 数组，可注入为 application/ld+json
internalLinks建议内链
entities实体覆盖信息
updatedAtoverlay 更新时间

​
注入规则

内容推荐处理
title替换当前页面 <title>
description替换或创建 meta[name="description"]
canonical替换或创建 link[rel="canonical"]
robots替换或创建 meta[name="robots"]
openGraph替换对应 og:* meta
twitter替换对应 twitter:* meta
schemaJsonLd注入 JSON-LD script，避免重复注入旧 GrowthOS script

​
常见错误

HTTP错误码说明处理建议
401INVALID_TOKENtoken 无效检查站点 token
429RATE_LIMITED请求过快按 Retry-After 退避重试

​
实现要点

  • 按标准化后的 path + locale 匹配，不要跨语种复用 overlay。
  • 没有 overlay 时保持页面原始 head。
  • 注入前先移除或替换旧的 GrowthOS 标签，避免重复 title、description 或 JSON-LD。
  • 正文内容不由 overlay 接口替换。
  • 高流量页面建议短缓存 overlay，并在插件任务完成后刷新缓存。