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:

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

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)

<img src="https://imageflow-backend.catcat.blog/api/random" alt="random" />

1) Tag filters (single / multi)

<!-- 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)" />

# 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)

<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" />

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)

<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 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)

# 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)

# 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)

# 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"

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

中文

English

ImageFlow API Usage Guide

📋 Table of Contents

🔐 Authentication

Getting an API Key

🌐 Public Endpoints

Random Image Endpoint

Basic Usage

Advanced Filtering Parameters

Examples

0) Basic usage (no filter)

1) Tag filters (single / multi)

2) Force orientation (landscape / portrait)

3) Preferred format (AVIF / WebP)

4) Orientation × Format combinations (matrix)

5) Content negotiation via Accept (recommended)

6) Excluding tags (when applicable)

​📋 Table of Contents

​🔐 Authentication

​Getting an API Key

​🌐 Public Endpoints

​Random Image Endpoint

​Basic Usage

​Advanced Filtering Parameters

​Examples

0) Basic usage (no filter)

1) Tag filters (single / multi)

2) Force orientation (landscape / portrait)

3) Preferred format (AVIF / WebP)

4) Orientation × Format combinations (matrix)

5) Content negotiation via Accept (recommended)

6) Excluding tags (when applicable)

📋 Table of Contents

🔐 Authentication

Getting an API Key

🌐 Public Endpoints

Random Image Endpoint

Basic Usage

Advanced Filtering Parameters

Examples