TG CDN

API 文档

所有接口都基于 https://tgimage.163418.xyz。公开读取接口无需鉴权；上传与管理接口需要 Token 或后台登录态。

快速开始

上传一张图片，拿到的 preview 可以直接放进 <img>：

curl -X POST https://tgimage.163418.xyz/upload \
  -H "Authorization: Bearer <UPLOAD_TOKEN>" \
  -F "file=@cat.jpg" \
  -F "category=animals"
{
  "ok": true,
  "id": "mvy5mpa0mzvrfj1m",
  "type": "image",
  "category": "animals",
  "name": "cat.jpg",
  "size": 252962,
  "preview": "https://tgimage.163418.xyz/i/mvy5mpa0mzvrfj1m",
  "download": "https://tgimage.163418.xyz/f/mvy5mpa0mzvrfj1m",
  "message_id": 3
}
<img src="https://tgimage.163418.xyz/random/animals" alt="random">

鉴权

方式用法
Bearer TokenAuthorization: Bearer <UPLOAD_TOKEN 或 ADMIN_TOKEN>，脚本/curl 用
后台登录POST /api/login 用账号密码换取 7 天有效的 HttpOnly Cookie，浏览器用
curl -X POST https://tgimage.163418.xyz/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<账号>","password":"<密码>"}' -c cookie.txt
上传接口 /upload 与所有 /api/item*、/api/batch、/api/stats 都需要鉴权；/i/、/f/、/random、/api/list、/api/categories、/api/visits 公开可读。

POST /upload

multipart/form-data 上传单个文件。图片按文件发送可保持原图（不重压缩）。

字段必填说明
file是文件本体
category否分类，默认 uncategorized；会出现在随机图路径里
type否auto（默认）按 MIME 判断，或强制 image / file
as_photo否1 用图片消息发送（频道里显示大图，但 Telegram 会压缩）
# 上传文件（非图片会自动归为 file，只有下载链接）
curl -X POST https://tgimage.163418.xyz/upload \
  -H "Authorization: Bearer <UPLOAD_TOKEN>" \
  -F "file=@report.pdf" \
  -F "category=docs"

访问与下载

路径行为
/i/:id图片内联预览，Content-Disposition: inline，可直接引用；支持 Range / ETag / 长缓存
/f/:id强制下载，保留原文件名；同样支持 Range（大文件断点续传）
# 下载（保留原文件名）
curl -O -J https://tgimage.163418.xyz/f/<id>

# 断点续传（Range）
curl -H "Range: bytes=0-1048575" https://tgimage.163418.xyz/i/<id> -o part1.jpg

随机图

按分类随机返回一张图片，默认 302 跳转到 /i/:id，加 ?format=json 返回信息。

# 直接当图片地址用
<img src="https://tgimage.163418.xyz/random/animals">

# 全部图片里随机
https://tgimage.163418.xyz/random

# 返回 JSON
curl "https://tgimage.163418.xyz/random/anime?format=json"
{
  "id": "mvy5rmhxtd3qnz1c",
  "category": "anime",
  "name": "anime-20261102-022315.jpg",
  "preview": "https://tgimage.163418.xyz/i/mvy5rmhxtd3qnz1c",
  "download": "https://tgimage.163418.xyz/f/mvy5rmhxtd3qnz1c"
}

当前可用分类：加载中…

列表与分类

路径说明
/api/list/:category?limit=36该分类最新图片；all 表示全部
/api/categories分类及数量 + 概要统计
/api/visits图片调用次数（calls = 直链 + 随机图），边缘缓存 30 秒
/api/home?category=all&limit=24首页一次拿全：分类 + 概要 + 调用次数 + 图库第一页（省 3 个请求）
/health健康检查
curl "https://tgimage.163418.xyz/api/list/animals?limit=12"
curl "https://tgimage.163418.xyz/api/categories"
curl "https://tgimage.163418.xyz/api/visits"

管理接口

以下接口需要鉴权，用于后台与自动化脚本。

方法路径说明
GET/api/items查询：type / category / q / sort / trash=1 / limit / offset
GET/api/item/:id单条详情
PATCH/api/item/:id改名 / 换分类：{"name","category"}
DELETE/api/item/:id软删除进回收站；加 ?hard=1 彻底删除
POST/api/batch{"ids":[],"action":"trash|restore|delete|move","category"}
GET/api/stats图片数 / 文件数 / 占用空间 / 分类分布
GET/api/traffic?days=14访问统计：总量、按天、按路由、状态码、热门路径
GET/api/categories/list分类列表，按类型分开：{image:[...], file:[...]}
POST/api/categories新建：{"type":"image|file","name":"wallpaper"}
PATCH/api/categories/:name?type=image重命名该类型的分类并迁移其条目
DELETE/api/categories/:name?type=file&move_to=删除该类型的分类；该类型下非空时需指定迁移目标
# 查询图片，按大小排序
curl -H "Authorization: Bearer <TOKEN>" \
  "https://tgimage.163418.xyz/api/items?type=image&sort=size&limit=10"

# 改名 + 换分类
curl -X PATCH https://tgimage.163418.xyz/api/item/<id> \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"name":"new.jpg","category":"wallpaper"}'

# 批量移入回收站
curl -X POST https://tgimage.163418.xyz/api/batch \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"ids":["id1","id2"],"action":"trash"}'

# 分类：新建 / 重命名 / 删除（非空分类要指定迁移目标）
curl -X POST https://tgimage.163418.xyz/api/categories   -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json"   -d '{"name":"wallpaper"}'
curl -X PATCH https://tgimage.163418.xyz/api/categories/wallpaper   -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json"   -d '{"name":"desktop"}'
curl -X DELETE "https://tgimage.163418.xyz/api/categories/desktop?move_to=animals"   -H "Authorization: Bearer <TOKEN>"

错误码

状态含义
400参数缺失或格式错误
401未登录 / Token 无效
404资源不存在或该分类没有图片
413文件超过 50MB
502Telegram 上传/下载失败（机器人权限或网络）
{"error": "telegram upload failed", "detail": {"ok": false, "description": "Forbidden: bot is not a member of the channel chat"}}

限制说明

项目限制
单文件上传≤ 50MB（Telegram Bot API 限制）
下载≤ 20MB（超过的能存进频道，但取不回来）
分类名字母 / 数字 / 中文 / 下划线 / 横线，≤ 32 字符
列表一致性KV 最终一致，新上传的条目在其他边缘节点可能有几十秒延迟
随机图只从"未被删除的图片"里取，文件不参与