API文档 - 图床

🚀 快速开始

1. 获取API密钥

首先，你需要在 API管理页面创建一个API密钥。

2. 认证方式

所有API请求都需要提供API密钥进行认证。支持两种方式：

方式1：使用请求头（推荐）

X-API-Key: sk_your_api_key_here

方式2：使用URL参数

?api_key=sk_your_api_key_here

⚠️ 安全提示： 请妥善保管你的API密钥，不要在公开场合泄露。建议使用环境变量存储密钥。

📡 API端点

上传单张图片

POST /api/upload

权限要求： upload

请求参数：

参数名	类型	位置	说明
`image`	File	FormData	要上传的图片文件

示例代码（JavaScript）：

const formData = new FormData();
formData.append('image', fileInput.files[0]);

const response = await fetch('http://localhost:3000/api/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_your_api_key_here'
  },
  body: formData
});

const result = await response.json();
console.log(result.data.url); // 图片URL

示例代码（cURL）：

curl -X POST http://localhost:3000/api/upload \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "image=@/path/to/image.jpg"

示例代码（Python）：

import requests

url = "http://localhost:3000/api/upload"
headers = {"X-API-Key": "sk_your_api_key_here"}
files = {"image": open("image.jpg", "rb")}

response = requests.post(url, headers=headers, files=files)
print(response.json()["data"]["url"])

响应示例：

{
  "success": true,
  "message": "上传成功",
  "data": {
    "filename": "1730000000000-123456789.jpg",
    "originalname": "myimage.jpg",
    "size": 245678,
    "url": "http://localhost:3000/uploads/1730000000000-123456789.jpg",
    "uploadTime": "2025-10-30T12:00:00.000Z"
  }
}

上传多张图片

POST /api/upload-multiple

权限要求： upload

请求参数：

参数名	类型	位置	说明
`images`	File[]	FormData	要上传的图片文件数组（最多10张）

示例代码（JavaScript）：

const formData = new FormData();
for (let file of fileInput.files) {
  formData.append('images', file);
}

const response = await fetch('http://localhost:3000/api/upload-multiple', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_your_api_key_here'
  },
  body: formData
});

获取图片列表

GET /api/images

权限要求： read

示例代码：

const response = await fetch('http://localhost:3000/api/images', {
  headers: {
    'X-API-Key': 'sk_your_api_key_here'
  }
});

const result = await response.json();
console.log(result.data); // 图片列表数组

响应示例：

{
  "success": true,
  "data": [
    {
      "filename": "1730000000000-123456789.jpg",
      "size": 245678,
      "url": "http://localhost:3000/uploads/1730000000000-123456789.jpg",
      "uploadTime": "2025-10-30T12:00:00.000Z"
    }
  ]
}

删除图片

DELETE /api/images/:filename

权限要求： delete

URL参数：

参数名	类型	说明
`filename`	String	要删除的图片文件名

示例代码：

const filename = "1730000000000-123456789.jpg";
const response = await fetch(`http://localhost:3000/api/images/${filename}`, {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'sk_your_api_key_here'
  }
});

🔐 权限说明

API密钥支持三种权限：

upload - 上传图片权限
read - 读取图片列表权限
delete - 删除图片权限

创建API密钥时可以选择授予哪些权限。如果请求的操作超出了密钥的权限范围，将返回403错误。

❌ 错误响应

当请求失败时，API会返回错误信息：

{
  "error": "错误描述",
  "message": "详细信息（可选）"
}

常见错误代码：

状态码	说明
`400`	请求参数错误（如缺少文件、文件过大等）
`401`	缺少API密钥
`403`	API密钥无效或权限不足
`404`	资源不存在
`500`	服务器内部错误

📝 限制说明

单个文件最大：10MB
批量上传最多：10张图片
支持格式：JPG、PNG、GIF、WebP、SVG

💡 提示： 建议在生产环境中配置HTTPS，确保API密钥传输安全。

📖 API文档