ImageFlow API 使用指南

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

📋 目录

公开接口
认证接口

🔐 认证机制

ImageFlow 使用 Bearer Token 认证。所有需要认证的接口都需要在请求头中包含：

Authorization: Bearer your-api-key-here

获取API Key

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

🌐 公开接口

随机图片接口

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

基础用法

GET /api/random

高级过滤参数

参数	类型	描述	示例
`tag`	string	单个标签过滤	`?tag=nature`
`tags`	string	多标签过滤(AND逻辑)	`?tags=nature,sunset,mountain`
`exclude`	string	排除标签	`?exclude=nsfw,private`
`orientation`	string	强制方向	`?orientation=landscape`
`format`	string	偏好格式	`?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 表示“偏好”格式，若目标格式不可用，服务会按能力协商并回退。

​📋 目录

​🔐 认证机制

​获取API Key

​🌐 公开接口

​随机图片接口

​基础用法

​高级过滤参数

​实际案例

0）最简用法（无过滤）

1）按标签筛选（单标签 / 多标签）

2）强制方向（横屏 / 竖屏）

3）偏好格式（AVIF / WebP）

4）方向 × 格式 组合（全组合）

5）通过 Accept 协商（推荐做法）

6）排除标签（若数据含敏感/无关标签时）

📋 目录

🔐 认证机制

获取API Key

🌐 公开接口

随机图片接口

基础用法

高级过滤参数

实际案例

4）方向 × 格式组合（全组合）