接口说明

Picmo图床 RESTful API，基于 HTTP 协议，以 JSON 格式交互。

接口地址

所有接口的基础 URL 为：

// 所有接口请求都以此为前缀（本站地址）
https://up.picmo.cn/api/v2

说明：代码示例中的 https://your-domain.com 为占位域名，请替换为本站实际地址；浏览器端可直接用 location.origin + '/api/v2' 取得当前站点的接口前缀。

验证方式

接口采用 Bearer Token 方式验证。登录后在用户中心 API Token 页面创建令牌，然后在请求头中携带：

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxx

说明：未携带 Authorization 请求上传接口时，将视为游客上传（如开放游客上传）。Token 等同于账户凭证，请妥善保管。

公共请求头

字段	类型	必填	说明
`Authorization`	String	*	Bearer Token 授权
`Accept`	String	*	固定为 `application/json`
`Content-Type`	String	否	POST 请求根据参数类型设置，上传文件用 `multipart/form-data`

公共响应头

字段	说明
`X-RateLimit-Limit`	当前客户端每分钟请求配额
`X-RateLimit-Remaining`	当前客户端剩余请求配额

响应状态码

状态码	说明
`200`	请求成功
`401`	未登录或授权失败（Token 无效）
`403`	没有该接口权限或接口已被管理员关闭
`404`	资源不存在
`422`	参数校验失败，message 字段返回具体错误信息
`429`	超出请求频率限制
`500`	服务器内部错误

用户资料

GET /api/v2/user/profile

获取当前登录用户的资料信息。

成功响应

{
  "status": "success",
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "zihaoia",
    "name": "zihaoia",
    "email": "zihaoia@yeah.net",
    "avatar_url": "https://...",
    "used_storage": 5120,
    "total_storage": 1048576
  }
}

上传图片

POST /api/v2/upload

上传图片到图床。需携带 Authorization 头。

请求参数（multipart/form-data）

参数	类型	必填	说明
`file`	File	*	图片文件，支持 JPG/PNG/GIF/WEBP/BMP 等
`storage_id`	int	*	储存 ID，指定图片保存到哪个储存
`album_id`	int	否	上传到指定相册
`expired_at`	String	否	过期时间，到期后自动删除
`tags[]`	Array	否	图片标签
`is_public`	bool	否	是否公开，默认跟随用户组设置
`is_remove_exif`	bool	否	是否移除图片 EXIF 信息
`intro`	String	否	图片简介

代码示例

cURL

JavaScript

Python

curl -X POST https://your-domain.com/api/v2/upload \
  -H "Authorization: Bearer <你的Token>" \
  -H "Accept: application/json" \
  -F "file=@/path/to/image.jpg" \
  -F "storage_id=1"

const API = location.origin + '/api/v2';
const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('storage_id', 1);

fetch(API + '/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <你的Token>',
    'Accept': 'application/json'
  },
  body: form
}).then(r => r.json()).then(console.log);

import requests

API = 'https://your-domain.com/api/v2'  # 替换为本站地址
headers = {'Authorization': 'Bearer <你的Token>', 'Accept': 'application/json'}
files = {'file': open('image.jpg', 'rb')}
data = {'storage_id': 1}

res = requests.post(API + '/upload', headers=headers, files=files, data=data)
print(res.json())

成功响应

{
  "status": "success",
  "message": "上传成功",
  "data": {
    "id": 123,
    "name": "xxxxx",
    "filename": "xxxxx.jpg",
    "pathname": "xxxxx.jpg",
    "mimetype": "image/jpeg",
    "extension": "jpg",
    "md5": "...",
    "sha1": "...",
    "width": 1920,
    "height": 1080,
    "ip_address": "127.0.0.1",
    "public_url": "https://your-domain.com/i/xxxxx.jpg",
    "is_public": 1,
    "intro": ""
  }
}

图片列表

GET /api/v2/user/photos

获取当前用户的图片列表，支持分页和筛选。

请求参数（Query）

参数	类型	必填	说明
`page`	int	否	页码，默认 1
`per_page`	int	否	每页数量
`q`	String	否	按名称等关键字搜索
`album_id`	int	否	筛选指定相册的图片
`storage_id`	int	否	筛选指定储存的图片
`order_by`	String	否	排序：`latest` 最新 / `oldest` 最早

图片详情

GET /api/v2/user/photos/{id}

获取单张图片的详细信息，包括公开链接、大小、格式、宽高、上传时间等。

修改图片

PUT /api/v2/user/photos/{id}

修改指定图片的信息（如相册、名称、简介等）。

删除图片

DELETE /api/v2/user/photos

批量删除图片：图片 ID 以 JSON 数组形式放在请求体中，URL 中不带 {id}，成功返回 204（无响应体）。删除后不可恢复，请谨慎操作。

请求体（application/json）

[76,90,26]

相册列表

GET /api/v2/user/albums

获取当前用户的相册列表。

请求参数（Query）

参数	类型	必填	说明
`page`	int	否	页码

创建相册

POST /api/v2/user/albums

请求参数（Body）

参数	类型	必填	说明
`name`	String	*	相册名称
`intro`	String	否	相册简介
`is_public`	bool	否	相册是否公开

删除相册

DELETE /api/v2/user/albums/{id}

删除指定相册。相册内图片不会被删除，仅移除相册分类。成功返回 204（无响应体）。

API Token 管理

GET /api/v2/user/tokens

获取当前用户的 API Token 列表。

POST /api/v2/user/tokens

创建新的 API Token。

请求参数（Body）

参数	类型	必填	说明
`name`	String	*	Token 名称（备注用途）
`abilities`	Array	否	权限范围，默认全部权限
`expires_at`	String	否	Token 过期时间，留空表示永不过期

DELETE /api/v2/user/tokens/{id}

删除指定 Token，删除后该 Token 立即失效。