API 快速入门：获取 Token 并发起第一次调用
从获取 API Token 到成功生成第一条短链，5 分钟完成接入。
1. 接入前须知
小南短链开放 API 的 Base URL 为 https://open.xnanlink.com。所有接口均通过 HTTP 协议调用，返回统一的 JSON 格式，任何语言（Java、Python、Node.js、Go、PHP 等）均可直接对接。
统一响应结构包含四个字段：
| 字段 | 类型 | 说明 |
|---|---|---|
code |
string | 状态码，OK 表示成功 |
message |
string | 提示信息，失败时包含具体错误原因 |
data |
any | 业务数据，类型随接口不同而变化（布尔值、对象或数组） |
success |
boolean | 请求是否成功 |
2. 获取 API Token
API Token 是调用接口的唯一凭证。登录小南短链后台，依次进入「个人中心 → API 管理」，点击「生成 Token」即可获得你的专属 Token。
关于 Token 的保管：
- Token 等同于账号的操作权限，请存放在服务端环境变量或密钥管理服务中，切勿写入前端代码或提交到公开代码仓库
- 如怀疑 Token 泄露，请立即在「API 管理」页面重置 Token，旧 Token 将即时失效
- API Token 与 MCP Key 相互独立：Token 用于 REST 接口调用，MCP Key 用于 AI 客户端接入，两者不能混用
3. 鉴权方式
所有接口通过请求头鉴权，在每次请求中携带 Token: YOUR_TOKEN 即可。POST 请求还需携带 Content-Type: application/json：
Token: YOUR_TOKEN Content-Type: application/json
4. 第一次调用：快捷生成短链
4.1 请求示例
最简单的接口是 POST /api/link/quick-create（快捷生成短链），只需两个必填参数：sourceLink（原始链接）和 domain（域名），其余参数使用默认值。
打开终端，把下面命令中的 YOUR_TOKEN 替换为你的 Token 后执行：
curl -X POST 'https://open.xnanlink.com/api/link/quick-create' \
-H 'Content-Type: application/json' \
-H 'Token: YOUR_TOKEN' \
-d '{
"sourceLink": "https://www.example.com/page?id=123",
"domain": "lxs.la"
}'
4.2 响应解读
调用成功时返回：
{
"code": "OK",
"message": "成功",
"data": true,
"success": true
}
code 为 OK 且 success 为 true 表示短链创建成功，此时登录后台或调用短链列表接口即可看到新生成的短链。如果调用失败，可对照下表排查：
| 常见错误 | 可能原因 | 排查方法 |
|---|---|---|
| Token 无效 / 鉴权失败 | Token 拼写错误、已重置或请求头名称不对 | 确认请求头为 Token，去后台核对当前有效 Token |
| 参数缺失 | 缺少 sourceLink 或 domain，或 JSON 格式错误 | 检查请求体是否为合法 JSON，必填字段是否齐全 |
| 额度不足 | 当日 / 当期套餐调用次数已用完 | 在后台查看额度使用情况，升级套餐或次日再试 |
5. 进阶：完整参数生成短链
如果需要更精细的控制，可以使用 POST /api/link/create（生成短链），它在 quick-create 的基础上支持以下可选参数：
visitCode：自定义访问码（短链后缀），不传则随机生成rules：路由规则列表，按设备、地区等条件分流到不同目标 URLexpireDate：过期时间，不传则按套餐默认jumpType：跳转类型，仅微信外链有效
curl -X POST 'https://open.xnanlink.com/api/link/create' \
-H 'Content-Type: application/json' \
-H 'Token: YOUR_TOKEN' \
-d '{
"sourceLink": "https://www.example.com/page?id=123",
"domain": "lxs.la",
"linkType": "COMMON",
"visitCode": "mycode"
}'
使用自定义访问码前，建议先调用 GET /api/link/check-visit-code 检查后缀在目标域名下是否可用（返回 data: false 表示可用，true 表示已被占用）：
curl -X GET 'https://open.xnanlink.com/api/link/check-visit-code?domain=lxs.la&visitCode=mycode' \ -H 'Token: YOUR_TOKEN'
6. 调用额度与套餐
API 调用次数与你的账号套餐挂钩：免费版每日有限额调用，适合开发调试与轻度使用；付费版（专业版及以上）调用次数无限制，并支持访问统计等完整能力。
需要注意的是，API 与 MCP 共享同一套套餐额度：无论通过 REST 接口还是 AI 客户端的 MCP 工具发起调用，都会计入同一额度池。
7. 常见问题
Token，值为你的 API Token，即 Token: YOUR_TOKEN。不支持放在 URL 参数或请求体中传递。
8. 下一步
完成第一次调用后，可以继续阅读完整的接口参考文档：
- API 接口参考：短链管理——创建、更新、状态管理与删除接口详解
- API 接口参考：查询、批量导入与访问统计——列表查询、Excel/JSON 批量导入与访问记录接口