OnePic API#

基于边缘计算的随机图片API服务，支持多平台部署。

项目链接：https://pic.api.sylv.top

OnePic API

项目简介#

OnePic API 是一个轻量级的随机图片服务，利用边缘计算技术实现，支持WebP图片格式，自动适配PC端和移动端设备。

项目提供两个分支，分别适配不同的边缘计算平台：

分支	适配平台	说明
`main`	腾讯云 EdgeOne Pages	默认分支，使用 EdgeOne Pages 边缘函数
`aliyun-esa`	阿里云 ESA	使用阿里云边缘安全加速平台

项目特性#

核心功能#

WebP格式: 采用现代WebP图片格式，体积小、质量高
设备适配: 自动检测客户端设备类型，返回PC端或移动端图片
随机返回: 从图片池中随机选择图片，保证多样性
多返回格式: 支持JSON响应、图片重定向、纯文本链接

技术优势#

边缘计算: 基于边缘函数，全球节点就近响应
零延迟缓存: 图片列表构建时嵌入，运行时零额外请求
轻量架构: 无需后端服务器，纯静态资源+边缘函数
简单部署: 推送到Git仓库即可自动构建部署
多平台支持: 同时支持腾讯云 EdgeOne Pages 和阿里云 ESA 平台

项目结构#

EdgeOne Pages 分支 (main)#

1
onepic-api/
2
├── build.js                    # 构建脚本
3
├── package.json                # 项目配置
4
├── edgeone.json                # EdgeOne Pages配置
5
├── convert_images_fixed.bat    # 图片转换脚本(Windows)
6
├── README.md                   # 项目文档
7
├── .gitignore                  # Git忽略配置
8
├── images/                     # 原始图片目录
9
│   ├── pc/                     # PC端原始图片
10
│   └── pe/                     # 移动端原始图片
11
├── converted/                  # 转换后图片目录
12
│   ├── pc/webp/                # PC端WebP图片
13
│   └── pe/webp/                # 移动端WebP图片
14
└── edge-functions/             # 边缘函数目录
15
    ├── api/index.js            # /api 接口处理
16
    └── image/index.js          # /image 接口处理

阿里云 ESA 分支 (aliyun-esa)#

1
onepic-api/
2
├── build.js                    # 构建脚本
3
├── package.json                # 项目配置
4
├── esa.jsonc                   # 阿里云 ESA 配置
5
├── convert_images_fixed.bat    # 图片转换脚本(Windows)
6
├── README.md                   # 项目文档
7
├── .gitignore                  # Git忽略配置
8
├── images/                     # 原始图片目录
9
│   ├── pc/                     # PC端原始图片
10
│   └── pe/                     # 移动端原始图片
11
├── converted/                  # 转换后图片目录
12
│   ├── pc/webp/                # PC端WebP图片
13
│   └── pe/webp/                # 移动端WebP图片
14
└── edge-functions/             # 边缘函数目录
15
    └── esa/index.js            # ESA 统一入口函数

快速开始#

1. 准备图片#

将图片放入以下目录：

1
images/
2
├── pc/    # 电脑端图片
3
└── pe/    # 移动端图片

2. 图片格式转换#

使用ImageMagick将图片转换为WebP格式：

1
# Windows系统运行
2
convert_images_fixed.bat
3

4
# 或手动转换
5
magick input.jpg -quality 85 output.webp

3. 选择平台并部署#

方式一：部署到 EdgeOne Pages (使用 main 分支)#

切换到 main 分支：git checkout main
推送代码到Git仓库
在EdgeOne Pages创建站点并关联仓库
设置构建配置：
- 构建命令：npm run build
- 输出目录：dist
- Node版本：20.18.0
触发构建，等待部署完成

方式二：部署到阿里云 ESA (使用 aliyun-esa 分支)#

切换到 aliyun-esa 分支：git checkout aliyun-esa
推送代码到Git仓库
在阿里云 ESA 创建应用并关联仓库
设置构建配置：
- 构建命令：node build.js
- 输出目录：dist
触发构建，等待部署完成

API 文档#

接口列表#

接口	描述	方法
`/api`	获取随机图片（JSON/重定向/文本）	GET
`/image`	直接重定向到随机图片	GET

GET /api#

获取随机图片，支持多种返回格式。

请求参数#

参数	类型	必填	默认值	说明
`count`	整数	否	1	返回图片数量，范围1-50
`type`	字符串	否	自动检测	设备类型：`pc` 或 `pe`
`format`	字符串	否	webp	图片格式，当前仅支持 `webp`
`return`	字符串	否	json	返回类型：`json`、`redirect`、`text`

返回类型#

JSON响应 (return=json)

1
{
2
  "success": true,
3
  "count": 2,
4
  "type": "pc",
5
  "format": "webp",
6
  "images": [
7
    {
8
      "url": "https://example.com/converted/pc/webp/xxx.webp",
9
      "format": "webp",
10
      "type": "pc"
11
    },
12
    {
13
      "url": "https://example.com/converted/pc/webp/yyy.webp",
14
      "format": "webp",
15
      "type": "pc"
16
    }
17
  ]
18
}

重定向 (return=redirect)

直接302重定向到图片URL，适用于count=1。

纯文本 (return=text)

每行一个图片URL，适用于批量获取链接。

1
https://example.com/converted/pc/webp/xxx.webp
2
https://example.com/converted/pc/webp/yyy.webp

GET /image#

直接重定向到一张随机图片，无需参数。

使用示例#

1
# 获取1张随机图片（JSON）
2
GET /api
3

4
# 获取10张随机图片
5
GET /api?count=10
6

7
# 获取移动端图片
8
GET /api?type=pe
9

10
# 获取5张移动端图片
11
GET /api?type=pe&count=5
12

13
# 直接重定向到图片
14
GET /api?count=1&return=redirect
15

16
# 获取纯文本链接
17
GET /api?count=10&return=text
18

19
# 直接获取随机图片（重定向）
20
GET /image

设备检测#

API会自动检测客户端设备类型：

检测到移动设备（Android、iOS等）时返回 pe 类型图片
其他情况返回 pc 类型图片

也可通过 type 参数手动指定。

构建说明#

运行构建命令：

1
npm run build

构建过程会：

清理 dist 目录
复制图片文件到 dist/converted/
扫描图片文件列表并嵌入到边缘函数代码
生成包含API文档的首页

技术栈#

运行时: 边缘函数 (EdgeOne Pages / 阿里云 ESA)
构建工具: Node.js
图片格式: WebP
部署平台:
- 腾讯云 EdgeOne Pages (main 分支)
- 阿里云 ESA (aliyun-esa 分支)

平台差异说明#

EdgeOne Pages (main 分支)#

使用 EdgeOne Pages 原生边缘函数格式
函数入口分布在 edge-functions/api/index.js 和 edge-functions/image/index.js
配置文件为 edgeone.json
支持自动 CORS 头部配置和缓存策略

阿里云 ESA (aliyun-esa 分支)#

使用阿里云 ESA 边缘函数统一入口格式
函数入口为 edge-functions/esa/index.js
配置文件为 esa.jsonc
构建时生成 dist/er/index.js 作为函数入口

环境要求#

Node.js 20.x 或更高版本
ImageMagick（用于图片转换，可选）
Git仓库（用于部署）

许可证#

MIT License