API Reference

rpicx Public API Documentation

Basic Information

Base URL	`https://api.tor.hk/v1`
Data Format	JSON
OpenAPI	`GET /openapi.json`

Endpoints

`GET /v1/health`

Auth: None

Description: Service health check, returns total image count and running status.

Response 200:

{
  "status": "ok",
  "image_count": 100000
}

`GET /v1/random`

Auth: None

Description: Randomly selects an image from the index and returns a 302 redirect.

Query Parameters:

Parameter	Type	Required	Description
`category`	string	No	Filter by category

Success (302):

Location: https://img.tor.hk/xxx.webp

No Image (404):

{ "success": false, "error": "No images available" }

`GET /v1/categories`

Auth: None

Description: Returns total image count.

Response 200:

{
  "total_images": 100000,
  "categories": []
}

`GET /v1/stats`

Auth: None (IP rate limit 10 QPS, response cache 3h)

Description: Returns aggregated service statistics.

Response 200:

{
  "requests_total": 1000000,
  "requests_today": 5000,
  "avg_hour_requests": 200.0,
  "uv_today": 1200,
  "top_referer": [{ "name": "github.com", "count": 300 }],
  "top_ua": [{ "name": "Chrome", "count": 500 }],
  "status": { "code_200": 900000, "code_302": 50000, "code_404": 20, "code_429": 10, "code_500": 0 },
  "sync_count": 30
}

`GET /metrics`

Auth: None

Description: Prometheus metrics endpoint (text/plain).

`GET /openapi.json`

Auth: None

Description: Returns OpenAPI 3.0 specification document (JSON).