本接口文档主要介绍如何使用 API Key 进行短链接的创建与查询（还原）。
## 1. 鉴权认证
所有接口均需要进行身份验证。请在 HTTP 请求头中携带 `X-API-Key`。
- **Header 参数名**: `X-API-Key`
- **内容**: 您的 Access Key (以 `sk_` 开头)
示例：
```bash
curl -H "X-API-Key: sk_YourAccessKey" ...
```
---
## 2. 创建短链接
用于将长链接转换为短链接。
- **接口地址**: `/api/v1/links`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `url` | string | 是 | 原始长链接 (必须以 http:// 或 https:// 开头) |
| `title` | string | 否 | 链接标题/备注 |
| `alias` | string | 否 | 自定义短码 (仅高级套餐支持) |
| `group_id` | integer | 否 | 分组 ID (不传则归入默认分组) |
| `expire_at` | string | 否 | 过期时间 (ISO 8601 格式, 如 `2024-12-31T23:59:59Z`) |
| `access_type` | string | 否 | 访问控制: `open` (公开), `password` (密码保护). 默认为 `open` |
| `password` | string | 否 | 访问密码 (当 `access_type` 为 `password` 时必填) |
### 请求示例
```json
{
"url": "https://www.example.com/very/long/url",
"title": "API测试链接",
"access_type": "open"
}
```
### 响应示例
```json
{
"code": 0,
"msg": "Success",
"data": {
"code": "AbC123",
"url": "https://www.example.com/very/long/url",
"title": "API测试链接",
"access_type": "open",
"created_at": "2024-01-01T12:00:00",
"full_short_url": "https://url.cy/AbC123"
// 注意: full_short_url 可能需根据实际部署自行拼接, API 返回通常包含 code
},
"request_id": "uuid..."
}
```
*(注：实际返回字段以 API 响应为准，核心字段为 `code`)*
---
## 3. 还原短链接 (查询详情)
通过短码查询原始长链接及详细信息。
- **接口地址**: `/api/v1/links/{code}`
- **请求方法**: `GET`
### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `code` | string | 是 | 短链码 (例如 `AbC123`) |
### 响应示例
```json
{
"code": 0,
"msg": "Success",
"data": {
"code": "AbC123",
"alias": "AbC123",
"url": "https://www.example.com/very/long/url",
"title": "API测试链接",
"click": 1024,
"status": "active",
"created_at": "2024-01-01T12:00:00"
}
}
```
其中 `data.url` 即为原始长链接。
---
## 4. 安全检测接口 (收费)
提供 URL 安全性检测服务，每次调用扣除 10 积分。
- **接口地址**: `/api/v1/tools/security-check`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `url` | string | 是 | 需要检测的 URL (域名或完整链接) |
### 请求示例
```bash
curl -X POST "https://url.cy/api/v1/tools/security-check" \
-H "X-API-Key: sk_YourAccessKey" \
-H "Content-Type: application/json" \
-d '{"url": "https://baidu.com"}'
```
### 响应示例
```json
{
"code": 0,
"msg": "ok",
"data": {
"url": "https://baidu.com",
"safe": false,
"reason": "该网站为...",
"points_deducted": 10,
"points_remaining": 80
},
"request_id": "uuid..."
}
```
## 5. 错误码说明
| HTTP 状态码 | code (JSON) | 说明 |
| :--- | :--- | :--- |
| 200 | 0 | 成功 |
| 400 | 400 | 请求参数错误 (如 URL 无效, 短码已存在等) |
| 401 | - | 鉴权失败 (API Key 无效或未提供) |
| 403 | 403 | 权限不足 (如账号被禁用, 或无权使用自定义短码) |
| 404 | 404 | 资源未找到 (如短码不存在) |