GET/api/v3/image_list

获取图片列表

分页读取当前账号下的图片，支持按相册和 imgid 筛选。

接口信息

项目	说明
接口地址	`GET /api/v3/image_list`
请求类型	`GET`
鉴权	`Authorization: Bearer sk-xxx`

请求头

字段	值格式	必填	说明
Authorization	`Bearer <token>`	是	开放接口 Token，在控制台 → 开放接口获取，`sk-` 开头

请求参数

参数	类型	必填	说明
page	int	否	页码，从 1 开始，默认 `1`
limit	int	否	每页数量，默认 `20`，最大 `100`；超过 100 按 100 返回
album_id	int	否	相册 ID；不传返回全部相册的图片，传 `0` 只查默认相册
keyword	string	否	按 imgid 精确查询，不支持文件名模糊搜索

只返回当前 Token 所属账号的图片，按上传时间从新到旧排列。

请求示例

cURL

curl --location --request GET 'https://vip.imgurl.org/api/v3/image_list?page=1&limit=20' \
--header 'Authorization: Bearer sk-xxx'

Python

import requests

url = "https://vip.imgurl.org/api/v3/image_list"
headers = {
    "Authorization": "Bearer sk-xxx"
}
params = {
    "page": 1,
    "limit": 20,
    "album_id": 1
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript

const query = new URLSearchParams({
  page: '1',
  limit: '20'
})

fetch(`https://vip.imgurl.org/api/v3/image_list?${query}`, {
  headers: {
    'Authorization': 'Bearer sk-xxx'
  }
})
  .then((response) => response.json())
  .then((data) => console.log(data))

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 128,
    "page": 1,
    "limit": 20,
    "items": [
      {
        "imgid": "WTfdGUBq",
        "size": 102400,
        "upload_at": "2026-01-08 12:20:40",
        "mime_type": "image/jpeg",
        "width": 1920,
        "height": 1080,
        "ext": "jpg",
        "filename": "example.jpg",
        "hash": "a1b2c3d4e5f60718",
        "url": "https://img.example.com/2026/01/08/WTfdGUBq.jpg",
        "thumbnail_url": "https://img.example.com/e8IhefQs3Jv3klW9DubaeTypYkGUm/rs:fill:120:90/g:sm/f:webp/aHR0cHM6Ly8..."
      }
    ]
  }
}

字段	类型	说明
total	int	当前筛选条件下的图片总数
page	int	当前页码
limit	int	当前每页数量
items	array	图片列表，按上传时间从新到旧排列
items[].imgid	string	图片唯一 ID（8 位，大小写字母 + 数字）
items[].size	int	文件大小（字节）
items[].upload_at	string	上传时间，北京时间 `YYYY-MM-DD HH:mm:ss`
items[].mime_type	string	MIME 类型，如 `image/jpeg`
items[].width	int	图片宽度（像素）
items[].height	int	图片高度（像素）
items[].ext	string	扩展名，如 `jpg`
items[].filename	string	原始文件名
items[].hash	string	图片内容 hash，可用于判断重复上传
items[].url	string	原图公开访问地址，使用账号配置的存储域名
items[].thumbnail_url	string	120×90 缩略图地址，由图片处理服务生成

没有图片时 items 为空数组，total 为 0。删除后的图片不会出现在列表里。

失败响应

{
  "code": -1000,
  "msg": "invalid.token",
  "data": null
}

msg	说明
invalid.token	Token 缺失、格式不对、已禁用或已过期
imgid.error	`keyword` 不是合法的 imgid 格式

完整错误码见总览。