> ## Documentation Index
> Fetch the complete documentation index at: https://imageflowdoc.sakiko.de/llms.txt
> Use this file to discover all available pages before exploring further.

# ImageFlow API 使用指南

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

## 📋 目录

* [公开接口](#公开接口)
* [认证接口](#认证接口)

## 🔐 认证机制

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

```http theme={null}
Authorization: Bearer your-api-key-here
```

### 获取API Key

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

***

## 🌐 公开接口

### 随机图片接口

**接口地址**: `GET /api/random`

**功能**: 获取随机图片，支持高级过滤和智能格式选择

#### 基础用法

```http theme={null}
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）最简用法（无过滤）

```html theme={null}
<img src="https://imageflow-backend.catcat.blog/api/random" alt="random" />
```

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

```html theme={null}
<!-- 浏览器会自动 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)" />
```

```bash theme={null}
# 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）强制方向（横屏 / 竖屏）

```html theme={null}
<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="鬼针草-竖屏" />
```

```bash theme={null}
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）

```html theme={null}
<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" />
```

```bash theme={null}
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）方向 × 格式 组合（全组合）

```bash theme={null}
# 横屏 + 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 协商（推荐做法）

```bash theme={null}
# 优先 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）排除标签（若数据含敏感/无关标签时）

```bash theme={null}
# 例如排除 nsfw 标签（若数据没有该标签则等同于无影响）
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&exclude=nsfw"
```

<Tip>
  * 使用 HTML 的 <code>\<img></code> 时，可直接书写中文标签，浏览器会自动编码；
  * 使用命令行或在某些 SDK 中，请使用 URL 编码（"鬼针草" → <code>%E9%AC%BC%E9%92%88%E8%8D%89</code>）。
  * <code>format</code> 表示“偏好”格式，若目标格式不可用，服务会按能力协商并回退。
</Tip>