让 Codex 真正会做 SEO

SEO Agent 给 Codex 接上SEO 数据和执行能力

Codex会分析和写作，但它默认不知道你的网站实时排名、客户搜索需求和真实流量，也没有完整的 SEO 执行流程。SEO Agent补上这些能力，让 Codex 能根据真实数据帮你研究、诊断、做内容、发布和持续监控。

一句话理解：你负责说清业务目标和确认结果，Codex 负责理解与执行，SEO Agent 负责提供真实数据、专业方法和网站连接。

有真实数据有完整流程能执行落地

SEO 运营人员可以少做查数据、整理表格和写初稿的重复工作；外贸老板可以少买重复工具、少花外包沟通成本，把预算用在真正重要的增长动作上。

看一个简单例子从第一步开始

SEO Agent

工作流示例 · AI 正在执行 SEO Agent 任务

我不懂 SEO，帮我看看这个月网站先做什么。

SEO Agent 正在查看：搜索机会 · 页面问题 · 真实流量

我会先列出最值得做的 3 件事，说明为什么、先改哪一页和预计工作量。 你只需要做判断，涉及修改或发布时我会先等你确认。

不懂 SEO 也能这样用

你只要说目标，SEO Agent 帮你完成剩下的工作

你在 Codex 里用日常语言提问，SEO Agent 会把分散的 SEO 资料整理成可以执行的下一步。

1 · 你说清楚目标“帮我让外贸网站获得更多美国客户。”

不需要知道该查什么，也不需要先整理一堆表格。

2 · Agent 找证据查看关键词、竞争对手、页面和真实流量

它把分散资料放到一起，解释哪些机会值得优先做。

3 · 你确认行动知道先改哪一页、写什么、什么时候复查

认可后再让 Codex 修改页面、创建 WordPress 草稿或正式发布。

SEO Agent 核心价值

让 Codex 从“会回答问题”，变成“能完成 SEO 工作”

普通 AI 只能根据已有知识给建议。SEO Agent 把实时 SEO 数据、标准工作流程和网站执行能力提供给 Codex，让每个建议都有依据，也能继续变成实际行动。

真实 SEO 数据查看客户搜索、排名、竞争对手、网站问题和真实流量，不靠猜。

标准 SEO 流程自动完成研究、分析、内容、检查和复盘，避免漏掉重要步骤。

网站执行能力你确认后，可以修改页面、创建 WordPress 草稿、发布并继续监控。

六项核心功能

你不需要记住这些专业工具，只要在 Codex 里说清想达到的目标。

研究市场和客户搜索

查客户在搜索什么、需求有多大、竞争难不难，找出值得优先做的关键词和市场机会。

关键词搜索需求市场机会

看懂竞争对手在做什么

分析同行从哪些关键词和页面获得流量，找出你缺少的内容、页面和外链机会。

竞争对手内容差距外链机会

检查网站和页面问题

检查搜索引擎能否找到网站，以及标题、页面结构、链接、速度和内容哪里需要修改。

网站体检页面问题技术 SEO

规划、生成和优化内容

根据研究结果规划选题、生成文章、更新旧页面，并给出标题、描述和页面修改方案。

内容规划文章生成页面优化

结合真实业务数据判断

连接 GSC 和 GA4 后，结合真实曝光、点击、访问和转化，判断哪些页面最值得先投入。

GSCGA4业务结果

发布、监控和持续优化

你确认后创建 WordPress 草稿或发布，再定时检查排名、流量和 AI 搜索曝光并发送提醒。

WordPress监控通知GEO

SEO Agent 怎么工作

你说一句话，Codex 帮你完成 SEO 任务

每一步都会显示结果。涉及修改或发布时，会停下来等你确认。

1你说目标

说明网站、市场和想解决的问题。

2Agent 查资料

自动查看搜索机会、竞品、页面和流量。

3AI 整理清单

告诉你为什么做、先做什么和预计工作量。

4你确认后执行

可以要求 Codex 修改、创建草稿或发布。

5定时看结果

持续观察排名和流量，发现变化及时提醒。

给 SEO 运营人员

少做重复工作，把时间留给判断

把查关键词、整理竞品、拉数据、写初稿和做周报交给 AI，自己专注于策略、审核和真正影响业务的优化。

给外贸老板

少买重复工具，少花外包沟通成本

不用同时打开很多工具，也不用每个小问题都交给外包。你能直接看到证据、行动和进度，再决定预算投向哪里。

不用长期买一堆工具

用多少算多少，少花固定成本

关键词研究、内容生成、发布和监控按阶段计算。你可以先试用，再决定是否继续，不用为暂时不用的工具付月费。

按阶段研究、生成、发布、监控分别计算 先确认发布和修改前会暂停等待你确认 无月费不用时不扣固定费用

查看详细价格查看使用方法适合独立站卖家、SEO 从业者、SEO 公司和外贸团队

使用帮助

不用懂 SEO，也能让 AI 帮你做网站优化

在 Codex 里说清网站、市场和目标，SEO Agent 会帮你查资料、解释问题、整理行动清单。需要批量任务时，还可以用 API / MCP 接入脚本和内部系统。

产品功能

SEO Agent 当前具备的核心能力

01MCP 接入 AI 工具把 SEO Agent 接入 Codex 等支持 MCP 的 AI 工具，让 AI 按任务调用关键词、GEO、竞品、站内审计和授权数据能力，先完成查数和分析初稿。查询示例：在 Codex 里让 SEO Agent 分析你的真实域名的美国英文市场 SEO 机会。

02API 数据接入用 API Key 调用关键词研究、竞品、排名、GEO、站内审计、GSC 搜索表现和 GA4 流量质量诊断接口，适合自动化脚本、客户报表和内部系统。查询示例：在个人资料里创建 API Key，再到 API / MCP 页面查看 REST 和 MCP 接入示例。

03GEO / AI 搜索与深度审计查询 Google AI Overview 与 ChatGPT 的当前提及、高频来源、历史趋势、新增/丢失、多目标份额和品牌品类格局；同时可复核页面表达、公开爬虫规则、llms.txt 和页面实际 JSON-LD 类型。查询示例：查看我的网站过去 6 个月 AI 可见度趋势，再与 3 个竞品对比。

04关键词与市场需求查询关键词搜索量（月均）、KD、CPC、趋势、搜索意图、问题词、商业词、关键词分组和优先级，帮助判断哪些词值得先做、应该合并到哪个页面。查询示例：深度分析 running shoes 在美国英文市场的关键词难度、搜索意图和相关词。

05竞品策略与内容差距整理前排同行、竞品出词、关键词差距、内容缺口、页面类型和补页路线，服务页面规划。查询示例：分析 custom hoodie manufacturer 在美国英文市场的竞品关键词策略。

06站内审计与技术 SEO检查页面状态、标题、描述、H1、canonical、内外链、图片 alt、正文相关性、关键词覆盖、重复内容和结构化数据。查询示例：给 https://你的真实域名做站内 SEO 审计，围绕 custom hoodie manufacturer 爬取 20 个页面。

07GSC / GA4 授权数据诊断连接自己的 GSC 和 GA4 后，可分析真实搜索表现、页面机会、内容衰退、渠道质量、落地页互动和关键事件。查询示例：用我已连接的 GSC 和 GA4 数据，找出最该优先优化的 SEO 页面。

08报告、执行产物与导出基于数据生成 SEO/GEO 顾问报告、Title、Meta、FAQ、Schema、llms.txt、页面模块、行动清单和 CSV 表格；报告会优先使用中文结构、数据依据、可信度和优先级，避免无依据数字。查询示例：根据刚才的数据生成 FAQ、Schema 和页面优化清单。

使用说明

常见问题解答 FAQ

SEO Agent 是什么？+

SEO Agent 是为 Codex 提供真实 SEO 数据、标准工作流程和网站执行能力的引擎。你只要说清网站、市场和业务目标，Codex 就能借助 SEO Agent 查数据、找问题、做内容，并在你确认后发布和持续监控。

SEO Agent 支持哪些功能？+

支持自然语言创建 SEO 工作流，覆盖关键词研究、SERP 与排名查询、竞品分析、技术 SEO、网站架构、页面优化、内容生成、WordPress/CMS 发布、定时监控与通知、GEO/AI 搜索可见性，以及 GSC/GA4 授权数据诊断。

如何计费？有没有月费？+

SEO 工作流按阶段计费，关键词研究、文章生成、检查、发布和监控分别计算。充值后按实际执行量扣费，无月费；使用前可以查看预计费用，不执行的阶段不会产生对应费用。

连接 WordPress 后，SEO Agent 能修改网站吗？+

可以修改已授权 WordPress 用户有权限管理的文章内容，例如创建草稿、更新标题和正文。正式发布前会等待用户确认。SEO Agent 当前不会修改主题、插件、网站设置或服务器文件，实际权限由 WordPress 用户账号决定。

如何接入 API 或 MCP？+

登录后在个人设置页面创建 API Key，然后到 API / MCP 页面查看 REST 接口和 MCP 配置说明。支持关键词、排名、竞品、GEO、站内审计、GSC 搜索表现与高级诊断、GA4 流量质量诊断等多类接口。API 支持批量调用和费用预估，MCP 可直接接入支持 MCP 协议的 AI 工具如 Codex。

站内审计支持爬取多少页面？+

站内审计默认爬取 20 页，最多支持 100 页，爬取深度最多 5 层。可检查页面状态码、title、meta description、H1-H6 标题、canonical、内外链、图片 alt、正文相关性、关键词覆盖、重复内容、noindex、结构化数据和 JS 渲染等技术 SEO 问题。

什么是 GEO 分析？SEO Agent 能做什么？+

GEO（Generative Engine Optimization，生成式引擎优化）关注品牌和内容在 AI 搜索中的可见性。SEO Agent 使用新版 LLM Mentions 查询 Google AI Overview 与 ChatGPT 的提及、高频来源、历史趋势、新增/丢失、多目标对比和品牌品类格局，并可做页面表达、公开爬虫规则、llms.txt 和结构化数据复核。数据库样本不是实时向每个模型逐条提问；llms.txt 也属于非必需实验项，不能保证获得 AI 引用。

MCP 是什么？和 API 有什么区别？+

MCP（Model Context Protocol）是让 AI 工具可以直接调用外部能力的协议。API 需要你自己写代码调用和处理数据，而 MCP 接入后，支持 MCP 的 AI 工具（如 Codex）可以自动理解你的目标，主动调用 SEO Agent 的标准化数据能力，完成查询、整理和分析初稿等连续工作流，不需要人工切换工具和整理数据。

关键词数据来自哪里？准确度如何？+

关键词和排名数据来自 SEO Agent 的标准化 SEO 数据能力，覆盖主流搜索引擎，支持全球多个国家和语言。数据更新频率高，包含搜索量、竞争度、CPC、趋势、搜索意图等丰富维度，可以满足专业 SEO 分析需求。

如何开始使用 SEO Agent？+

四步即可开始：1. 下载 Codex 和 CC Switch；2. 配置第三方中转站，让 Codex 能正常对话；3. 在个人资料创建 API Key，把 SEO Agent MCP 接入 Codex；4. 在 Codex 中用日常语言说明网站、市场和目标。

适合什么样的用户使用？+

适合 SEO 运营人员、独立站卖家和外贸企业。SEO 运营人员可以减少查数据、整理表格和写初稿的重复工作；外贸老板可以减少重复工具和外包沟通成本，并直接看到证据、行动和进度。

可以导出数据吗？支持哪些格式？+

支持 CSV 格式导出原始数据表格，也可以生成完整的 SEO 顾问报告（Markdown 格式），包含核心发现、数据证据、影响分析、优先级和行动清单。此外还可以直接生成 Title/Meta 建议、FAQ 内容、Schema 代码、页面模块方案、llms.txt 建议等可直接使用的执行产物。

和 Ahrefs、Semrush 等工具有什么不同？+

传统 SEO 工具给你数据和仪表盘，你需要自己分析和整理。SEO Agent 是 AI 驱动的 SEO 顾问，不仅给数据，还会帮你解读数据、发现机会、评估影响、排优先级，并生成可执行的方案和产物。另外支持 MCP 接入，可以让 AI 工具直接调用 SEO 能力，形成自动化工作流。计费方式也更灵活，按量付费无月费。

支持哪些国家和语言的关键词查询？+

支持全球绝大多数国家和语言，包括美国、英国、加拿大、澳大利亚、德国、法国、日本、韩国、中国等主要市场。查询时可以指定国家代码（如 us、gb、de、jp）和语言代码（如 en、de、ja、zh），获取对应市场的本地化搜索数据。

API Key 的安全性如何保障？+

API Key 使用加密存储，创建时只显示一次完整密钥，后续无法查看。可以为每个 Key 设置不同的接口权限（scope）、消费额度上限和有效期，降低风险。支持随时停用或删除 Key。建议为不同用途创建独立 Key，并定期轮换。

充值后可以退款吗？+

已充值金额原则上不支持退款，但如果遇到服务故障或重大使用问题，可以联系客服协商处理。建议先小额充值试用，确认符合需求后再根据使用量充值。余额长期有效，不会过期清零。

账户管理

个人设置

查看账户余额、历史充值记录和历史消费记录。

账户余额¥0.00

兑换券

API / MCP 使用

在这里创建和管理 API Key。MCP 和 API 共用同一个 Key：Codex 等 AI 工具用它调用 MCP，Python、自动化脚本或内部系统用它调用 API。

0 个 Key

创建前建议 完整 Key 只会显示一次。建议按使用场景单独创建，例如 Codex、客户报表、Python 脚本或内部系统各用一个 Key。

独立站卖家：可以先勾选 MCP、GEO、关键词研究、站内审计和授权数据诊断。
SEO 公司：建议按客户或交付工具分别创建 Key，便于导出记录和排查。
外贸企业：建议给 Codex 和内部脚本分别创建 Key，并设置额度或有效期。

我的 API Keys

Google 数据连接

统一管理 GSC 和 GA4 授权。两项互不强制，需要哪个就连接哪个，连接后可用于网页对话、API 和 MCP 分析。

GSC 搜索表现

关键词曝光、点击、CTR、排名和页面机会。

未连接

授权账号 -

默认站点 -

可用站点 0

GA4 流量质量

渠道、落地页、互动、关键事件和转化承接。

未连接

授权账号 -

默认媒体资源 -

可用媒体资源 0

安全提示：GSC / GA4 只读取你授权的数据。若连接后没有站点或媒体资源，请检查当前 Google 账号权限。Codex 或其他 MCP 客户端仍然只需要 SEO Agent API Key。

发布连接

连接 WordPress 或其他 CMS。建议先发布为草稿，确认内容后再正式发布。

0 个连接

修改密码

历史充值记录

把 SEO Agent 接入 Codex、脚本和内部系统

API / MCP 面向独立站卖家、SEO 公司和外贸企业。你可以用同一个 SEO Agent API Key，把 MCP、API、GEO、关键词研究、竞品、站内审计、已授权 GSC 搜索表现和已授权 GA4 流量质量数据接入 Codex、客户报表、数据库、Python 脚本或内部自动化流程。

先选接入方式

MCP 适合让 AI 工具直接接手连续 SEO 任务；API 适合你的系统、脚本或客户报表稳定拉取标准化数据。两者共用同一个 SEO Agent API Key。

1 MCP：给 AI 工具使用 适合 Codex 等 AI 工具。你用自然语言提出目标，AI 按任务调用 SEO Agent 工具。

2 API：给系统和脚本使用 适合 Python、内部系统、客户报表和批量任务，直接返回标准化数据与本次费用信息。

3 SEO 公司批量交付 把多个客户的关键词、GEO、竞品、GSC 和 GA4 数据接入内部交付流程。

4 独立站和外贸团队 围绕目标市场、产品词和竞品，沉淀可复用的选词、审计和页面优化流程。

能做什么

MCP 接入：让 Codex 等 AI 工具按你的目标调用 SEO Agent，不需要手动记接口路径。
API 接入：把标准化 SEO 数据接入脚本、内部系统、客户报表和自动化流程。
GEO 当前可见度：查询 Google AI Overview 或 ChatGPT 中的当前提及、指标和高频来源。
GEO 趋势监控：查看历史月度趋势、周/月/年变化量以及新增和丢失提及。
GEO 竞争格局：统一对比 2 至 10 个品牌、域名或主题，并查询高频品牌和品牌品类。
GEO 深度审计：检查页面可引用性、AI 爬虫、llms.txt、Schema、品牌平台建议和可选 PDF 报告。
关键词研究：查询搜索量、竞争度、相关词、去重结果和优先级。
深度关键词研究：补全 KD、CPC、趋势、问题词、商业意图、页面类型和关键词分组。
域名个性化关键词机会：结合目标域名已有排名，判断哪些词该优化旧页面、哪些词该新建页面。
域名关键词：查看网站当前已有自然排名关键词和可提升机会。
竞品分析：获取竞品关键词差距、前排同行和竞品关键词策略。
排名查询：查询指定域名在指定关键词下的自然排名。
站内审计：调用内置爬虫检查页面、链接、正文、重复内容和技术问题。
GSC 搜索表现：读取已授权站点的点击、曝光、CTR、平均排名，并输出关键词机会、页面机会、周期摘要、内容衰退、关键词蚕食和优先级行动计划。
GA4 流量质量：读取已授权媒体资源的会话、用户、渠道、落地页、互动率、跳出率和关键事件，并输出落地页机会、渠道诊断和优先级行动计划。
费用预估：正式查询前用 estimate 接口预估最高费用。

如何开始使用

进入"个人资料"的"API / MCP 使用"栏目创建 API Key。独立站卖家可以先勾选 MCP、GEO 和关键词能力；SEO 公司建议按客户或工具分别创建 Key；外贸企业可以给内部脚本和 Codex 分别创建 Key，方便控制权限和额度。

Codex 远程 MCP 接入

新版 Codex 可直接在对话中让 AI 写入远程 MCP 配置，不需要寻找旧版 MCP 按钮或下载本地启动脚本。配置后，Codex 会按任务调用 SEO Agent 能力。

查看 Codex 配置步骤

在 Codex 对话中发送

将 API Key 替换后发给 Codex。它会追加配置，不需要旧版 MCP 按钮。

请在本机 ~/.codex/config.toml 中追加 SEO Agent 远程 MCP，
保留已有配置且不要回显 API Key：

[mcp_servers.seoagent]
enabled = true
url = "https://www.seoagent.vip/mcp"

[mcp_servers.seoagent.http_headers]
Authorization = "Bearer YOUR_SEO_AGENT_API_KEY"

支持的 MCP 工具

seoagent_keyword_research关键词研究。

seoagent_keyword_intelligence深度关键词研究与分组。

seoagent_domain_keyword_opportunities域名个性化关键词机会。

seoagent_domain_keywords域名排名关键词。

seoagent_competitor_gap竞品关键词差距。

seoagent_competitor_keyword_strategy竞品关键词策略。

seoagent_serp_rank_query关键词排名查询。

seoagent_geo_visibilityGEO 可见度。

seoagent_geo_visibility_historyAI 可见度历史趋势。

seoagent_geo_visibility_deltaAI 可见度变化量。

seoagent_geo_visibility_new_lostAI 新增与丢失提及。

seoagent_geo_visibility_comparison最多 10 个目标的 AI 可见度对比。

seoagent_geo_brand_landscapeAI 高频品牌与品牌品类格局。

seoagent_geo_deep_auditGEO 深度审计。

seoagent_site_audit站内审计。

seoagent_gsc_sitesGSC 授权站点。

seoagent_gsc_search_analyticsGSC 搜索表现。

seoagent_gsc_keyword_opportunitiesGSC 关键词机会。

seoagent_gsc_page_opportunitiesGSC 页面机会。

seoagent_gsc_performance_summaryGSC 表现摘要。

seoagent_gsc_content_decayGSC 内容衰退。

seoagent_gsc_cannibalizationGSC 关键词蚕食。

seoagent_gsc_action_planGSC 优先级行动计划。

seoagent_ga4_propertiesGA4 授权媒体资源。

seoagent_ga4_reportGA4 报表数据。

seoagent_ga4_traffic_summaryGA4 流量摘要。

seoagent_ga4_landing_page_opportunitiesGA4 落地页机会。

seoagent_ga4_channel_insightsGA4 渠道质量诊断。

seoagent_ga4_action_planGA4 优先级行动计划。

seoagent_estimate正式查询前预估。

MCP 调用仍然使用同一个 SEO Agent API Key，遵守该 Key 的接口权限、额度、有效期和账户余额规则。未传 location、language 时，MCP 工具默认按 United States / English 查询。

可用接口

先开放高频 SEO 数据能力，后续可根据客户使用情况继续扩展。

接口	用途	必填参数	适合场景
`POST /api/dev/keyword-research`	关键词研究	`keyword` 或 `keywords`	查询种子词搜索量、竞争度、相关词和优先级；批量关键词会先做去重。
`POST /api/dev/keyword-intelligence`	深度关键词研究	`keyword`	补全 KD、CPC、趋势、搜索意图、问题词、商业价值，并返回关键词分组和建议页面类型。
`POST /api/dev/domain-keyword-opportunities`	域名个性化关键词机会	`domain` + `keyword`	结合目标域名已有自然排名和种子词扩展数据，输出机会分、当前排名、匹配页面、难度适配和页面动作建议。
`POST /api/dev/estimate`	费用预估	`endpoint` + `params`	正式查询前预估最高费用，不执行查询，不扣费。
`POST /api/dev/domain-keywords`	域名关键词	`domain`	查看网站当前已有自然排名关键词。
`POST /api/dev/competitor-gap`	竞品差距	`domains` 或 `domain` + `competitor`	找出竞品有排名而自己缺失的关键词机会。
`POST /api/dev/competitor-keyword-strategy`	竞品关键词策略	`keyword`	输入一个种子关键词，返回前排同行、竞品出词、关键词类型、搜索意图、页面类型和策略判断。
`POST /api/dev/serp-rank-query`	排名查询	`keyword` + `domain`	查询目标网站在指定关键词下的排名。
`POST /api/dev/geo-visibility`	GEO 可见度	`topic`、`keyword` 或 `domain`	按品牌、域名或主题查询 Google AI Overview 或 ChatGPT 的当前提及、目标指标、高频来源域名与页面。
`POST /api/dev/geo-visibility-history`	AI 可见度历史趋势	`topic`、`keyword` 或 `domain`	查看历史月度提及与 AI 搜索量，支持指定平台和日期范围。
`POST /api/dev/geo-visibility-delta`	AI 可见度变化量	分析对象 + 可选日期与 `groupRange`	按周、月或年查看提及和 AI 搜索量变化幅度。
`POST /api/dev/geo-visibility-new-lost`	新增与丢失提及	分析对象 + 可选日期与 `groupRange`	分开监控周期内新增和丢失的 AI 提及。
`POST /api/dev/geo-visibility-comparison`	多目标可见度对比	`targets`（2 至 10 个）	统一市场、语言和平台，计算多个对象的相对可见度份额。
`POST /api/dev/geo-brand-landscape`	品牌与品类格局	`topic`、`keyword` 或 `domain`	查询 AI 答案中的高频品牌和品牌品类，支持 Lite 模式。
`POST /api/dev/geo-deep-audit`	GEO 深度审计	`url` 或 `domain`	生成页面表达复核线索，检查公开 AI 爬虫规则、llms.txt 和页面实际 JSON-LD 类型；内部评分仅用于排序复核，可选返回 PDF 报告。
`POST /api/dev/site-audit`	站内审计	`url` 或 `domain`	使用 seoagent 内置爬虫检查页面状态、标题、描述、H1、canonical、内外链、图片 alt、正文相关性、关键词覆盖、重复内容聚类、响应速度、noindex 和结构化数据；可选开启 JS 渲染。
`POST /api/dev/gsc-sites`	GSC 授权站点	无	查询当前 API Key 对应账号已连接的 GSC 站点列表；使用前需要先在个人资料页连接 GSC。
`POST /api/dev/gsc-search-analytics`	GSC 搜索表现	可选 `siteUrl`、`startDate`、`endDate`	读取已授权站点的查询、页面、点击、曝光、CTR 和平均排名；不传 `siteUrl` 时使用个人资料页选择的默认站点。
`POST /api/dev/gsc-keyword-opportunities`	GSC 关键词机会	可选 `siteUrl`、`minImpressions`	基于 GSC 真实搜索表现识别高曝光低点击、排名 8-20 名等 Quick Win 关键词机会。
`POST /api/dev/gsc-page-opportunities`	GSC 页面机会	可选 `siteUrl`、`startDate`、`endDate`	按页面聚合 GSC 查询表现，输出需要优化标题、内容覆盖和内链的页面机会。
`POST /api/dev/gsc-performance-summary`	GSC 表现摘要	可选 `siteUrl`、`startDate`、`endDate`	对比当前周期与上一等长周期，输出点击、曝光、CTR、平均排名变化，以及增长和下降来源。
`POST /api/dev/gsc-content-decay`	GSC 内容衰退	可选 `minPreviousClicks`、`dropRateThreshold`	识别点击或排名明显下滑的页面和查询，用于内容刷新、索引检查和标题复核。
`POST /api/dev/gsc-cannibalization`	GSC 关键词蚕食	可选 `minQueryImpressions`、`minCompetingPages`	发现同一查询由多个页面共同承接的情况，辅助确定主页面、合并、canonical 或内容差异化策略。
`POST /api/dev/gsc-action-plan`	GSC 优先级行动计划	可选 `siteUrl`、`limit`	综合关键词机会、页面机会、内容衰退和关键词蚕食，输出 P0/P1/P2 执行清单和复查指标。
`POST /api/dev/ga4-properties`	GA4 授权媒体资源	无	查询当前 API Key 对应账号已连接的 GA4 媒体资源列表；使用前需要先在个人资料页连接 GA4。
`POST /api/dev/ga4-report`	GA4 报表数据	可选 `propertyId`、`dimensions`、`metrics`	读取已授权媒体资源的标准报表数据，可按落地页、渠道、国家、设备和日期拆解。
`POST /api/dev/ga4-traffic-summary`	GA4 流量摘要	可选 `propertyId`、`startDate`、`endDate`	汇总会话、用户、浏览、关键事件、渠道、设备和国家表现，用于判断流量质量。
`POST /api/dev/ga4-landing-page-opportunities`	GA4 落地页机会	可选 `minSessions`、`rowLimit`、`limit`	识别有访问但互动差、跳出高或关键事件不足的落地页，输出页面优化优先级。
`POST /api/dev/ga4-channel-insights`	GA4 渠道质量诊断	可选 `minSessions`、`limit`	按渠道拆解会话、互动、跳出和关键事件，判断哪些来源需要复核承接质量。
`POST /api/dev/ga4-action-plan`	GA4 优先级行动计划	可选 `propertyId`、`minSessions`、`limit`	综合 GA4 流量摘要、落地页机会和渠道诊断，输出 P0/P1/P2 执行清单和复查指标。
`POST /api/dev/site-audit-async`	站内审计（异步）	`url` 或 `domain`，可选 `callbackUrl`	异步提交站内审计任务，立即返回任务 ID。支持通过 `callbackUrl` 接收完成通知，或通过 `GET /api/dev/site-audit-async/{taskId}` 查询任务状态和结果。
`GET /api/dev/site-audit-async/{taskId}`	查询异步任务状态	路径参数：`taskId`	查询异步审计任务的当前状态（pending / processing / completed / failed）和结果数据。
`POST /api/dev/balance`	账户余额	无	查询当前 API Key 对应的账户余额、可用额度和套餐信息。
`POST /api/dev/usage-records`	消费记录明细	无	查询 API 调用历史消费记录，包含接口类型、调用时间、扣费金额和调用状态。

通用可选参数：location、language、limit、dryRun。批量关键词可传 keywords，相似词选择可传 dedupeMode: "all" 或 dedupeMode: "smart"；域名个性化关键词机会可传 domainKeywordLimit 控制用于匹配的域名排名关键词样本。竞品关键词策略可传 competitorLimit 和 keywordsPerCompetitor，标准版上限分别为 5 和 10；站内审计可传 limit、maxDepth、targetKeywords、duplicateSimilarityThreshold、renderJavascript、renderWaitMs、respectRobots 和 includeSubdomains，不需要国家或语言参数。GSC 接口使用已授权站点和日期范围，可传 siteUrl、startDate、endDate、dimensions、rowLimit、searchType；深度诊断可传 minPreviousClicks、dropRateThreshold、minQueryImpressions 和 minCompetingPages。GA4 接口使用已授权媒体资源，可传 propertyId、startDate、endDate、dimensions、metrics、rowLimit 和 minSessions。

默认市场提醒：如果请求没有传 location 和 language，API / MCP 默认按 United States / English 查询；查询其他国家或语言时请显式传入。

竞品关键词策略分析输出内容

这个接口最多返回 5 个竞品和每个竞品 10 个高搜索量关键词，把前排同行的 SEO 出词方式整理成可继续分析的标准化结构。

返回字段	内容	用途
`competitorCount` / `keywordCount`	实际返回的竞品数量和关键词总数。	用于判断本次数据样本规模；不足上限时按真实数量展示。
`competitors`	前排同行网站列表，包含排名、域名、页面标题和 URL。	用于判断当前关键词下 Google 前排主要由哪些同行占据。
`keywords`	竞品关键词明细，包含竞品域名、关键词、关键词排名、搜索量、预估流量、排名 URL、关键词类型、搜索意图、建议页面类型和机会判断。	用于分析同行靠哪些词、哪些页面类型获取流量，并整理自己的页面规划。
`strategySummary`	SEO Agent 对出词结构和商业机会的归纳。	用于快速判断应该优先补分类页、产品页、场景页、教程页、评测页还是对比页。

字段中的 competitorLimit 和 keywordsPerCompetitor 是查询上限，不代表一定返回满。返回结果已按 SEO Agent 统一字段整理，方便 Codex、Python 或内部系统继续处理。

快速接入

按下面 4 步接入即可：先拿 Key，再决定走 MCP 还是 API，查询前可预估费用，最后读取标准化字段。

1 创建 API Key 进入个人资料页创建 Key。MCP 和 API 共用同一个 Key，权限和额度也共用。

2 选择接入方式 AI 工具优先用 MCP；脚本、报表和内部系统优先用 API。

3 先预估费用 批量查询或新流程上线前，先调用 estimate 检查预计扣费和缓存情况。

4 读取标准字段 从 data 读取结果，从 billing 读取扣费和缓存状态。

最小请求示例

所有接口都使用 POST 请求，并在 Header 中携带自己的 API Key。

curl -X POST https://www.seoagent.vip/api/dev/domain-keyword-opportunities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "keyword": "custom hoodie manufacturer",
    "location": "United States",
    "language": "English",
    "limit": 10
  }'

响应重点看这几项

query本次实际查询参数，方便记录和复查。

data标准化结果，例如 competitors、keywords、pages。

billing本次扣费、预估费用、是否命中缓存。

apiVersion当前 API 响应版本。

{
    "scope": "domain-keyword-opportunities",
    "query": { "domain": "example.com", "keyword": "custom hoodie manufacturer" },
    "data": {
      "keywords": [
        { "keyword": "custom hoodie manufacturer", "priority": "P0", "recommendation": "优化已有页面" }
      ],
      "groups": []
    },
  "billing": {
    "amountCents": 386,
    "cached": false
  }
}

缓存机制与省钱策略

相同参数的请求会自动命中缓存，缓存期内重复调用按缓存复用规则计费。善用缓存可以显著降低批量查询成本。

缓存规则

缓存有效期默认 7 天（604,800 秒），从首次成功调用开始计算。

缓存 Key 组成接口标识 + 请求参数（对象键排序后序列化）。

不参与缓存的参数keywordDeduplication（去重模式不影响缓存命中）。

可缓存的接口所有可缓存的 SEO 数据接口（keyword-research、keyword-intelligence、domain-keyword-opportunities、domain-keywords、competitor-gap、competitor-keyword-strategy、serp-rank-query、geo-visibility、geo-deep-audit、site-audit）。

命中缓存费用按缓存复用规则计费。响应中 billing.cached 为 true，具体金额以 billing.amountCents 为准。

响应中的缓存字段

每个接口响应的 billing 字段都包含缓存状态，可用于判断是否命中以及剩余有效期。

{
  "billing": {
    "cached": true,
    "amountCents": 18,
    "cacheExpiresAt": "2026-07-11T10:30:00.000Z",
    "cacheTtlSeconds": 518400
  }
}

cached是否命中缓存。

cacheExpiresAt缓存过期时间（ISO 8601 格式）。

cacheTtlSeconds当前缓存剩余有效秒数（命中时），或默认缓存有效期（未命中时）。

省钱策略：先 estimate 后批量

批量查询前，先用 /api/dev/estimate 检查每个请求是否已在缓存中，只对未命中的请求执行正式调用。

// 步骤 1：批量预估，筛选未缓存的请求
POST /api/dev/estimate
{ "endpoint": "keyword-research", "params": { "keyword": "seo tools" } }

// 若 cacheHit = false，再执行正式调用
POST /api/dev/keyword-research
{ "keyword": "seo tools" }

estimate 响应缓存字段

{
  "cacheHit": false,
  "cacheTtlSeconds": 604800,
  "estimatedMaxAmountCents": 120
}

cacheHit该参数组合是否已在缓存中。

cacheExpiresAt若已缓存，返回缓存过期时间。

cacheRemainingSeconds若已缓存，返回剩余有效秒数。

estimatedMaxAmountCents预估最高费用，具体扣费以正式调用返回的 billing 为准。

提示：同一 URL / 关键词在缓存期内重复审计或查询，会按缓存复用规则计费，通常比重新查询更省。建议批量任务开始前先用 estimate 全量检查缓存命中情况，规划好调用顺序以最大化利用缓存窗口。

多个国家 / 市场查询

每次 API 请求只对应一个国家和一种语言；如果要查多个国家，请按国家和语言拆成多次请求。

正确写法：每个市场单独请求

POST /api/dev/competitor-keyword-strategy
{
  "keyword": "custom hoodie manufacturer",
  "location": "United States",
  "language": "English"
}

POST /api/dev/competitor-keyword-strategy
{
  "keyword": "custom hoodie manufacturer",
  "location": "Canada",
  "language": "English"
}

POST /api/dev/competitor-keyword-strategy
{
  "keyword": "custom hoodie manufacturer",
  "location": "Australia",
  "language": "English"
}

Python 批量请求示例

import requests

api_key = "YOUR_API_KEY"
url = "https://www.seoagent.vip/api/dev/competitor-keyword-strategy"

markets = [
    {"location": "United States", "language": "English"},
    {"location": "Canada", "language": "English"},
    {"location": "Australia", "language": "English"},
]

for market in markets:
    payload = {
        "keyword": "custom hoodie manufacturer",
        **market
    }
    response = requests.post(
        url,
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload
    )
    print(market["location"], response.json())

不要把多个国家写在同一个 location 字段里，例如 United States, Canada, Australia。多个国家会按多次 API 查询分别计费；如果相同国家、语言、关键词命中缓存，则对应请求按系统规则计费。

费用预估与关键词去重

外部工具可以先预估费用，再决定是否正式查询；批量关键词会自动处理完全重复词，相似词可由客户选择。

费用预估示例

curl -X POST https://www.seoagent.vip/api/dev/estimate -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"endpoint":"keyword-research","params":{"keywords":["Wooden Puzzle","wooden puzzle","wooden puzzles"],"location":"United States","language":"English","limit":10}}'

预估响应

{
  "endpoint": "keyword-research",
  "cacheHit": false,
  "estimatedMaxAmountCents": 80,
  "estimatedMaxAmountYuan": "0.80",
  "billableRequestCount": 2,
  "keywordDeduplication": {
    "exactDuplicateCount": 1,
    "choices": [
      { "id": "all", "label": "全部查询" },
      { "id": "smart", "label": "智能精简" }
    ]
  },
  "note": "这是预计最高费用，实际费用可能因缓存命而减少"
}

接入方可把 keywordDeduplication.choices 渲染为两个按钮；选择"全部查询"传 dedupeMode: "all"，选择"智能精简"传 dedupeMode: "smart"。

使用规则和常见错误

权限错误 scope_not_allowed 表示当前 Key 没有该接口权限。

额度错误 api_key_spend_limit_exceeded 表示该 Key 剩余额度不足。