API接入文档

API基础地址

所有API请求都基于此地址，通过 act 参数指定具体操作。

请求格式

• 请求方式：GET 或 POST（根据接口而定）
• Content-Type：application/json 或 multipart/form-data
• 字符编码：UTF-8

响应格式

所有API响应均为JSON格式：

{
    "success": true,
    "data": { ... },
    "message": "操作成功"
}

错误响应：

{
    "success": false,
    "error_code": 400,
    "message": "错误信息"
}

HTTP状态码

• 200 - 请求成功
• 400 - 请求参数错误
• 401 - 未登录或登录已过期
• 403 - 无权限访问
• 404 - 资源不存在
• 500 - 服务器内部错误

Cookie认证（推荐）

通过网页登录后，系统会自动设置Cookie，API请求会自动携带Cookie进行身份验证。

API密钥认证

在用户中心 → 图床配置中生成API密钥，然后在请求头中携带：

Authorization: Bearer YOUR_API_KEY

1. 秒传检查

接口：POST /api/check

说明：检查文件是否已存在，支持秒传功能。

{
    "hash": "文件MD5哈希值",
    "filename": "文件名",
    "size": 文件大小（字节）,
    "folder_id": 文件夹ID（可选）
}

{
    "success": true,
    "data": {
        "exists": true,
        "skip_upload": true,
        "file_id": "文件ID"
    }
}

2. 初始化上传任务

接口：POST /api.html?act=upload-init

说明：创建上传任务，获取任务ID和上传配置。

{
    "filename": "文件名",
    "size": 文件大小（字节）,
    "hash": "文件MD5哈希值（可选）",
    "folder_id": 文件夹ID（可选）
}

{
    "success": true,
    "data": {
        "task_id": "任务ID",
        "file_id": "文件ID",
        "chunk_size": 2097152,
        "upload_mode": "direct",
        "upload_urls": [
            {
                "chunk_index": 0,
                "upload_url": "预签名URL",
                "expires_at": 过期时间戳
            }
        ]
    }
}

3. 上传分片（代理模式）

接口：POST /api.html?act=upload-chunk

说明：通过服务器代理上传分片（适用于本地存储）。

4. 获取分片上传URL（R2直传）

接口：GET /api.html?act=upload-chunk-url

说明：获取R2存储的预签名上传URL，客户端直接上传到R2。

5. 合并分片

接口：POST /api.html?act=upload-merge

说明：所有分片上传完成后，合并文件（本地存储需要，R2直传自动合并）。

{
    "task_id": "任务ID"
}

6. 查询上传进度

接口：GET /api/task/list

说明：查询上传任务列表和进度。

1. 文件下载

接口：GET /api.html?act=file-download

参数：id - 文件ID

说明：下载文件，支持断点续传。

2. 获取缩略图

接口：GET /api.html?act=file-thumbnail

参数：

• id - 文件ID
• size - 缩略图尺寸（200或800，默认200）

3. 获取压缩图片

接口：GET /api.html?act=file-compressed

参数：id - 文件ID

说明：获取压缩后的图片，用于预览。

4. 直链访问

接口：GET /directlink/短ID

说明：通过短ID直接访问文件，无需登录。

1. 获取文件列表

接口：GET /api.html?mod=file&act=list

参数：

• page - 页码（默认1）
• page_size - 每页数量（默认20）
• folder_id - 文件夹ID（可选）
• keyword - 搜索关键词（可选）
• type - 文件类型（可选）

2. 获取文件信息

接口：GET /api.html?mod=file&act=info

参数：file_id - 文件ID

3. 重命名文件

接口：POST /api.html?mod=file&act=rename

参数：

• file_id - 文件ID
• new_filename - 新文件名

4. 删除文件

接口：POST /api.html?mod=file&act=delete

参数：file_id - 文件ID

5. 获取外链地址

接口：GET /api.html?mod=file&act=external-link

参数：file_id - 文件ID

说明：获取文件的各种外链格式（Markdown、UBB、HTML等）。

1. 获取文件夹列表

接口：GET /api.html?mod=folder&act=list

参数：parent_id - 父文件夹ID（可选，默认0）

2. 创建文件夹

接口：POST /api.html?mod=folder&act=create

参数：

• folder_name - 文件夹名称
• parent_id - 父文件夹ID（可选，默认0）
• description - 描述（可选）

3. 重命名文件夹

接口：POST /api.html?mod=folder&act=rename

参数：

• folder_id - 文件夹ID
• new_folder_name - 新文件夹名称

4. 删除文件夹

接口：POST /api.html?mod=folder&act=delete

参数：folder_id - 文件夹ID

1. 获取用户信息

接口：GET /api.html?mod=user&act=info

说明：获取当前登录用户的基本信息。

2. 获取用户统计

接口：GET /api.html?mod=user&act=stats

说明：获取用户的存储使用情况、文件数量等统计信息。

3. 更新用户资料

接口：POST /api.html?mod=user&act=update

参数：

• username - 用户名（可选）
• email - 邮箱（可选）
• avatar - 头像URL（可选）

1. 获取VIP方案列表

接口：GET /api.html?act=vip-plans-public

说明：获取所有可用的VIP方案信息（公开接口，无需登录）。

2. 获取VIP权限详情

接口：GET /api.html?act=vip-plan-permissions-public

说明：获取各VIP等级的权限对比（公开接口，无需登录）。

3. 创建VIP订单

接口：POST /api.html?act=vip-order-create

参数：

• plan_id - VIP方案ID
• sku_id - SKU ID（可选）
• payment_method - 支付方式（alipay/wxpay）

4. 查询VIP订单状态

接口：GET /api.html?act=vip-order-status

参数：order_id - 订单ID

JavaScript/jQuery 上传示例

// 初始化上传
$.ajax({
    url: '/api.html?act=upload-init',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        filename: 'example.jpg',
        size: 1024000,
        hash: 'md5_hash_value'
    }),
    success: function(response) {
        if (response.success) {
            var taskId = response.data.task_id;
            // 开始上传分片
            uploadChunks(taskId, response.data.upload_urls);
        }
    }
});

// 上传分片
function uploadChunks(taskId, uploadUrls) {
    uploadUrls.forEach(function(item, index) {
        // 使用预签名URL直接上传到R2
        $.ajax({
            url: item.upload_url,
            method: 'PUT',
            contentType: 'application/octet-stream',
            data: chunkData,
            success: function() {
                // 分片上传成功
            }
        });
    });
}

Python 上传示例

import requests

# 初始化上传
response = requests.post(
    'http://your-domain.com/api.html?act=upload-init',
    json={
        'filename': 'example.jpg',
        'size': 1024000,
        'hash': 'md5_hash_value'
    },
    cookies={'session': 'your_session_cookie'}
)

if response.json()['success']:
    task_data = response.json()['data']
    task_id = task_data['task_id']
    
    # 上传分片
    for chunk_info in task_data['upload_urls']:
        chunk_index = chunk_info['chunk_index']
        upload_url = chunk_info['upload_url']
        
        # 读取分片数据
        with open(f'chunk_{chunk_index}', 'rb') as f:
            chunk_data = f.read()
        
        # 上传到R2
        requests.put(upload_url, data=chunk_data)