PICFLOW API 参考

PICFLOW API 参考

所有 API 端点返回统一 JSON 格式：

{
  "code": 200,
  "message": "ok",
  "data": { ... }
}

鉴权方式

支持两种鉴权方式：

1. Bearer Token：Authorization: Bearer <token> 头
2. 参数传递：?api_token=<token> 或 POST body 中的 api_token

Token 在数据库中存储为 SHA-256 哈希，不可逆向还原。

---

认证相关

POST /api/auth.php?action=login — 登录

请求：

{
  "username": "string",
  "password": "string",
  "captcha": "string (可选)"
}

响应：

{
  "code": 200,
  "data": {
    "token": "string",
    "user": {
      "id": 1,
      "username": "admin",
      "nickname": "Admin",
      "role": "admin"
    }
  }
}

POST /api/auth.php?action=register — 注册

请求：

{
  "username": "string (3-30 chars)",
  "password": "string (min 6 chars)",
  "email": "string",
  "nickname": "string (可选)",
  "captcha": "string"
}

POST /api/auth.php?action=refresh — 刷新 Token

需要鉴权。旧 Token 失效，返回新 Token。

POST /api/auth.php?action=logout — 登出

需要鉴权。使当前 Token 失效。

---

用户相关

GET /api/user.php — 获取用户信息

鉴权：可选。

获取当前用户或指定用户的个人资料和统计。

响应：

{
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "Admin",
    "email": "admin@example.com",
    "role": "admin",
    "stats": {
      "images_count": 42,
      "likes_count": 156,
      "browse_count": 1024
    }
  }
}

POST /api/user.php — 更新用户信息

需要鉴权。

请求：

{
  "nickname": "string",
  "email": "string",
  "liked_tags": "tag1,tag2,tag3"
}

---

图片相关

GET /api/images.php — 图片列表

鉴权：可选。

参数：

参数	类型	说明
category_id	int	按分类筛选
search	string	按标题搜索
user_id	int	按上传者筛选
page	int	页码，默认 1
per_page	int	每页数量，默认 20，最大 100

响应：

{
  "data": {
    "images": [
      {
        "id": 1,
        "title": "日落风景",
        "category_id": 1,
        "category_name": "scenery",
        "url": "https://example.com/uploads/xxx.jpg",
        "user_id": 1,
        "username": "admin",
        "nickname": "Admin",
        "views_count": 1024,
        "likes_count": 256,
        "tags": ["sunset", "landscape"],
        "is_liked": false,
        "created_at": "2024-01-15 10:30:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}

GET /api/image.php?id=N — 图片详情

鉴权：可选。

响应：返回单张图片的完整信息，含标签、上传者信息、当前用户是否点赞。

POST /api/upload.php — 上传图片

需要鉴权。使用 multipart/form-data。

参数：

参数	类型	说明
image	file	图片文件
title	string	标题
category_id	int	分类 ID

限制：最大 10MB，支持 JPG/PNG/GIF/WebP。

POST /api/images.php?action=delete — 删除图片

需要鉴权（仅上传者或管理员）。

---

互动相关

POST /api/like.php — 点赞/取消点赞

需要鉴权。

请求：

{
  "image_id": 1
}

响应：

{
  "code": 200,
  "data": {
    "is_liked": true,
    "likes_count": 257
  }
}

GET /api/likes.php — 收藏列表

需要鉴权。返回当前用户点赞的所有图片，支持分页。

POST /api/browse.php — 记录浏览

鉴权：可选。支持 navigator.sendBeacon 方式调用。

请求：

{
  "image_id": 1,
  "dwell_time": 5,
  "from_page": "/"
}

GET /api/history.php — 浏览历史

鉴权：可选。返回用户的浏览历史记录。

---

发现相关

GET /api/recommended.php — 智能推荐

鉴权：可选。

• 已登录用户：基于六因子算法个性化推荐
• 游客：返回热门图片

参数：

参数	类型	说明
page	int	页码
per_page	int	每页数量

GET /api/hot.php — 热门图片

参数：

参数	类型	说明
days	int	时间范围（天），默认 7
page	int	页码
per_page	int	每页数量

算法：score = likes_count * 2 + views_count * 0.5

GET /api/latest.php — 最新图片

按时间倒序返回最新上传的图片。

GET /api/categories.php — 分类列表

返回所有分类及其包含的图片数量。

---

版本管理

GET /api/version.php — 检查更新

参数：

参数	类型	说明
platform	string	web / h5 / ios / android / desktop / uniapp

响应：

{
  "data": {
    "version": "1.2.3",
    "build": 123,
    "title": "v1.2.3 更新",
    "description": "修复若干 Bug，优化性能",
    "update_url": "https://example.com/download",
    "is_force": false,
    "is_active": true
  }
}

---

错误码

code	说明
200	成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
429	请求频率限制
500	服务器内部错误