Skip to main content
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

ParamTypeDescriptionExample
tagstringSingle tag filter?tag=nature
tagsstringMulti-tag filter (AND)?tags=nature,sunset,mountain
excludestringExclude tags?exclude=nsfw,private
orientationstringForce orientation?orientation=landscape
formatstringPreferred 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.