Skip to main content
ImageFlow 是一个现代化的图片服务系统，提供完整的图片管理和分发功能。

​
📋 目录

​
🔐 认证机制

ImageFlow 使用 Bearer Token 认证。所有需要认证的接口都需要在请求头中包含： 
Authorization: Bearer your-api-key-here

​
获取API Key

API Key 通过环境变量 API_KEY 配置，联系管理员获取。

​
🌐 公开接口

​
随机图片接口

接口地址: GET /api/random 功能: 获取随机图片，支持高级过滤和智能格式选择

​
基础用法

GET /api/random

​
高级过滤参数

参数类型描述示例
tagstring单个标签过滤?tag=nature
tagsstring多标签过滤(AND逻辑)?tags=nature,sunset,mountain
excludestring排除标签?exclude=nsfw,private
orientationstring强制方向?orientation=landscape
formatstring偏好格式?format=webp

​
实际案例

以下示例基于你的后端地址与标签：
  • 基础地址：https://imageflow-backend.catcat.blog
  • 标签：鬼针草（注意中文标签在 URL 中建议进行编码）
0）最简用法（无过滤）
<img src="https://imageflow-backend.catcat.blog/api/random" alt="random" />
1）按标签筛选（单标签 / 多标签）
<!-- 浏览器会自动 URL 编码，直接写中文也可 -->
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草" alt="鬼针草" />

<!-- AND 逻辑：只有一个标签时等同于 tag= -->
<img src="https://imageflow-backend.catcat.blog/api/random?tags=鬼针草" alt="鬼针草(AND)" />

# curl 建议对中文进行 URL 编码
# "鬼针草" 的编码为 %E9%AC%BC%E9%92%88%E8%8D%89
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89"
curl "https://imageflow-backend.catcat.blog/api/random?tags=%E9%AC%BC%E9%92%88%E8%8D%89"
2）强制方向（横屏 / 竖屏）
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&orientation=landscape" alt="鬼针草-横屏" />
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&orientation=portrait"  alt="鬼针草-竖屏" />

curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=landscape"
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=portrait"
3）偏好格式（AVIF / WebP）
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&format=avif" alt="鬼针草-AVIF" />
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&format=webp" alt="鬼针草-WebP" />

curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&format=avif" -o random.avif
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&format=webp" -o random.webp
4）方向 × 格式 组合（全组合）
# 横屏 + AVIF
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=landscape&format=avif" -o guizhen-cao-landscape.avif

# 横屏 + WebP
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=landscape&format=webp" -o guizhen-cao-landscape.webp

# 竖屏 + AVIF
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=portrait&format=avif" -o guizhen-cao-portrait.avif

# 竖屏 + WebP
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&orientation=portrait&format=webp" -o guizhen-cao-portrait.webp
5）通过 Accept 协商（推荐做法）
# 优先 AVIF，其次 WebP，最后回退到其它图片类型
curl -H 'Accept: image/avif,image/webp;q=0.9,image/*;q=0.5,*/*;q=0.1' \
  "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89" \
  -o random-negotiated
6）排除标签（若数据含敏感/无关标签时）
# 例如排除 nsfw 标签（若数据没有该标签则等同于无影响）
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&exclude=nsfw"
  • 使用 HTML 的 <img> 时，可直接书写中文标签，浏览器会自动编码；
  • 使用命令行或在某些 SDK 中，请使用 URL 编码（“鬼针草” → %E9%AC%BC%E9%92%88%E8%8D%89）。
  • format 表示“偏好”格式，若目标格式不可用，服务会按能力协商并回退。
⌘I