Neko Fans Server #
This Server keeps track of how many images were displayed with the Neko Fans plugin.
API #
https://api.nekofans.net/count_total Generates the total download count from every user |
|---|
https://api.nekofans.net/count/123 Generates an image with that number |
|
|---|---|
| 420 | |
| 69 | |
| 1337 | |
| 314159 |
Gallery query API #
POST /gallery/query runs a constrained gallery-dl JSON query through the internal worker, normalizes the result shape, and caches the normalized result in Redis.
Request body:
{
"source": "danbooru",
"rating": "safe",
"tags": ["cat_girl"],
"limit": 25
}
Fields:
| Field | Required | Description |
|---|---|---|
source |
yes, unless url is set |
One of danbooru, gelbooru, safebooru, konachan, or yandere. |
url |
yes, unless source is set |
Direct https:// URL for any gallery-dl extractor. This cannot be combined with source, rating, or tags. |
rating |
no | Convenience field for a booru rating tag such as safe, questionable, or explicit. rating:safe is also accepted and normalized to safe. The worker receives this as a normal rating:<value> search tag. |
tags |
no | Up to 20 tag strings. Tags may contain ASCII letters, numbers, _, -, and :. Existing clients may still pass rating filters as tags, for example rating:safe. |
limit |
no | Number of gallery-dl items to request. Defaults to 50; maximum is 100. |
For source queries, at least one query term is required: either rating or one tags entry.
Response body:
{
"items": [
{
"url": "https://cdn.example/image.jpg",
"source": "danbooru",
"category": "danbooru",
"subcategory": "post",
"id": 123,
"title": null,
"filename": "image",
"extension": "jpg",
"file_url": "https://cdn.example/image.jpg",
"preview_url": "https://cdn.example/preview.jpg",
"sample_url": null,
"width": 1200,
"height": 900,
"rating": "s",
"score": 42,
"tags": ["cat_girl"],
"created_at": "2026-05-24T10:00:00Z",
"metadata": {}
}
],
"errors": []
}
The server consumes gallery-dl -J event rows such as [2, metadata], [3, url, metadata], and [-1, error], then returns a stable object. Source-specific fields are preserved under metadata.
Caching behavior:
| Setting | Default | Description |
|---|---|---|
GALLERY_DL_CACHE_TTL_SECONDS |
900 |
Redis result cache TTL for normalized query target + limit. |
| worker lock TTL | 30 |
Short Redis lock used to avoid duplicate worker calls for the same cache key. Concurrent identical misses return HTTP 202. |
Successful responses are always backed by Redis: either X-Server-Cache: HIT or the worker result is written to Redis before returning X-Server-Cache: MISS. X-Server-Cache-Ttl-Seconds reports the remaining server-side TTL. HTTP responses include Cache-Control: no-store because this is a POST endpoint whose response varies by request body; caching is server-side in Redis, not browser/proxy caching.
The technology used to run the server #
Neko Server is written in Rust with the asyc framework Tokio and using Warp as a web server. This is then all bundled in a Docker container, which gets automaticly build with Google Cloud Build. Those images are then pushed to a private Container repository.
Local development with Nix #
Enter the development shell with:
nix develop
The shell includes the Rust toolchain, rust-analyzer, cargo-watch, Redis, Docker Compose, and the Python dependencies for the gallery-dl worker.