API 文档
面向智能体（Agent）与开发者：所有响应都是 JSON，计费、幂等、错误码都写在响应里。
本页的端点参考由线上的 /api/openapi.json 运行时渲染——
规格改了这里就改，不会出现「文档是旧版本」这种不报错的错。
5 分钟上手
- 拿 key：当前为定向开通，发邮件到 service@saler.ai；开通后你会拿到一个
saler_…形式的租户密钥。 - 先免费试一下：
GET /api/v1/diagnose?domain=example.com不需要 key，可直接验证网络与响应形状。 - 先问价，再下单：每个扣费端点都有对应的报价端点（
*_estimate），报价不扣费，并同时返回售价与上游成本。 - 正式调用：带上
authorization: Bearer $SALER_API_KEY，建议同时传idempotency_key（重试不重复扣费）。
免费试调（无需 key）
curl 'https://api.saler.ai/api/v1/diagnose?domain=example.com'
鉴权与响应封套
- 租户密钥走 HTTP 头：
authorization: Bearer $SALER_API_KEY。 - 成功统一封套：
{ "code": "OK", "data": <负载>, "meta": { "locale": "…" } }。 - 失败同形状：
{ "code": …, "message": …, "retryable": …, "action": … }。 - 公开端点（
/api/v1/diagnose、/api/v1/openapi.json）无需 key，但带配额。
错误与「404 双语义」
404 有两种含义，判据在 message 前缀而不在状态码：
路径不存在：… 表示路由没注册（客户端写错地址或该版本未部署）；
未找到：… 表示路由存在、但对象不存在（如品牌未授权/未登记）。
把两者都当成「地址写错」会误诊——前者改地址，后者查授权。
401 也有两种语境：响应要求租户 key 说明路由已注册；要求 ADMIN_TOKEN 说明该路径属于管理面。
定价速查
| 能力 | 档位 | 售价 | 说明 |
|---|---|---|---|
| 品牌 AI 可见度（GEO） | 30 天 | $2.70 | ≈ $0.09 / 品牌 / 天 |
| 90 天 | $8.10 | 同一口径 | |
| 365 天 | $32.70 | 日均价不随窗口下降 | |
| SEO 研究（按 kind） | keywords | $4.00 | 200 词上限，含 AI 搜索量与难度 |
| competitor_gap | $0.50 | 最多 10 个竞品域 | |
| domain_overview | $0.60 | 最多 10 个域 | |
| backlinks | $0.40 | 概览 + 锚文本 + 引用域 | |
| 技术审计（Lighthouse） | 每次 | $0.02 | 2 小时未交付自动全额退款 |
| GEO 诊断 | — | 免费 | 公开端点，带配额 |
报价端点会同时给出售价与上游成本预估（upstream_cost_micro）。
自有数据（GEO 时序）的上游成本为 0，也如实披露为 0——不假装「免费」，也不把零成本包装成有成本。
口径披露（会影响你怎么解读数据）
- 空档日不是 0：某天没采样时可见度为
null，绝不用 0 填补（0 会被读成「掉了」）。 - 口径带版本号：可见度得分口径为
vs2（分母排除无 AI 概览的查询）。跨口径的报告不能直接比较。 - 样本不进交付物但会披露：
is_sample的数据行参与计数、但不作为结论交付。 - 能生成 ≠ 能交付：若窗口内有效样本不足，响应会给出覆盖天数与空档天数，趋势字段为
N/A而不是编一个数。
端点参考
以下由线上 OpenAPI 规格实时渲染；想给智能体直接读机器规格，用 /api/openapi.json。
正在加载接口规格…
有问题或要开通：service@saler.ai。 条款见 服务条款（当前为草稿，待律师审订）。