开发者中心 · API v1

夸克短链 API

通过接口管理短链、替换失效目标、提交自动准备任务、查看审核结果和访问统计。

1. 获取 API 密钥

登录本站原生 RuoYi 后台，在「短链管理 → API 密钥」创建密钥，选择权限及有效期。每个账号最多20个有效密钥，有效期1–365天；密钥只显示一次，可随时撤销。

请求头使用 Authorization: Bearer YOUR_API_KEY。密钥只能访问所选权限与账号当前权限的交集，普通账号只能访问自己的短链和统计。账号停用、权限撤销、密钥到期或撤销后不能继续调用。密钥用于服务端集成，不要放进公开网页或URL。

GET /openapi/v1/links
Authorization: Bearer YOUR_API_KEY

文档任何人可访问，业务接口需要站点账号授权。自动转存/审核任务使用本站配置的夸克账号，仅超级管理员ID1可操作，不会把夸克Cookie或AI上游密钥提供给接入方。

2. 调用示例

将下面的地址替换为您的部署域名；请求API前先在本机安全设置 PAN_API_KEY 环境变量。

curl -H "Authorization: Bearer $PAN_API_KEY" \
  'https://YOUR_HOST/openapi/v1/links'

curl -X POST 'https://YOUR_HOST/openapi/v1/links' \
  -H "Authorization: Bearer $PAN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"code":"my-resource","title":"我的资源","description":"资源说明","target":"https://pan.quark.cn/s/2495e46017e5","enabled":true}'

curl -X POST 'https://YOUR_HOST/openapi/v1/resolve-jobs' \
  -H "Authorization: Bearer $PAN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://pan.quark.cn/s/2495e46017e5"}'

手动创建短链用于明确管理的目标，沿用管理员手动操作规则。处理他人资源时提交自动准备任务：转存完成后立即创建本账号分享，分享就绪5分钟后读取文件名和目录结构并审核。未通过或异常时在同一夸克直链内用公共300MB占位ZIP替换原文件。系统不下载原文件正文。

指定短码创建时，重复POST返回409；PUT完整更新可重试。同一夸克分享码的自动任务去重。不要对结果不明确的创建请求无限重试；先查询短码/任务。

3. 请求与响应

接口前缀 /openapi/v1。成功返回HTTP 200及下列结构；任务提交成功仅代表受理或已有记录，不代表文件已经可公开。

{"code":200,"msg":"成功","data":{...}}
{"code":403,"msg":"API权限不足或账号权限已撤销"}

错误使用对应HTTP状态：400参数、401鉴权、403权限、404不存在/不可访问、409冲突、429限流、500保存异常。CSV导出成功直接返回CSV；错误返回JSON。每个密钥每分钟60次，请求体最多1MiB；触发限流时遵循Retry-After（任务队列繁忙可能没有该头）。自动准备还受每来源每分钟12个新任务和队列上限约束。日期使用UTC，from/to含当日。

原生后台仍使用 /api/pan 和RuoYi登录JWT，其错误通常通过JSON的code返回。外部程序请使用此处的版本化接口及API密钥，不要混用两种鉴权。

4. 自动准备状态

状态	含义
pending / checking / saving / moderating / sharing	处理中，建议2–5秒查询一次
ready	已就绪，可使用短链；reviewDueAt表示后审开始时间
fallback	由原夸克页面显示文件不可用等情况
replacing / replacement_error	审核未通过，正在替换 / 替换失败待重试
expired	原夸克直链中已换为300MB失效提示包
blocked / audit_error	旧任务的审核拒绝 / 异常；仅旧异常任务可用retry
error / disabled	需管理员处理 / 已停用

终态停止轮询。审核结果 manual_review 不是通过。新任务先分享后审，5分钟内资源可能已被访问或转存；审核失败后的替换不能撤回已取得的文件。旧策略的manual_review任务在再次访问短链时会按新策略复核，复用已转存文件；明确风险拒绝不会自动重审。正常工具不会仅因授权信息未知被拦截。仅凭元数据的筛查不能证明正文合规或版权授权。

5. 接口清单与完整字段

点击接口展开参数、请求体和响应定义；完整规范可导入支持OpenAPI的工具。

正在读取接口规范……

共享数据结构（Link / Job / Error）

6. 部署与迁移

接口随本项目程序提供，域名变化无需改客户端以外的接口逻辑。账号及权限在本项目数据库；API密钥只保存摘要，保存在私有数据目录api-keys.json，迁移时随完整数据目录移动。管理员密钥管理接口仅接受RuoYi登录，API密钥无法签发其他密钥。

无需安装RustPan或Codex。夸克和AI上游通过本项目私有配置设置；公开文档和发布包均不包含这些凭据。