开发文档 · 短链接开放 API

本页面向接入方开发者，介绍面向用户的短链接开放接口。

Base URL	以站点地址为准（如 `https://your-domain.com`）
数据格式	请求与响应均为 `application/json`，编码 UTF-8
时间戳	入参使用毫秒时间戳，返回的 `created_at` 为毫秒
限流	基于账号与接口的频率限制，超限返回 `429`

在「API 对接」页创建 API 密钥，并在请求头携带：

Authorization: Bearer {api_key}

每账号最多 3 个密钥，支持重置与删除；旧密钥重置后立即失效。

成功响应统一含 success: true；失败返回 { "error": "错误描述" }。分页接口额外返回 total / page / limit。

HTTP	含义	说明
`200`	成功	正常返回
`400`	参数错误	URL 非法、分流目标不足 2 个或超过 5 个等
`401`	未认证	缺少或过期 API Key
`403`	受限	套餐不支持分流（`need_upgrade`）、链接被拒绝等
`404`	不存在	链接不存在
`409`	冲突	长链接重复、后缀被占用
`429`	请求过快	触发限流

# 创建一条短链接
curl -X POST "{BASE}/api/links" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/landing","agree":true}'

创建接口 agree 必须为 true（内容合规承诺），否则返回 403。

POST/api/links需认证

字段	类型	必填	说明
`url`	string	是	目标网址（完整 URL）
`agree`	boolean	是	内容合规承诺，必须为 `true`
`suffix`	string	否	自定义后缀，至少 6 位（字母数字及 `-` `_`）
`domain`	string	否	使用域名（系统域名或已验证的专属域名）
`title`	string	否	标题；留空则回填自动审核抓取的页面标题
`password`	string	否	访问密码
`maxClicks`	number	否	最大点击次数，`0` = 不限
`expiresAt`	number	否	过期时间（毫秒时间戳）
`split_mode`	string	否	分流模式（见「分流模式」，仅高级版及以上）
`targets`	array	否	分流目标数组（2~5 个，仅高级版及以上）

{
  "url": "https://example.com/very/long/url",
  "agree": true,
  "suffix": "my-link",
  "domain": "link.example.com",
  "title": "链接标题",
  "password": "1234",
  "maxClicks": 100,
  "expiresAt": 1700000000
}

{
  "success": true,
  "data": {
    "short_code": "4PYY5V",
    "short_url": "https://link.example.com/4PYY5V",
    "long_url": "https://example.com/very/long/url",
    "review_status": "auto_approved"
  }
}

POST/api/links/batch需认证

字段	类型	说明
`urls`	array	元素可为字符串或 `{ url, suffix, title }` 对象
`domain`	string	统一域名（可选）
`title`	string	统一标题（可选）

POST /api/links/batch
{
  "urls": ["https://a.com", "https://b.com"],
  "domain": "link.example.com"
}

单次上限 50 条，不支持分流模式。

GET/api/links需认证

Query	说明
`page`	页码，默认 1
`limit`	每页条数，默认 20
`search`	按长链接 / 短码 / 标题搜索

GET /api/links?page=1&limit=20&search=keyword

GET/api/links/:code需认证

返回链接详情、访问统计与分流目标：

{
  "success": true,
  "data": {
    "short_code": "4PYY5V",
    "split_mode": "round_robin",
    "targets": [
      { "id": 1, "url": "https://example.com/t1", "quota": 0, "used_count": 3, "review_status": "auto_approved" }
    ],
    "daily_clicks": [], "top_referrers": [], "browser_stats": [], "device_stats": [], "os_stats": []
  }
}

PUT/api/links/:code需认证

可修改 title / maxClicks / password / expiresAt / split_mode / targets；不可修改 url / short_code / domain。

{
  "title": "新标题",
  "split_mode": "by_quota",
  "targets": [
    { "url": "https://example.com/t1", "quota": 500 },
    { "url": "https://example.com/t2", "quota": 500 }
  ]
}

传入 targets 为全量替换：相同 URL 保留审核状态，新 URL 需重新审核，缺席目标被删除；split_mode=single 且 targets: [] 可清空分流。

DELETE/api/links/:code需认证

删除指定短码的链接及其点击记录。

高级版及以上可将一条短链配置最多 5 个跳转目标，访问时按所选模式自动分流。

split_mode	名称	行为
`single`	单链接（默认）	始终跳转主链接
`round_robin`	轮询	在已通过审核的目标间依次轮换
`random`	随机	在已通过审核的目标中随机选择
`by_quota`	按余量	选择剩余配额（quota - used_count）最大者，quota=0 视为不限

POST /api/links
{
  "url": "https://example.com/t1",
  "agree": true,
  "split_mode": "round_robin",
  "targets": [
    { "url": "https://example.com/t1", "quota": 0 },
    { "url": "https://example.com/t2", "quota": 0 }
  ]
}

仅从已通过审核的目标中分流；任一目标被拒绝则整体拒绝，任一目标待审核则整体提示「审核中」。目标数量为 2~5 个。

针对设置了 maxClicks 的短链，当点击量达到上限后按天递进：

阶段	动作
第 1 天	发送超量提醒邮件，链接仍可访问
第 2 天	再次发送提醒邮件
第 3 天	链接转入「超出点击次数」状态并暂停跳转

升级套餐后可解除限制、恢复正常访问。

链接对象（部分）

字段	说明
`short_code`	短码
`short_url`	完整短链地址
`long_url`	目标网址
`split_mode`	分流模式
`review_status`	`auto_approved` / `pending` / `approved` / `rejected`

分流目标对象

字段	说明
`url`	目标跳转网址
`quota`	配额上限（0 = 不限，仅按余量模式使用）
`used_count`	已使用次数
`review_status`	该目标的审核状态

短链接开放 API

概述

认证

响应与错误码

快速开始

短链接接口

创建短链接

批量创建

链接列表

链接详情

编辑短链接

删除短链接

分流模式

点击超量提醒

字段说明

链接对象（部分）

分流目标对象