API 文档
完整的 WiZs图床 API 参考文档 - 轻松集成到你的应用
21
图片总数
87
总访问量
50 MB
最大文件
21
上传总数
📚 API 概览
INFO
Base URL
https://pic.us.wizs.vip/api/v1
WiZs图床 API 基于 RESTful 架构设计，支持跨域请求。所有请求和响应均使用 JSON 格式。
通用请求头
| 参数 | 说明 |
|---|---|
| Content-Type | application/json 或 multipart/form-data（上传时） |
| X-API-Key | API 密钥（可选，部分接口需要） |
🔐 认证方式
上传接口需要身份验证。你可以通过以下三种方式进行认证：
方式一：token 参数（推荐，与 EasyImages2.0 兼容）
在 POST 数据中添加 token 参数：
curl -X POST "https://pic.us.wizs.vip/api/v1/upload.php" \
-F "image=@image.png" \
-F "token=your-api-key"
方式二：X-API-Key 请求头
在请求头中添加 X-API-Key：
curl -X POST "https://pic.us.wizs.vip/api/v1/upload.php" \
-H "X-API-Key: your-api-key" \
-F "file=@image.png"
方式三：会话认证（浏览器内使用）
如果用户在浏览器中已登录，图床上传页面会自动使用会话进行认证。
如何获取 API 密钥？
- 登录 WiZs图床 后访问 个人中心
- 在左侧「API 密钥」区块点击「创建密钥」按钮
- 输入密钥名称（如：我的网站）
- 复制生成的 API 密钥
📤 上传文件（图片/视频）
POST
/api/v1/upload.php
上传图片或视频文件到图床
请求参数 (multipart/form-data)
| 参数 | 类型 | 说明 |
|---|---|---|
| image / file 必填 | File | 要上传的文件（字段名支持 image 或 file） |
| token | string | API密钥（可替代 X-API-Key 头） |
支持的图片格式: jpg, jpeg, png, gif, webp, bmp, svg
支持的视频格式: mp4, webm, avi, mov, wmv, mkv, m4v
HTML 表单示例
<form action="https://pic.us.wizs.vip/api/v1/upload.php" method="post" enctype="multipart/form-data">
<input type="file" name="image" accept="image/*" required>
<input type="text" name="token" placeholder="API密钥" required>
<input type="submit" value="上传">
</form>
cURL 示例
# 使用 image 字段名
curl -X POST "https://pic.us.wizs.vip/api/v1/upload.php" \
-F "image=@/path/to/file.jpg" \
-F "token=your-api-key"
# 使用 file 字段名 + X-API-Key 头
curl -X POST "https://pic.us.wizs.vip/api/v1/upload.php" \
-H "X-API-Key: your-api-key" \
-F "file=@/path/to/video.mp4"
JavaScript (jQuery) 示例
var file = document.querySelector('input[type="file"]').files[0];
var token = 'your-api-key';
var formData = new FormData();
formData.append('image', file);
formData.append('token', token);
$.ajax({
url: 'https://pic.us.wizs.vip/api/v1/upload.php',
type: 'POST',
data: formData,
processData: false,
contentType: false,
success: function(response) {
console.log('文件地址:', response.url);
console.log('缩略图:', response.thumb);
console.log('删除链接:', response.del);
},
error: function(xhr, status, error) {
console.error('上传失败:', error);
}
});
Python 示例
import requests
url = 'https://pic.us.wizs.vip/api/v1/upload.php'
token = 'your-api-key'
files = {'image': ('example.jpg', open('example.jpg', 'rb'))}
data = {'token': token}
response = requests.post(url, files=files, data=data)
result = response.json()
if result['result'] == 'success':
print('文件地址:', result['url'])
print('缩略图:', result['thumb'])
print('删除链接:', result['del'])
响应示例（图片）
{
"result": "success",
"code": 200,
"url": "https://pic.us.wizs.vip/uploads/2024/04/10gwv0y.webp",
"srcName": "example.jpg",
"thumb": "https://pic.us.wizs.vip/application/thumb.php?img=/uploads/2024/04/10gwv0y.webp",
"width": 1920,
"height": 1080,
"file_size": 102456,
"del": "https://pic.us.wizs.vip/application/del.php?hash=..."
}
响应示例（视频）
{
"result": "success",
"code": 200,
"url": "https://pic.us.wizs.vip/uploads/videos/2024/04/b2c3d4.mp4",
"srcName": "video.mp4",
"type": "video",
"duration": 125.5,
"duration_formatted": "2:05",
"file_size": 5242880,
"del": "https://pic.us.wizs.vip/application/del.php?hash=..."
}
错误响应
{
"result": "error",
"code": 400,
"error": "No file uploaded"
}
📋 获取文件列表
GET
/api/v1/list.php
获取公开的图片和视频列表
查询参数 (URL Query)
| 参数 | 类型 | 说明 |
|---|---|---|
| page | int | 页码，从 1 开始（默认：1） |
| per_page | int | 每页数量，范围 1-100（默认：20） |
| order_by | string | 排序字段：created_at, views, file_size（默认：created_at） |
| order_dir | string | 排序方向：ASC, DESC（默认：DESC） |
请求示例
GET https://pic.us.wizs.vip/api/v1/list.php?page=1&per_page=10&order_by=created_at&order_dir=DESC
响应示例
{
"success": true,
"data": [
{
"id": 1,
"filename": "a1b2c3d4e5f6.png",
"original_name": "image.png",
"file_path": "2024/04/a1b2c3d4e5f6.png",
"file_size": 102456,
"width": 1920,
"height": 1080,
"views": 42,
"created_at": "2024-04-16 12:00:00"
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5
}
}
🗑️ 删除文件
GET
/application/del.php?hash={hash}
使用上传返回的 hash 删除文件
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| hash 必填 | string | 上传成功后返回的 del 链接中的 hash 参数 |
请求示例 (cURL)
curl "https://pic.us.wizs.vip/application/del.php?hash=bW8vWG4vcG8yM2pLQzRJUGI0dHlTZkN4L2grVmtwUTFhd1A4czJsbHlMST0="
响应示例
{
"result": "success",
"code": 200,
"message": "File deleted successfully"
}
JavaScript 示例
// 使用上传返回的 del 链接直接删除
var delUrl = response.del;
$.getJSON(delUrl, function(data) {
if (data.result == 'success') {
console.log('删除成功');
} else {
console.log('删除失败:', data.error);
}
});
🔄 JSON 文件同步
提供多设备间的JSON文件同步功能，支持版本控制和冲突处理。灵感来源于 Git 的版本管理理念。
核心特性
- 自动版本控制 - 每次更新自动递增版本号
- 冲突检测 - 检测多设备同时修改产生的冲突
- 历史保存 - 所有版本完整保留，可随时回溯
- 设备管理 - 追踪同步设备，记录最后同步时间
- 文件大小限制 - 最大支持 50MB 的 JSON 文件
API 端点概览
| 端点 | 方法 | 说明 |
|---|---|---|
| /api/v1/json/sync.php | POST | 推送/上传JSON文件 |
| /api/v1/json/sync.php | GET | 拉取最新JSON文件 |
| /api/v1/json/history.php | GET | 获取历史版本列表 |
| /api/v1/json/pull.php | GET | 拉取特定版本 |
| /api/v1/json/devices.php | GET | 获取设备列表 |
| /api/v1/json/conflicts.php | GET | 获取冲突列表 |
📤 推送 JSON（上传/更新）
POST
/api/v1/json/sync.php
推送JSON文件到服务器进行同步
请求参数 (application/json 或 multipart/form-data)
| 参数 | 类型 | 说明 |
|---|---|---|
| file_key 必填 | string | 文件唯一标识（如 "user_settings", "app_config"） |
| content 必填 | object/string | JSON内容（对象或字符串） |
| device_id 必填 | string | 设备唯一标识 |
| device_name | string | 设备名称（可选） |
| message | string | 版本描述信息 |
请求示例
curl -X POST "https://pic.us.wizs.vip/api/v1/json/sync.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"file_key": "user_settings",
"content": {"theme": "dark", "language": "zh-CN"},
"device_id": "device_001",
"device_name": "我的手机",
"message": "更新主题设置"
}'
成功响应
{
"success": true,
"version": 3,
"hash": "sha256...",
"conflict": false,
"message": "Version created successfully"
}
冲突响应
{
"success": true,
"version": 5,
"hash": "sha256...",
"conflict": true,
"conflict_type": "divergence",
"message": "Conflict detected and auto-merged",
"conflict_details": {
"local_version": 3,
"remote_version": 4,
"saved_as_version": 5
}
}
📥 拉取 JSON（获取最新）
GET
/api/v1/json/sync.php
从服务器拉取最新或指定版本的JSON文件
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| file_key 必填 | string | 文件唯一标识 |
| since_version | int | 获取此版本之后的更新（用于增量同步） |
请求示例 - 获取最新版本
curl "https://pic.us.wizs.vip/api/v1/json/sync.php?file_key=user_settings" \
-H "X-API-Key: your-api-key"
请求示例 - 获取增量更新
curl "https://pic.us.wizs.vip/api/v1/json/sync.php?file_key=user_settings&since_version=2" \
-H "X-API-Key: your-api-key"
响应示例（最新版本）
{
"success": true,
"file_key": "user_settings",
"current_version": 3,
"content": {
"theme": "dark",
"language": "zh-CN"
},
"hash": "sha256...",
"updated_at": "2024-04-28 12:00:00"
}
响应示例（增量更新）
{
"success": true,
"file_key": "user_settings",
"current_version": 3,
"updates": [
{
"version": 3,
"content": {...},
"hash": "sha256...",
"device_id": "device_002",
"message": "更新配置",
"created_at": "2024-04-28 12:00:00"
}
]
}
📜 历史版本查询
GET
/api/v1/json/history.php
获取JSON文件的所有历史版本
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| file_key 必填 | string | 文件唯一标识 |
| page | int | 页码，默认 1 |
| per_page | int | 每页数量，默认 50，最大 100 |
请求示例
curl "https://pic.us.wizs.vip/api/v1/json/history.php?file_key=user_settings" \
-H "X-API-Key: your-api-key"
响应示例
{
"success": true,
"file_key": "user_settings",
"current_version": 3,
"history": [
{
"version": 3,
"hash": "sha256...",
"parent_hash": "sha256...",
"device_id": "device_001",
"message": "更新主题",
"created_at": "2024-04-28 12:00:00"
},
{
"version": 2,
"hash": "sha256...",
"parent_hash": "sha256...",
"device_id": "device_002",
"message": "",
"created_at": "2024-04-27 10:30:00"
}
],
"pagination": {
"current_page": 1,
"per_page": 50,
"total": 3,
"total_pages": 1
}
}
⚠️ 冲突处理
GET
/api/v1/json/conflicts.php
获取未解决的冲突列表
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| file_key | string | 筛选特定文件的冲突 |
| resolved | int | 0=未解决，1=已解决，默认 0 |
POST
/api/v1/json/conflicts.php
解决冲突
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id 必填 | int | 冲突ID |
| action 必填 | string | resolve_keep_local / resolve_keep_remote / resolve_custom |
| content | object | 当 action=resolve_custom 时需要提供 |
请求示例 - 保留本地版本
curl -X POST "https://pic.us.wizs.vip/api/v1/json/conflicts.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"id": 1, "action": "resolve_keep_local"}'
请求示例 - 自定义合并
curl -X POST "https://pic.us.wizs.vip/api/v1/json/conflicts.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"id": 1,
"action": "resolve_custom",
"content": {"theme": "light", "language": "en-US"}
}'
⚠️ 错误码
所有错误响应都包含 result: "error" 和 code 字段。
| code | error 消息 | 说明 |
|---|---|---|
| 400 | No file uploaded | 未上传文件 |
| 400 | Invalid file type | 不支持的文件类型 |
| 400 | File too large | 文件大小超过限制 |
| 401 | Login required or invalid token | 未提供有效认证 |
| 401 | Invalid API key | API 密钥无效 |
| 403 | Video upload disabled | 视频上传已禁用 |
| 404 | File not found | 文件不存在 |
| 405 | Method not allowed | 不支持的请求方法 |
| 413 | File too large | 请求体过大 |
| 500 | Upload failed | 服务器上传失败 |
💻 代码示例
HTML 表单直接提交
<!-- 最简单的集成方式 -->
<form action="https://pic.us.wizs.vip/api/v1/upload.php" method="post" enctype="multipart/form-data">
<input type="file" name="image" accept="image/*" required>
<input type="text" name="token" placeholder="API密钥" required>
<input type="submit" value="上传">
</form>
JavaScript (jQuery) 完整示例
var file = document.querySelector('input[type="file"]').files[0];
var token = 'your-api-key';
var formData = new FormData();
formData.append('image', file);
formData.append('token', token);
$.ajax({
url: 'https://pic.us.wizs.vip/api/v1/upload.php',
type: 'POST',
data: formData,
processData: false,
contentType: false,
success: function(response) {
if (response.result == 'success') {
console.log('文件地址:', response.url);
console.log('缩略图:', response.thumb);
console.log('删除链接:', response.del);
// 显示图片
$('#preview').attr('src', response.url);
} else {
alert('上传失败:' + response.error);
}
},
error: function(xhr, status, error) {
console.error('上传失败:', error);
}
});
Python
import requests
# 上传图片
upload_url = 'https://pic.us.wizs.vip/api/v1/upload.php'
token = 'your-api-key'
image_path = './example.png'
with open(image_path, 'rb') as f:
files = {'image': (image_path, f)}
data = {'token': token}
response = requests.post(upload_url, files=files, data=data)
result = response.json()
if result['result'] == 'success':
print('文件地址:', result['url'])
print('缩略图:', result['thumb'])
print('删除链接:', result['del'])
else:
print('上传失败:', result['error'])
# 获取文件列表
list_url = 'https://pic.us.wizs.vip/api/v1/list.php'
params = {'page': 1, 'per_page': 10}
response = requests.get(list_url, params=params)
images = response.json()
print('总数:', images['pagination']['total'])