14 KiB
e621tagger API Documentation
This document provides comprehensive API documentation for agent integration. It covers all Flask endpoints, request/response contracts, error handling, and usage examples.
Base URL
Production: https://tagger.fenrir784.app
Local: http://localhost:5000
Endpoints Overview
| Method | Path | Description | Rate Limit |
|---|---|---|---|
| GET | / |
Main UI page | - |
| POST | /predict |
Submit image for tagging | 20/min, 500/hr |
| OPTIONS | /predict |
CORS preflight | - |
| GET | /health |
Health check | - |
| GET | /service-worker.js |
PWA service worker | - |
| GET | /static/<path> |
Static assets | - |
| GET | /favicon.ico |
Favicon | - |
| GET | /robots.txt |
Robots.txt | - |
| GET | /sitemap.xml |
Sitemap | - |
GET / - Main UI Page
Returns the main HTML interface for image tagging.
Request
GET / HTTP/1.1
Host: tagger.fenrir784.app
Response
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Security-Policy: ...
<!DOCTYPE html>
<html lang="en">
<head>
<title>e621tagger</title>
...
</head>
<body>
<div class="container">
<header>...</header>
<main>
<div id="dropZone">...</div>
<div class="results">...</div>
</main>
</div>
</body>
</html>
Security Headers
All responses include these headers:
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), microphone=(), camera=()
Content-Security-Policy: default-src 'self'; img-src 'self' data: blob:; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https://e621.net; object-src 'none'; base-uri 'self';
POST /predict - Image Classification
Submit an image for AI-powered tag generation.
Rate Limits
| Limit | Window | Scope |
|---|---|---|
| 20 requests | per minute | /predict endpoint only |
| 500 requests | per hour | All endpoints (global default) |
Exceeding limits returns HTTP 429.
Request
POST /predict HTTP/1.1
Host: tagger.fenrir784.app
Content-Type: multipart/form-data
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
image |
file | Yes | Image file (JPEG, PNG, GIF, WebP, BMP, TIFF) |
top_k |
integer | No | Number of tags to return (default: 200) |
Allowed Values
- top_k: 50, 75, 100, 150, 200, 300
- image formats: .jpg, .jpeg, .png, .gif, .webp, .bmp, .tiff
- max file size: 20MB
Request Example
# Using curl
curl -X POST https://tagger.fenrir784.app/predict \
-F "[email protected]" \
-F "top_k=200"
# Python example
import requests
with open("artwork.png", "rb") as f:
response = requests.post(
"https://tagger.fenrir784.app/predict",
files={"image": f},
data={"top_k": "200"}
)
Response (Success)
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"tags": [
{
"tag": "female",
"prob": 0.95,
"category": "General"
},
{
"tag": "anthro",
"prob": 0.89,
"category": "Species"
},
{
"tag": "furry",
"prob": 0.87,
"category": "General"
},
{
"tag": "safe",
"prob": 0.92,
"category": "Meta"
},
...
],
"auto_meta": [
"hi_res",
"16:9"
]
}
Note: Rating tags (
safe,questionable,explicit) appear in thetagsarray as model predictions, not inauto_meta. Theauto_metafield contains automatically-detected technical tags like resolution and aspect ratio.
Tag Object Structure
| Field | Type | Description |
|---|---|---|
tag |
string | Tag name |
prob |
float | Confidence probability (0.0 to 1.0) |
category |
string | e621 category name |
Categories
General tags are further split into 12 subcategories using the _SUBCATEGORY_MAP in hydra/_subcat.py. The API returns the subcategory display name in the category field:
| ID | Name | Description |
|---|---|---|
| 0 | General | General tags (split into 12 subcategories below) |
| 1 | Artist | Artist tags |
| 2 | Contributor | Contributor tags |
| 3 | Copyright | Copyright/series tags |
| 4 | Character | Character tags |
| 5 | Species | Species tags |
| 6 | Invalid | Invalid tags |
| 7 | Meta | Meta tags (rating, resolution) |
| 8 | Lore | Lore-related tags |
| 100 | Accessories, Items, Clothing | Clothing and accessories |
| 101 | Actions, Positions, State | Actions and poses |
| 102 | Body Color | Body color tags |
| 103 | Body Features | Body feature tags |
| 104 | Effects, Fluids | Effects and fluids |
| 105 | Fetishes, Specifics, Interactions | Fetish and adult tags |
| 106 | Genders, Demographics | Gender and demographic tags |
| 107 | Locations, Backgrounds, Setting | Location and background tags |
| 108 | Poses, Scenarios, Situations | Pose and scenario tags |
| 109 | Style, Perspective | Style and perspective tags |
| 110 | Text, Symbols, UI, Vocalization | Text and UI tags |
| 111 | Other | Tags from unrecognized categories |
Note: When copying tags to clipboard, categories 100-111 are merged into "General" to maintain e621 compatibility. The subcategory mapping uses a multi-tier strategy (direct map lookup, color prefix heuristic) and has been validated to 100% coverage (6,263/6,263 general tags). See TAGGING.md for details.
Auto-Generated Meta Tags
These tags are automatically added based on image properties:
| Tag | Condition |
|---|---|
animated |
GIF with multiple frames |
thumbnail |
Width ≤ 250px and height ≤ 250px |
low_res |
Width ≤ 500px and height ≤ 500px |
hi_res |
Width ≥ 1600px OR height ≥ 1200px |
absurd_res |
Width ≥ 3200px OR height ≥ 2400px |
superabsurd_res |
Width ≥ 10000px AND height ≥ 10000px |
4k |
3840x2160, 2160x3840, 4096x2160, or 2160x4096 |
long_image |
Aspect ratio ≥ 4:1 or ≤ 1:4 |
tall_image |
Aspect ratio ≤ 1:4 (subset of long_image) |
widescreen |
Aspect ratio 16:9 or ~16:10 |
1:1, 2:1, 16:9, etc. |
Standard aspect ratios |
Response (Error)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "No image provided"
}
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
{
"error": "File too large. Maximum size is 20MB."
}
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | No image provided |
Missing image field |
| 400 | Empty filename |
Empty filename parameter |
| 400 | File type not allowed |
Unsupported file extension |
| 400 | Invalid or corrupted image file |
Image verification failed |
| 413 | File too large. Maximum size is 20MB. |
Exceeds 20MB limit |
| 429 | Rate limit exceeded | Too many requests |
| 500 | Internal server error |
Processing failed |
GET /health - Health Check
Check if the service is operational.
Request
GET /health HTTP/1.1
Host: tagger.fenrir784.app
Response (Healthy)
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "healthy",
"model": "JTP-3 Hydra 3.5",
"tags_count": 8888,
"version": "v123"
}
Response (Unhealthy)
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{
"status": "unhealthy",
"reason": "model not loaded"
}
Response Fields
| Field | Type | Description |
|---|---|---|
status |
string | healthy or unhealthy |
model |
string | Model name (e.g. JTP-3 Hydra 3.5) |
tags_count |
integer | Number of tags in model (8,888 for Hydra 3.5) |
version |
string | Application version |
reason |
string | Error reason if unhealthy |
GET /static/ - Static Assets
Serve static files (CSS, JS, icons).
Request
GET /static/css/style.css HTTP/1.1
Host: tagger.fenrir784.app
Response
HTTP/1.1 200 OK
Content-Type: text/css
Cache-Control: public, max-age=86400
Caching
Static assets are cached for 24 hours:
Cache-Control: public, max-age=86400
GET /service-worker.js - PWA Service Worker
Serve the service worker script for PWA functionality.
Request
GET /service-worker.js HTTP/1.1
Host: tagger.fenrir784.app
Response
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Note
Service worker is cached by the browser's SW cache, not HTTP cache. Cache headers prevent HTTP caching but allow SW caching.
GET /favicon.ico - Favicon
Response
HTTP/1.1 200 OK
Content-Type: image/vnd.microsoft.icon
Cache-Control: public, max-age=86400
GET /robots.txt - Robots.txt
Request
GET /robots.txt HTTP/1.1
Host: tagger.fenrir784.app
Response
HTTP/1.1 200 OK
Content-Type: text/plain
User-agent: *
Disallow: /predict
Disallow: /health
Disallow: /service-worker.js
Sitemap: https://www.tagger.fenrir784.app/sitemap.xml
GET /sitemap.xml - Sitemap
Request
GET /sitemap.xml HTTP/1.1
Host: tagger.fenrir784.app
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://www.tagger.fenrir784.app/</loc>
<lastmod>2024-01-01</lastmod>
<changefreq>daily</changefreq>
<priority>1.0</priority>
</url>
</urlset>
Python Integration Example
import requests
from PIL import Image
import io
class E621Tagger:
def __init__(self, base_url="https://tagger.fenrir784.app"):
self.base_url = base_url
self.session = requests.Session()
def check_health(self) -> dict:
"""Check service health."""
response = self.session.get(f"{self.base_url}/health")
response.raise_for_status()
return response.json()
def tag_image(
self,
image_path: str = None,
image_bytes: bytes = None,
top_k: int = 200
) -> dict:
"""
Tag an image.
Args:
image_path: Path to image file
image_bytes: Raw image bytes
top_k: Number of tags to return (50-300)
Returns:
dict with 'success', 'tags', 'auto_meta'
"""
if image_path:
with open(image_path, "rb") as f:
files = {"image": f}
elif image_bytes:
files = {"image": io.BytesIO(image_bytes)}
else:
raise ValueError("Must provide image_path or image_bytes")
data = {"top_k": str(top_k)}
response = self.session.post(
f"{self.base_url}/predict",
files=files,
data=data
)
response.raise_for_status()
return response.json()
def tag_image_pil(self, image: Image.Image, top_k: int = 200) -> dict:
"""Tag a PIL Image."""
buf = io.BytesIO()
image.save(buf, format="PNG")
buf.seek(0)
files = {"image": ("image.png", buf, "image/png")}
response = self.session.post(
f"{self.base_url}/predict",
files=files,
data={"top_k": str(top_k)}
)
response.raise_for_status()
return response.json()
# Usage
tagger = E621Tagger()
# Check health
health = tagger.check_health()
print(f"Status: {health['status']}")
print(f"Tags: {health['tags_count']}")
# Tag an image
result = tagger.tag_image("artwork.png")
print(f"Success: {result['success']}")
print(f"Tags returned: {len(result['tags'])}")
# Print top tags
for tag in result["tags"][:10]:
print(f" {tag['tag']}: {tag['prob']:.2%} ({tag['category']})")
JavaScript Integration Example
class E621Tagger {
constructor(baseUrl = 'https://tagger.fenrir784.app') {
this.baseUrl = baseUrl;
}
async checkHealth() {
const response = await fetch(`${this.baseUrl}/health`);
return response.json();
}
async tagImage(file, topK = 200) {
const formData = new FormData();
formData.append('image', file);
formData.append('top_k', topK.toString());
const response = await fetch(`${this.baseUrl}/predict`, {
method: 'POST',
body: formData
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error || 'Request failed');
}
return response.json();
}
}
// Usage
const tagger = new E621Tagger();
const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
const file = e.target.files[0];
const result = await tagger.tagImage(file);
console.log('Success:', result.success);
console.log('Tags:', result.tags);
console.log('Auto Meta:', result.auto_meta);
});
Rate Limiting
The application uses flask-limiter for rate limiting.
Limits
| Endpoint | Limit |
|---|---|
/predict |
20 per minute |
| Default | 500 per hour |
Rate Limit Headers
When rate limited, responses include:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
{
"error": "Rate limit exceeded"
}
Implementation
Located in app.py:
limiter = Limiter(
get_remote_address,
app=app,
default_limits=["500 per hour"],
storage_uri="memory://",
)
@app.route('/predict', methods=['POST'])
@limiter.limit("20 per minute")
def predict():
...
Content Security Policy
The application sets a strict CSP:
Content-Security-Policy: default-src 'self'; img-src 'self' data: blob:; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https://e621.net; object-src 'none'; base-uri 'self';
Directives
| Directive | Value | Purpose |
|---|---|---|
| default-src | 'self' | Default: same origin |
| img-src | 'self' data: blob: | Images: same origin, data URLs, blobs |
| script-src | 'self' | Scripts: same origin only |
| style-src | 'self' 'unsafe-inline' | Styles: same origin + inline |
| connect-src | 'self' https://e621.net | Fetch: same origin + e621 |
| object-src | 'none' | No plugins/objects |
| base-uri | 'self' | Base URL: same origin |