API GUIDE

外链 API 参数说明

所有请求均使用 POST + JSON，并需携带 `x-token` 请求头。下面的参数讲解方便你在任何环境中完成集成。

Headers

请求头要求

Header	类型	必填	说明
Content-Type	string	✅	固定为 `application/json`，确保请求体以 JSON 发送。
x-token	string	✅	请求 Token，可在密钥管理或“密钥”页面直接复制。

Body

JSON 请求体字段

`blacklist` 与 `preferredSites` 支持数组或逗号分隔字符串，服务端会自动去重。

字段	类型	必填	说明
email	string	✅	已在后台登记的授权邮箱，服务端会基于邮箱读取调用配置。
text	string	✅	需要进行外链分析的英文文本。
fingerprint	string	—	匿名访客可选指纹，用于限流识别。
blacklist	string[] \| string	—	需要排除的域名，支持数组或逗号分隔字符串。
preferredSites	string[] \| string	—	优先展示的域名列表，支持数组或逗号分隔字符串。

Usage

调用步骤

邮箱与 Token 必须一一对应，否则接口会返回 UNAUTHORIZED。

1
准备邮箱与 Token
在后台添加授权邮箱后，点击“查看密钥”复制对应的 x-token。该 Token 与邮箱绑定，丢失需重新生成。
2
构造请求
请求体包含 email 与 text 等字段，Header 需携带 Content-Type 和 x-token。可在 Postman、curl 或任何 HTTP 客户端中发送。
3
处理响应
成功响应会返回 keywords、usage 以及可选的 linkFetchError；失败时根据 error.code 判定是限流、鉴权还是 AI 服务异常。

Example

完整请求示例

将 `YOUR_DOMAIN`、`YOUR_X_TOKEN` 等占位符替换为实际值即可在 Postman 或 curl 中使用。

POST https://YOUR_DOMAIN/api/external-links
Content-Type: application/json
x-token: YOUR_X_TOKEN

{
  "email": "user@example.com",
  "text": "Search engine optimization is crucial",
  "preferredSites": ["moz.com"],
  "blacklist": ["example.com"]
}

Response

响应字段

当 `success=false` 时，`error` 对象会提供具体的失败原因。

字段	说明
success	布尔值，表示请求是否成功。
data.keywords[].keyword	关键词文本。
data.keywords[].query	建议用于搜索引擎的查询语句。
data.keywords[].reason	推荐该外链的理由。
data.keywords[].link	主推荐链接，可能为空。
data.keywords[].title	主链接标题。
data.keywords[].alternatives.preferred	优先候选链接数组。
data.keywords[].alternatives.regular	常规候选链接数组。
data.usage.promptTokens	提示词 Token 数。
data.usage.completionTokens	生成 Token 数。
data.usage.totalTokens	总 Token 数。
data.linkFetchError	抓取外链时的错误信息，成功时为 `null`。
error	当 `success=false` 时出现，包含 `code`、`message` 与可选 `details`。

请求头要求

JSON 请求体字段

调用步骤

准备邮箱与 Token

构造请求

处理响应

完整请求示例

响应字段