无头 API 接口文档

面向后端、脚本、CLI 等非浏览器客户端，提供与标准 API 相同的业务能力

本文档中「示例」基于 cURL 编写，「实例」基于 JSON（请求/响应数据）编写。

本文档使用 {花括号} 标记占位符，使用时请替换为实际值：

占位符	含义	示例
`{你的域名}`	短链服务部署的域名	`s.example.com`
`{su_你的Key}`	你的 API Key	`su_aBcDeFgH1234`
`{长链接}` / `{目标长链接}`	要缩短的原始 URL	`https://example.com/very/long/path`
`{短链后缀}`	短链路径部分，1–4 位	`a1b2`
`{完整短链地址}`	生成的完整短链 URL	`https://s.example.com/a1b2`
`{ISO 8601 过期时间}`	链接过期时间，ISO 8601 格式	`2026-05-20T12:00:00+08:00`
`{永久/临时短链当前数量}`	当前已有的短链数量	`12`
`{永久/临时短链配额上限}`	配额上限值	`9999`

一、与标准 API 的区别

项目	标准 API	无头 API
路径前缀	`/api/`	`/headless/api/`
认证方式	POST：请求体 `key`；GET：`X-Token` 头	统一使用 `X-Headless-Token` 请求头
CORS	允许配置域名跨域	不设置 CORS
错误格式	`{ "error": "中文描述" }`	`{ "error": "英文代码", "message": "中文描述" }`

二、Key 认证

所有无头接口统一通过 X-Headless-Token 请求头传递 API Key：

X-Headless-Token: {su_你的Key}

数据文件不可访问时（优先于认证检查）：

HTTP 430
{ "error": "data_inaccessible", "message": "数据不可访问：keys.json" }

认证失败时返回：

HTTP 406
{ "error": "missing_key", "message": "缺少密钥" }

HTTP 406
{ "error": "invalid_key", "message": "密钥失效或不正确" }

三、标准接口详情

1. 创建短链

POST /headless/api/create
Content-Type: application/json
X-Headless-Token: {su_你的Key}

请求体与标准创建接口一致（url、ttl、code），无需包含 key 字段。

Prop

Type

永久短链：

{ "short_url": "https://{你的域名}/{短链后缀}" }

临时短链：

{ "short_url": "https://{你的域名}/{短链后缀}", "exp": "{ISO 8601 过期时间}" }

Prop

Type

状态码	error 代码	message 消息	原因
`400`	`missing_url`	缺少目标链接	`url` 字段缺失
`400`	`invalid_url`	目标链接无效	URL 格式不合法
`400`	`ttl_exceeded`	TTL 超限	`ttl` 超出范围
`400`	`invalid_code`	后缀格式错误	`code` 格式不合法
`400`	`reserved_code`	保留字	`code` 是系统保留字
`409`	`conflict`	已占用	自定义 `code` 与已有短链冲突
`429`	`quota_exceeded`	已达上限	配额不足
`430`	`data_inaccessible`	数据不可访问：{文件名}	数据文件权限错误
`500`	`gen_failed`	无法生成后缀	后缀生成失败
`500`	`write_failed`	服务器内部错误	数据写入验证失败（v2.1 safe_write 保护）

创建永久短链

curl -X POST https://{你的域名}/headless/api/create \
  -H "Content-Type: application/json" \
  -H "X-Headless-Token: {su_你的Key}" \
  -d '{"url":"{长链接}","ttl":0}'

创建 30 分钟临时短链

curl -X POST https://{你的域名}/headless/api/create \
  -H "Content-Type: application/json" \
  -H "X-Headless-Token: {su_你的Key}" \
  -d '{"url":"{长链接}","ttl":1800}'

请求 → 创建永久短链（自动生成后缀）

{ "url": "https://example.com/some/long/path", "ttl": 0 }

响应 ← 200

{ "short_url": "https://s.example.com/a3k9" }

请求 → 创建 30 分钟临时短链（自定义后缀）

{ "url": "https://example.com/page", "ttl": 1800, "code": "demo" }

响应 ← 200

{ "short_url": "https://s.example.com/demo", "exp": "2026-05-20T12:30:00+08:00" }

响应 ← 409 冲突

{ "error": "conflict", "message": "已占用" }

响应 ← 429 配额不足

{ "error": "quota_exceeded", "message": "已达上限" }

2. 删除短链

POST /headless/api/delete
Content-Type: application/json
X-Headless-Token: {su_你的Key}

{ "code": "{短链后缀}" }

Prop

Type

{ "ok": true }

状态码	error 代码	message 消息	原因
`400`	`missing_code`	缺少短链后缀	`code` 字段缺失
`404`	`not_found`	该短链不存在	`code` 未找到
`430`	`data_inaccessible`	数据不可访问：{文件名}	数据文件权限错误
`500`	`write_failed`	服务器内部错误	数据写入验证失败（v2.1 safe_write 保护）

删除指定短链

curl -X POST https://{你的域名}/headless/api/delete \
  -H "Content-Type: application/json" \
  -H "X-Headless-Token: {su_你的Key}" \
  -d '{"code":"{短链后缀}"}'

请求 → 删除短链

{ "code": "demo" }

响应 ← 200

{ "ok": true }

响应 ← 404 不存在

{ "error": "not_found", "message": "该短链不存在" }

3. 查询短链列表

GET /headless/api/list
X-Headless-Token: {su_你的Key}

{
  "permanent": [
    {
      "id":   "{短链后缀}",
      "url":  "{目标长链接}",
      "lurl": "{完整短链地址}",
      "exp":  "permanent"
    }
  ],
  "temporary": [
    {
      "id":   "{短链后缀}",
      "url":  "{目标长链接}",
      "lurl": "{完整短链地址}",
      "exp":  "{ISO 8601 过期时间}"
    }
  ]
}

响应格式与标准列表接口完全一致。

Prop

Type

查询所有短链

curl https://{你的域名}/headless/api/list \
  -H "X-Headless-Token: {su_你的Key}"

响应 ← 200（含永久和临时短链）

{
  "permanent": [
    {
      "id":   "a3k9",
      "url":  "https://example.com/docs",
      "lurl": "https://s.example.com/a3k9",
      "exp":  "permanent"
    },
    {
      "id":   "home",
      "url":  "https://example.com/",
      "lurl": "https://s.example.com/home",
      "exp":  "permanent"
    }
  ],
  "temporary": [
    {
      "id":   "demo",
      "url":  "https://example.com/promo",
      "lurl": "https://s.example.com/demo",
      "exp":  "2026-05-20T12:30:00+08:00"
    }
  ]
}

4. 查询配额状态

GET /headless/api/stat
X-Headless-Token: {su_你的Key}

{
  "perm_count":  {永久短链当前数量},
  "temp_count":  {临时短链当前数量},
  "perm_limit":  {永久短链配额上限},
  "temp_limit":  {临时短链配额上限}
}

响应格式与标准配额接口完全一致。

Prop

Type

查询配额

curl https://{你的域名}/headless/api/stat \
  -H "X-Headless-Token: {su_你的Key}"

响应 ← 200

{
  "perm_count":  2,
  "temp_count":  1,
  "perm_limit":  9999,
  "temp_limit":  9999
}

含义：当前有 2 条永久短链、1 条临时短链，配额上限各 9999 条。

5. 查询单条短链

此接口仅在无头模式下提供，标准 API 不包含此功能。

GET /headless/api/get/{code}
X-Headless-Token: {su_你的Key}

{code} 为短链后缀，1–4 位。

{
  "id":   "{短链后缀}",
  "url":  "{目标长链接}",
  "lurl": "{完整短链地址}",
  "exp":  "permanent"
}

Prop

Type

{
  "id":   "{短链后缀}",
  "url":  "{目标长链接}",
  "lurl": "{完整短链地址}",
  "exp":  "{ISO 8601 过期时间}"
}

若已过期则返回 404，见错误码。

Prop

Type

状态码	error 代码	message 消息	原因
`400`	`missing_code`	缺少短链后缀	路径中未提供 `code`
`404`	`not_found`	该短链不存在	`code` 未找到
`404`	`expired`	该短链已过期	临时短链已过期
`430`	`data_inaccessible`	数据不可访问：{文件名}	数据文件权限错误

查询单条短链

curl https://{你的域名}/headless/api/get/{短链后缀} \
  -H "X-Headless-Token: {su_你的Key}"

响应 ← 200（永久短链）

{
  "id":   "a3k9",
  "url":  "https://example.com/docs",
  "lurl": "https://s.example.com/a3k9",
  "exp":  "permanent"
}

响应 ← 200（临时短链）

{
  "id":   "demo",
  "url":  "https://example.com/promo",
  "lurl": "https://s.example.com/demo",
  "exp":  "2026-05-20T12:30:00+08:00"
}

响应 ← 404 已过期

{ "error": "expired", "message": "该短链已过期" }

声明

作者：圣堂之魂；发布于：2026-05-19；许可协议：CC BY-NC-SA 4.0

无头 API 接口文档

跳转

占位符约定

一、与标准 API 的区别

二、Key 认证

三、标准接口详情

1. 创建短链

2. 删除短链

3. 查询短链列表

4. 查询配额状态

5. 查询单条短链

声明

本页目录