> ## 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 Usage Guide

ImageFlow is a modern image service system that provides full image management and delivery capabilities.

## 📋 Table of Contents

* Public Endpoints
* Authenticated Endpoints

## 🔐 Authentication

ImageFlow uses Bearer Token authentication. All endpoints that require authentication must include the following header:

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

### Getting an API Key

The API Key is configured via the `API_KEY` environment variable. Contact the administrator to obtain it.

***

## 🌐 Public Endpoints

### Random Image Endpoint

Endpoint: `GET /api/random`

Purpose: Fetch a random image with advanced filtering and intelligent format selection.

#### Basic Usage

```http theme={null}
GET /api/random
```

#### Advanced Filtering Parameters

| Param         | Type   | Description            | Example                        |
| ------------- | ------ | ---------------------- | ------------------------------ |
| `tag`         | string | Single tag filter      | `?tag=nature`                  |
| `tags`        | string | Multi-tag filter (AND) | `?tags=nature,sunset,mountain` |
| `exclude`     | string | Exclude tags           | `?exclude=nsfw,private`        |
| `orientation` | string | Force orientation      | `?orientation=landscape`       |
| `format`      | string | Preferred format       | `?format=webp`                 |

#### Examples

> Based on your backend and tag:
>
> * Base URL: `https://imageflow-backend.catcat.blog`
> * Tag: `鬼针草` (Chinese; URL-encode recommended in CLI)

##### 0) Basic usage (no filter)

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

##### 1) Tag filters (single / multi)

```html theme={null}
<!-- Browsers auto URL-encode; writing Chinese directly is fine -->
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草" alt="鬼针草" />

<!-- AND semantics; with one tag it's equivalent to tag= -->
<img src="https://imageflow-backend.catcat.blog/api/random?tags=鬼针草" alt="鬼针草 (AND)" />
```

```bash theme={null}
# CLI: URL-encode Chinese. "鬼针草" => %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) Force orientation (landscape / portrait)

```html theme={null}
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&orientation=landscape" alt="鬼针草 - landscape" />
<img src="https://imageflow-backend.catcat.blog/api/random?tag=鬼针草&orientation=portrait"  alt="鬼针草 - portrait" />
```

```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) Preferred format (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 guizhen-cao.avif
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&format=webp" -o guizhen-cao.webp
```

##### 4) Orientation × Format combinations (matrix)

```bash theme={null}
# landscape + 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

# landscape + 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

# portrait + 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

# portrait + 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) Content negotiation via Accept (recommended)

```bash theme={null}
# Prefer AVIF, then WebP, then fall back to other image types
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) Excluding tags (when applicable)

```bash theme={null}
# For example, exclude nsfw; if your data has no such tag, this is a no-op
curl "https://imageflow-backend.catcat.blog/api/random?tag=%E9%AC%BC%E9%92%88%E8%8D%89&exclude=nsfw"
```

<Tip>
  * When using HTML <code>\<img></code>, writing Chinese directly is fine; browsers auto-encode.
  * In CLI/SDK calls, URL-encode Chinese ("鬼针草" → <code>%E9%AC%BC%E9%92%88%E8%8D%89</code>).
  * <code>format</code> is a preference; if unsupported, the service negotiates and falls back.
</Tip>