API 概述

声量开放 API 让你把 GEO 监测和软文发稿接进自己的系统 —— 在你的后台里发起检测、 取回品牌在各个 AI 平台的可见度数据、提交发稿工单，不必每次都打开控制台操作。

API 和控制台是同一个账号、同一份数据：用 API 跑出来的检测，在控制台的 GEO 页面里 看得到；在控制台配好的品牌和意图词，API 也读得到。配额也共用一份，不另外计费。

第一次接入请看快速开始，五步跑通一轮检测。

服务地址

https://shengliang.cn

请求与响应一律 UTF-8 JSON。机器可读的接口定义见 openapi.json，可直接导入 Postman / Swagger UI 或用来生成客户端。

认证

每个请求都要在 Header 里带上 API Key：

Authorization: Bearer sk-xxxxxxxxxxxx

Key 在控制台「API Key」页创建。明文只在创建时显示一次，请当场保存 —— 我们只存 哈希值，无法帮你找回，丢了只能吊销重建。

Key 等同于你的账号凭证，不要提交到代码仓库，也不要放进浏览器或移动端代码里。

调 GET /openapi/v1/me 可以验证一把 Key 是否可用、它有哪些权限。

权限范围

创建 Key 时可以限定它能做什么。

也可以用通配符：* 代表全部，geo:* 代表 GEO 域内全部（不跨域）。控制台新建 Key 时 默认给全部权限，切到「自定义」可逐项勾选。

权限在创建后不可修改，需要调整请重新创建一把。给第三方或自动化脚本用的 Key， 建议只勾选它实际需要的权限 —— 尤其 geo:run 和 media:order 会消耗你的配额和点数。

权限不足时返回 1002，detail.missing 会列出缺少的 scope：

{ "code": 1002, "msg": "API Key 缺少权限：geo:run",
  "detail": { "required": ["geo:run"], "missing": ["geo:run"] } }

可访问的数据范围

API 只能访问个人空间的数据。团队空间里的品牌、意图词、发稿记录通过 API 读不到， 即使你是该团队成员。有团队场景的需求请联系我们。

响应结构

成功和失败用同一个结构，不需要写两套解析：

{ "code": 0, "msg": "ok", "data": { } }

同一个 HTTP 状态码可能对应多种原因，例如 429 既可能是请求太频繁（等几秒），也可能是 当日检测次数用完（等到明天）。请根据 code 分支处理，完整码表与排查步骤见 错误码说明。

端点总览

路径均省略了 /openapi/v1 前缀。

配额与限制

API 与控制台共用同一套配额，具体额度按订阅套餐：

几点说明：

• 可检测平台：传入超出档位的平台会被忽略，不会报错。当前可用的平台列表见 结果概览的返回。
• 意图词上限限的是同时「启用」的条数，不限总数。一轮检测的问答次数 = 启用意图词数 × 平台数，这也是上限存在的原因。超限时启用操作返回 2002。
• 每日检测次数按北京时间自然日计算，00:00 重置；只统计你主动触发的（含 API 调用）， 套餐内的定时监测不占用。
• 最小间隔是为了保证数据质量：AI 平台的回答在短时间内高度相似，间隔太近跑两次 拿到的几乎是同一份答案，反而会把趋势曲线压平。
• 发布点数按订阅周期发放，每家媒体消耗多少与其价格挂钩。撤回待审核的工单会退回点数。

请求频率

除业务配额外，还按 Key 做频率限制。超限返回 2001，detail.retry_after 给出建议 等待秒数。轮询监测进度建议 30 秒一次 —— 一轮检测以分钟计，更密的轮询拿不到更多 信息，只会更快触发限制。

接入前值得知道

下一步

• 快速开始 —— 五步跑通第一轮 GEO 监测
• 错误码说明 —— 完整错误码表与排查步骤
• 发起 GEO 监测 —— 最常用的一个端点