CloudFlare ImgBed API 说明文档

CloudFlare ImgBed API 说明文档

来源：CloudFlare ImgBed 官方文档（https://cfbed.sanyue.de）
项目：CloudFlare-ImgBed
收录接口：上传 API · 读取 API · 列出 API · 随机图 API
文档整理日期：2026-09-30

目录

1. 接口总览
2. 上传 API
3. 读取 API
4. 列出 API
5. 随机图 API
6. 附录：相关文档

1. 接口总览

2. 上传 API

来源：https://cfbed.sanyue.de/api/upload.html

上传 API 支持通过第三方上传文件至 CloudFlare ImgBed，便于集成到各种应用和服务中。

2.1 基本信息

2.2 响应格式

[
  {
    "src": "/file/abc123_image.jpg",
    "publicUrl": "https://img.example.com/abc123_image.jpg"
  }
]

上传成功响应为数组，常见字段如下：

2.3 普通上传

直接通过 /upload 端点上传文件，适用于小文件。

Query 参数

Body 参数（FormData）

示例

curl -X POST 'https://your.domain/upload?authCode=YOUR_CODE&uploadChannel=telegram' \
  -F 'file=@"/path/to/image.jpg"'

文件大小限制

2.4 分块上传（Telegram / R2 / S3 / Discord）

当文件较大时，客户端可将文件切分为多个分块，逐块上传后由服务端合并。适用于 telegram、cfr2、s3、discord 四个渠道。

注意：HuggingFace 渠道不支持分块上传，有独立的大文件直传流程（见 2.5）。

推荐分块大小

上传流程

分块上传分为三步：初始化 → 逐块上传 → 合并。

第一步：初始化

创建上传会话，获取 uploadId。

Query 参数：

Body 参数（FormData）：

请求示例：

POST /upload?authCode=YOUR_CODE&initChunked=true&uploadChannel=telegram
Content-Type: multipart/form-data

FormData:
  originalFileName: "video.mp4"
  originalFileType: "video/mp4"
  totalChunks: 5

响应示例：

{
  "success": true,
  "uploadId": "upload_1713500000000_abc123def",
  "sessionInfo": {
    "uploadId": "upload_1713500000000_abc123def",
    "originalFileName": "video.mp4",
    "totalChunks": 5,
    "uploadChannel": "telegram"
  }
}

第二步：逐块上传

将文件按推荐大小切分，依次上传每个分块。每个请求是同步的，服务端会等待分块上传到存储端后才响应。

Query 参数：

Body 参数（FormData）：

请求示例：

POST /upload?authCode=YOUR_CODE&chunked=true&uploadChannel=telegram
Content-Type: multipart/form-data

FormData:
  file: <分块二进制数据>
  uploadId: "upload_1713500000000_abc123def"
  chunkIndex: 0
  totalChunks: 5
  originalFileName: "video.mp4"
  originalFileType: "video/mp4"

响应示例：

{
  "success": true,
  "message": "Chunk 1/5 received and being uploaded",
  "uploadId": "upload_1713500000000_abc123def",
  "chunkIndex": 0
}

并发上传：各分块可并发上传以提升速度。对于 R2/S3 渠道，第一个分块（chunkIndex=0）会初始化 Multipart Upload，其他分块会自动等待初始化完成（最多等待 60 秒）。

第三步：合并

所有分块上传完成后，请求合并。合并过程是同步的。

Query 参数：

Body 参数（FormData）：

请求示例：

POST /upload?authCode=YOUR_CODE&chunked=true&merge=true&uploadChannel=telegram
Content-Type: multipart/form-data

FormData:
  uploadId: "upload_1713500000000_abc123def"
  totalChunks: 5
  originalFileName: "video.mp4"
  originalFileType: "video/mp4"

响应示例：

[
  {
    "src": "/file/1713500000000_video.mp4",
    "publicUrl": "https://img.example.com/1713500000000_video.mp4"
  }
]

失败重试：合并时服务端会自动检查各分块状态，对失败或超时的分块进行重试（最多 5 次）。如果仍有分块未完成，合并会返回错误。

清理请求

如果上传中途取消，可发送清理请求释放临时数据。

Query 参数：

POST /upload?authCode=YOUR_CODE&cleanup=true&uploadId=xxx&totalChunks=5

2.5 HuggingFace 大文件直传

HuggingFace 渠道采用独立的上传流程，文件由客户端直接上传到 HuggingFace LFS 存储，CF Workers 仅负责签名和提交，从而绕过 Cloudflare 的 100MB 请求体限制和 CPU 时间限制。

上传方式选择

前置准备

客户端需要预先计算：

• SHA-256：文件完整内容的 SHA-256 哈希（hex 字符串）
• fileSample：文件前 512 字节的 Base64 编码

第一步：获取上传 URL

请求参数（JSON Body）：

请求示例：

POST /upload/huggingface/getUploadUrl
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "large-video.mp4",
  "fileType": "video/mp4",
  "fileSize": 524288000,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
  "fileSample": "AAAAIGZ0eXBpc29t...",
  "channelName": "my-hf-channel",
  "uploadNameType": "default",
  "uploadFolder": "videos"
}

响应示例：

{
  "success": true,
  "fullId": "videos/1713500000000_large-video.mp4",
  "filePath": "videos/a1b2c3d4_1713500000000_large-video.mp4",
  "channelName": "my-hf-channel",
  "repo": "username/repo-name",
  "needsLfs": true,
  "alreadyExists": false,
  "oid": "e3b0c44298fc1c149afbf4c8996fb924...",
  "uploadAction": {
    "href": "https://s3.amazonaws.com/...",
    "header": { }
  }
}

关键字段说明：

第二步：上传文件到 HuggingFace S3

根据 uploadAction 返回的信息，客户端直接上传到 HuggingFace 的 S3 存储。

基本上传（无 chunk_size）：

PUT <uploadAction.href>
Headers: <uploadAction.header>
Body: <文件二进制内容>

分片上传（有 chunk_size）：

将文件按 chunk_size 切分，依次 PUT 到 header["00001"]、header["00002"] ... 对应的 URL，收集每个响应的 ETag。全部上传完成后，POST 到 uploadAction.href 完成合并：

POST <uploadAction.href>
Content-Type: application/vnd.git-lfs+json

{
  "oid": "<sha256>",
  "parts": [
    { "partNumber": 1, "etag": "\"abc123\"" },
    { "partNumber": 2, "etag": "\"def456\"" }
  ]
}

第三步：提交文件引用

上传完成后，调用提交接口将文件注册到系统数据库。

请求参数（JSON Body）：

请求示例：

POST /upload/huggingface/commitUpload
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fullId": "videos/1713500000000_large-video.mp4",
  "filePath": "videos/a1b2c3d4_1713500000000_large-video.mp4",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
  "fileSize": 524288000,
  "fileName": "large-video.mp4",
  "fileType": "video/mp4",
  "channelName": "my-hf-channel"
}

响应示例：

{
  "success": true,
  "src": "/file/videos/1713500000000_large-video.mp4",
  "publicUrl": "https://img.example.com/videos/1713500000000_large-video.mp4",
  "fileUrl": "https://huggingface.co/datasets/username/repo-name/resolve/main/videos/a1b2c3d4_1713500000000_large-video.mp4",
  "fullId": "videos/1713500000000_large-video.mp4"
}

3. 读取 API

来源：https://cfbed.sanyue.de/api/file.html

读取 API 用于通过统一路径访问已经存储在 CloudFlare ImgBed 中的文件。接口支持各存储渠道的文件读取、HEAD 请求、Range 分段读取，以及按 URL 参数缩放图片。

3.1 基本信息

3.2 请求参数

路径参数

Query 参数

尺寸约束行为：

• 不传 fit 时，width 和 height 表示图片的最大边界：图片保持原始宽高比且不会放大。
• 示例：原图 1600×900，请求 width=640&height=480 时返回 640×360。

请求头

3.3 图片尺寸处理

注意
格式支持：JPEG、PNG 和 WebP 可在所有部署方式中处理；AVIF 仅 Worker 和 Docker 支持，Pages 默认返回 415；GIF 仅 Docker 支持并保持 GIF 格式，Pages 和 Worker 默认返回 415；SVG 及其他格式不支持。
大小限制：Worker 和 Docker 的待处理源文件最大为 20 MB；Pages 以 Cloudflare Images 当前限制为准。
失败回退：使用 fallback=original 可在格式不支持、源文件超限或处理失败时返回原文件。
配置说明：图片尺寸处理默认关闭，使用前请在「配置说明 → 安全设置 → 访问管理」中开启功能并配置允许尺寸。
实际兼容性：实际支持情况以各渠道测试为准。

各部署方式格式支持一览

3.4 响应

成功的 GET 请求返回文件或处理后图片的二进制内容，Content-Type 根据实际输出格式设置；HEAD 请求只返回响应头。

原文件的有效 Range 请求返回 206 Partial Content。

常见响应头

3.5 错误状态码

3.6 示例

读取原文件

curl --location 'https://your.domain/file/album/example.jpg' \
  --output example.jpg

按固定尺寸居中裁剪

<img
  src="https://your.domain/file/album/example.jpg?width=640&height=480&fit=cover&fallback=original"
  alt="示例图片"
>

仅限制宽度（保持宽高比）

curl 'https://your.domain/file/album/example.jpg?width=640' -o thumb.jpg

Range 分段读取

curl -H 'Range: bytes=0-1023' \
  'https://your.domain/file/album/example.jpg' \
  --output chunk.bin

4. 列出 API

来源：https://cfbed.sanyue.de/api/list.html

列表 API 支持获取 CloudFlare ImgBed 中的文件列表。

4.1 基本信息

4.2 请求参数（Query）

4.3 功能说明

普通文件列表查询

获取指定目录下的文件和子目录列表，支持分页、搜索和筛选。

统计查询

当 count=-1 且 sum=true 时，只返回文件总数统计（指定目录和子目录下的文件）。

递归查询

当 recursive=true 时，递归获取子目录下的所有文件。

标签筛选

支持通过标签对文件进行精确筛选：

• 包含标签 (includeTags)：文件必须包含所有指定的标签才会被返回
• 排除标签 (excludeTags)：文件不能包含任何指定的标签
• 标签匹配不区分大小写，支持中文、日文、韩文等多语言标签
• 可以同时使用包含和排除标签进行复合筛选

其他维度筛选

渠道筛选 (channel)

按存储渠道筛选文件，支持多选（OR 逻辑）：

示例：channel=TelegramNew,CloudflareR2 返回存储在 Telegram 或 Cloudflare R2 的文件。

渠道名称筛选 (channelName)

按具体渠道名称筛选，支持多选（OR 逻辑）。渠道名称是用户自定义的存储渠道标识。

支持的格式：

• name — 只匹配渠道名称
• type:name — 同时匹配渠道类型和名称（推荐，用于区分不同类型的同名渠道）

类型标识：TelegramNew、CloudflareR2、S3、Discord、HuggingFace

示例：

• channelName=default — 匹配所有名为 "default" 的渠道
• channelName=TelegramNew:default — 只匹配 Telegram 类型中名为 "default" 的渠道
• channelName=TelegramNew:default,S3:backup — 匹配 Telegram 的 "default" 或 S3 的 "backup"

黑白名单筛选 (listType)

按文件的黑白名单状态筛选，支持多选（OR 逻辑）：

示例：listType=White,None 返回白名单或未设置的文件。

访问状态筛选 (accessStatus)

按文件的访问状态筛选，支持多选（OR 逻辑）：

判断逻辑：

• 已屏蔽：ListType === 'Block' || (Label === 'adult' && ListType !== 'White')
• 正常：其他所有情况

注意：白名单优先，即使审查结果是成人内容（Label === 'adult'），只要在白名单中（ListType === 'White'）就是正常状态。

审查结果筛选 (label)

按内容审查结果筛选，支持多选（OR 逻辑）：

文件类型筛选 (fileType)

按文件 MIME 类型筛选，支持多选（OR 逻辑）：

组合筛选

所有筛选参数可以组合使用，实现复杂的查询需求。例如：

/api/manage/list?listType=White&fileType=image&channel=TelegramNew&accessStatus=normal

返回：白名单 + 图片 + Telegram 渠道 + 正常访问状态的文件。

特殊操作

4.4 响应格式

普通列表响应

{
  "files": [
    {
      "name": "example/image.jpg",
      "metadata": {
        "Channel": "telegram",
        "TimeStamp": "1754020094217",
        "File-Mime": "image/jpeg",
        "File-Size": "1024000"
      }
    }
  ],
  "directories": [
    "example/subfolder"
  ],
  "totalCount": 100,
  "returnedCount": 50,
  "indexLastUpdated": "1754020094217",
  "isIndexedResponse": true
}

统计响应

{
  "sum": 100,
  "indexLastUpdated": "1754020094217"
}

索引信息响应

{
  "totalFiles": 100,
  "lastUpdated": "1754020094217",
  "channelStats": {
    "telegram": 20
  },
  "directoryStats": {
    "/": 30
  },
  "typeStats": {
    "None": 20
  },
  "oldestFile": {},
  "newestFile": {}
}

错误响应

{
  "error": "Internal server error",
  "message": "详细错误信息"
}

4.5 示例

获取文件列表

curl --location --request GET 'https://your.domain/api/manage/list?start=0&count=50' \
  --header 'Authorization: Bearer your_token'

搜索文件

curl --location --request GET 'https://your.domain/api/manage/list?search=image&count=20' \
  --header 'Authorization: Bearer your_token'

获取指定目录

curl --location --request GET 'https://your.domain/api/manage/list?dir=photos/2024' \
  --header 'Authorization: Bearer your_token'

按存储渠道筛选

curl --location --request GET 'https://your.domain/api/manage/list?channel=TelegramNew' \
  --header 'Authorization: Bearer your_token'

按黑白名单筛选

# 获取白名单文件
curl --location --request GET 'https://your.domain/api/manage/list?listType=White' \
  --header 'Authorization: Bearer your_token'

按访问状态筛选

# 获取所有正常访问的文件
curl --location --request GET 'https://your.domain/api/manage/list?accessStatus=normal' \
  --header 'Authorization: Bearer your_token'

# 获取所有已屏蔽的文件
curl --location --request GET 'https://your.domain/api/manage/list?accessStatus=blocked' \
  --header 'Authorization: Bearer your_token'

按文件类型筛选

# 获取所有图片文件
curl --location --request GET 'https://your.domain/api/manage/list?fileType=image' \
  --header 'Authorization: Bearer your_token'

# 获取图片和视频文件
curl --location --request GET 'https://your.domain/api/manage/list?fileType=image,video' \
  --header 'Authorization: Bearer your_token'

按审查结果筛选

# 获取正常内容的文件
curl --location --request GET 'https://your.domain/api/manage/list?label=normal' \
  --header 'Authorization: Bearer your_token'

按渠道名称筛选

# 获取特定渠道名称的文件
curl --location --request GET 'https://your.domain/api/manage/list?channelName=default' \
  --header 'Authorization: Bearer your_token'

# 获取特定类型和名称的渠道文件（推荐）
curl --location --request GET 'https://your.domain/api/manage/list?channelName=TelegramNew:default' \
  --header 'Authorization: Bearer your_token'

# 获取多个渠道的文件
curl --location --request GET 'https://your.domain/api/manage/list?channelName=TelegramNew:default,S3:backup' \
  --header 'Authorization: Bearer your_token'

组合筛选

# 白名单 + 图片 + Telegram 渠道
curl --location --request GET 'https://your.domain/api/manage/list?listType=White&fileType=image&channel=TelegramNew' \
  --header 'Authorization: Bearer your_token'

# 正常访问状态 + 图片类型
curl --location --request GET 'https://your.domain/api/manage/list?accessStatus=normal&fileType=image' \
  --header 'Authorization: Bearer your_token'

获取总数统计

curl --location --request GET 'https://your.domain/api/manage/list?count=-1&sum=true' \
  --header 'Authorization: Bearer your_token'

重建索引

curl --location --request GET 'https://your.domain/api/manage/list?action=rebuild' \
  --header 'Authorization: Bearer your_token'

按标签筛选

# 包含特定标签的文件
curl --location --request GET 'https://your.domain/api/manage/list?includeTags=风景,旅行' \
  --header 'Authorization: Bearer your_token'

# 排除特定标签的文件
curl --location --request GET 'https://your.domain/api/manage/list?excludeTags=私密,草稿' \
  --header 'Authorization: Bearer your_token'

# 组合使用：包含「风景」标签但排除「草稿」标签
curl --location --request GET 'https://your.domain/api/manage/list?includeTags=风景&excludeTags=草稿' \
  --header 'Authorization: Bearer your_token'

5. 随机图 API

来源：https://cfbed.sanyue.de/api/random.html

随机图 API 允许您从图床中随机获取一张图片，适用于网站背景、占位图等场景。

5.1 基本信息

5.2 请求参数

5.3 响应格式

1. 当 type 为 img 时：返回格式为 image/jpeg
2. 当 type 为其他值时：
   • 当 form 不是 text 时，返回 JSON 格式内容，data.url 为返回的链接/文件路径
   • 当 form 是 text 时，直接返回链接/文件路径

5.4 示例

基本请求

curl --location --request GET 'https://your.domain/random'

获取横图

curl --location --request GET 'https://your.domain/random?orientation=landscape'

获取指定目录的竖图

curl --location --request GET 'https://your.domain/random?dir=wallpaper&orientation=portrait'

直接返回图片

curl --location --request GET 'https://your.domain/random?type=img&orientation=landscape'

响应示例

{
  "url": "/file/4fab4d423d039b4665a27.jpg"
}

5.5 使用场景

网站随机背景

<img src="https://your.domain/random?type=img&orientation=landscape" alt="随机背景">

CSS 背景图

.hero {
  background-image: url('https://your.domain/random?type=img&orientation=landscape');
  background-size: cover;
}

手机壁纸 API

https://your.domain/random?type=img&dir=mobile&orientation=portrait

自适应设备方向

curl --location --request GET 'https://your.domain/random?orientation=auto'

5.6 orientation=auto 自适应模式

当 orientation 设为 auto 时，API 会根据请求设备自动判断并返回合适方向的图片。

检测策略

1. Client Hints（优先）：如果浏览器发送了 Sec-CH-Viewport-Width 和 Sec-CH-Viewport-Height 请求头，API 会根据视口宽高比判断方向：
   • 宽高比 > 1.1 → 横图（landscape）
   • 宽高比 < 0.9 → 竖图（portrait）
   • 0.9 ≤ 宽高比 ≤ 1.1 → 方图（square）
2. User-Agent（回退）：如果没有 Client Hints，API 会解析 User-Agent 判断设备类型：
   • 移动设备 → 竖图（portrait）
   • 桌面设备 → 横图（landscape）
3. 无法判断：如果两种方式都无法判断，则不进行方向过滤，返回任意方向的图片。

响应头

自适应模式下，响应会包含以下额外头信息，以便浏览器在后续请求中发送 Client Hints：

• Accept-CH: Sec-CH-Viewport-Width, Sec-CH-Viewport-Height
• Vary: Sec-CH-Viewport-Width, Sec-CH-Viewport-Height, User-Agent

降级处理

• 自适应模式下，如果自动检测的方向没有匹配的图片，会降级返回任意方向的图片（不会返回空结果）
• 手动指定方向（landscape / portrait / square）时，如果没有匹配的图片，返回空结果

6. 附录：相关文档

本文档根据 CloudFlare ImgBed 官方文档整理（上传 / 读取 / 列出 / 随机图），内容以官方文档为准。