API 接口文档

通过 API 接口，您可以在自己的应用中集成短网址生成功能。本文档详细说明了接口的使用方法、参数说明和返回格式。

API 端点

POST http://4a.al/api.php

请求方式：POST
内容类型：application/x-www-form-urlencoded 或 application/json

请求参数

参数名 类型 必填 说明
longUrl string 是 需要缩短的原始网址，必须以 http:// 或 https:// 开头
length integer 否 短网址长度，可选值：4、5、6，默认为 4
customCode string 否 自定义短网址后缀，仅支持字母和数字，最长 20 位
expireTime integer 否 有效期（秒），0 表示永久有效，默认为 0
password string 否 访问密码，最长 32 位，留空则无需密码
burnAfterRead integer 否 阅后即焚，1 表示启用，0 表示不启用，默认为 0

请求示例

cURL 示例

curl -X POST http://4a.al/api.php \ -d "longUrl=https://example.com/very/long/url" \ -d "length=4" \ -d "expireTime=86400"

JavaScript (Fetch) 示例

fetch('http://4a.al/api.php', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ 'longUrl': 'https://example.com/very/long/url', 'length': '4', 'expireTime': '86400' }) }) .then(response => response.json()) .then(data => console.log(data));

PHP 示例

$data = [ 'longUrl' => 'https://example.com/very/long/url', 'length' => 4, 'expireTime' => 86400 ]; $ch = curl_init('http://4a.al/api.php'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true);

返回格式

成功响应 (HTTP 200)

{ "success": true, "shortUrl": "http://4a.al//abc1", "shortCode": "abc1", "longUrl": "https://example.com/very/long/url", "expireTime": 1735401600, "hasPassword": false, "burnAfterRead": false }

失败响应 (HTTP 400/500)

{ "success": false, "error": "错误信息描述" }

返回字段说明

字段名 类型 说明
success boolean 请求是否成功
shortUrl string 生成的完整短网址
shortCode string 短网址的唯一标识码
longUrl string 原始长网址
expireTime integer 过期时间戳（Unix timestamp），0 表示永久有效
hasPassword boolean 是否设置了访问密码
burnAfterRead boolean 是否启用阅后即焚
error string 错误信息（仅在失败时返回）

常见错误

错误信息 原因
请提供有效的网址 未提供 longUrl 参数或格式不正确
网址必须以 http:// 或 https:// 开头 网址协议不正确
短网址长度必须为 4、5 或 6 length 参数值不在允许范围内
自定义后缀只能包含字母和数字 customCode 包含非法字符
该自定义后缀已被使用 customCode 已存在于数据库中
该域名在黑名单中 longUrl 的域名在系统黑名单中
生成短网址失败，请重试 无法生成唯一的短网址（极少发生）

使用限制与注意事项

使用提示
  • 建议在调用 API 时添加适当的错误处理机制
  • 自定义后缀具有唯一性，建议先检查是否可用
  • 设置有效期后，链接过期会自动从数据库删除
  • 阅后即焚功能会在用户确认访问后立即删除链接
  • 建议妥善保管设置的访问密码，系统采用 MD5 加密存储
重要提醒

请勿使用 API 生成指向非法内容的短网址，包括但不限于：色情、赌博、诈骗、暴力、侵权等违法违规内容。 系统会记录生成短网址的 IP 地址，发现违规行为将立即封禁并报告相关部门。