API 文档 · KAKAO提链

公开接口

GET/api/health无需认证

健康检查，返回系统配置状态与上游地址。

响应示例

{
  "configured": true,
  "mode": "link",
  "upstreamBaseUrl": "https://kakao.shzyhqn.online"
}

POST/api/cdk/verify限流 20次/分

校验 CDK 兑换码，返回额度信息与可用状态。

请求参数

字段	类型	必填	说明
cdk	string	是	CDK 兑换码

响应示例

{
  "code": "kls_abc123...",
  "totalQuota": 5,
  "usedQuota": 2,
  "remainingQuota": 3,
  "status": "active",
  "valid": true,
  "expiresAt": null
}

POST/api/cdk/merge无需认证

将多张可用 CDK 的剩余额度合并为一张新 CDK。

请求参数

字段	类型	必填	说明
cdks	string[]	是	待合并的 CDK 码数组，至少 2 张

响应示例

{
  "id": "cdk_xxx",
  "code": "kls_merged...",
  "totalQuota": 7,
  "usedQuota": 0,
  "remainingQuota": 7,
  "status": "active"
}

GET/api/cdk/:code/tasks

获取指定 CDK 的任务记录列表。

DELETE/api/cdk/:code/tasks

清除指定 CDK 的任务记录（有在途任务时拒绝）。

POST/api/tasks

创建提链任务。成功后预扣 CDK 额度，任务失败自动退还。

请求参数

字段	类型	必填	说明
cdk	string	是	已校验的 CDK 兑换码
at	string	是	Access Token
session_token	string	否	Session Token（可选）
idempotency_key	string	否	幂等键，防重复提交

响应示例

{
  "job_id": "job_abc123",
  "status": "queued",
  "stage": null,
  "round": null,
  "max_rounds": null,
  "created_at": "2025-01-01T00:00:00+08:00"
}

GET/api/tasks/:job_id

查询任务状态，自动从上游同步最新状态。任务失败/超时/取消时自动退还 CDK 额度。

响应字段

字段	说明
job_id	上游任务编号
status	queued / running / succeeded / failed / timed_out / deleted
stage	当前执行阶段
url	提链成功后的结果链接
error	错误信息（失败时）

DELETE/api/tasks/:job_id

取消任务，同时退还 CDK 额度。需提供 cdk 参数验证权限。

管理后台接口

需通过管理后台登录获取 Cookie 认证（管理员）。

POST/api/admin/login

管理员登录，成功后设置认证 Cookie。

请求参数

字段	类型	必填	说明
password	string	是	后台密码

POST/api/admin/logout

管理员登出，清除认证 Cookie。

GET/api/key-status

查询当前上游 API Key 的状态信息。

GET/api/admin/keys

获取所有 API Key 列表（脱敏显示）。

POST/api/admin/keys

添加 API Key。首个自动设为当前使用。

请求参数

字段	类型	必填	说明
name	string	是	Key 名称
key	string	是	API Key 值

GET/api/admin/keys/:id/reveal

查看 API Key 明文。

POST/api/admin/keys/:id/activate

将指定 API Key 设为当前使用。

DELETE/api/admin/keys/:id

删除 API Key。

GET/api/admin/cdks

获取所有 CDK 列表（含 ID、使用状态、额度详情）。

POST/api/admin/cdks

批量生成 CDK。支持自定义额度、数量、过期时间、备注。

请求参数

字段	类型	必填	说明
quota	int	是	每张 CDK 的额度
count	int	否	生成数量，默认 1，最大 50
expiresAt	string	否	过期时间（ISO 8601）
note	string	否	备注信息

POST/api/admin/cdks/:id/disable

停用指定 CDK。

DELETE/api/admin/cdks/:id

删除指定 CDK。

GET/api/admin/cdks/:id/tasks

获取指定 CDK（按 ID）的任务记录。

第三方对接接口

需在请求头携带 X-API-Key: <INTEGRATION_API_KEY> 认证。

POST/api/v1/cdks/verify

第三方校验 CDK，返回额度信息。

请求参数

字段	类型	必填	说明
cdk	string	是	CDK 兑换码

POST/api/v1/link-jobs

第三方创建提链任务。与 POST /api/tasks 行为一致，但使用 X-API-Key 认证。

请求参数

字段	类型	必填	说明
cdk	string	是	CDK 兑换码
at	string	是	Access Token
session_token	string	否	Session Token

GET/api/v1/link-jobs/:job_id

第三方查询任务状态。

错误码说明

HTTP 状态码	说明
200	请求成功
201	创建成功
202	任务已接受（异步处理中）
204	操作成功，无返回内容
400	请求参数错误
401	未认证或认证失败
403	无权限或 CDK 不可用
404	资源不存在
409	冲突（如 CDK 有在途任务）
429	请求频率超限
502	上游 API 异常
503	服务不可用（如未配置 API Key）