Q3CC API Documentation

website·Indexed 31 days ago

https://api.q3cc.top

API reference for Q3CC services, featuring endpoints for system status (health checks and statistics), calendar services for holiday detection, a hitokoto quote service, and a random image service.

Tokens: 2.2K
Snippets: 16
Records: 17
Agent score: 48%

What's inside Q3CC API

Use pithy mode for simple holiday status
Setting the query parameter type=pithy returns a plain text response indicating the day's status. The possible values are:
- ture: Holiday
- flase: Non-holiday
- worker: Makeup workday
```
curl "https://api.q3cc.top/api/holidays?type=pithy&y=2025&m=10&d=1"
# Response: ture
```
https://api.q3cc.top/reference/calendar/holidays
Check system health with the ping endpoint
Use the GET /api/ping endpoint to perform a health check on the API interface. The response is plain text pong.
```
curl https://api.q3cc.top/api/ping
```
https://api.q3cc.top/reference/
Get a random image URL
The GET /img endpoint returns a random image. Depending on the request, it can respond with a 302 redirect, a plain text direct link (type=url), or a JSON response (type=json).
```
# Example for JSON response
curl "https://api.q3cc.top/img?type=json"
```
https://api.q3cc.top/reference/
Get plain text quotes from /api/hitokoto
To receive only the quote text without JSON metadata, use the encode=text or type=text query parameter.
```
curl "https://api.q3cc.top/api/hitokoto?c=i&encode=text"
```
https://api.q3cc.top/reference/content/hitokoto
Handle JSON responses from the /img endpoint
When requesting a random image with the type=json query parameter, the API returns a JSON object containing the direct link to the image instead of a 302 redirect.
```
{
  "url": "https://list.yppp.net/d/image/2026-02-15-d04a3ad05a815966831fdbaee96ba802.jpg"
}
```
https://api.q3cc.top/reference/image/random
Retrieve system and user statistics
The GET /api/info endpoint provides statistical information for the entire site and the current requesting user. The response is returned in JSON format and uses the UTC+8 timezone.
```
curl https://api.q3cc.top/api/info
```
https://api.q3cc.top/reference/
Use alarm mode for work/vacation status
Setting the query parameter type=alarm returns a plain text response indicating whether the day is a working day or a vacation day.
Logic:
- work: Monday to Friday (excluding legal holidays) OR makeup workdays.
- vacation: Legal holidays OR regular weekends.
```
curl "https://api.q3cc.top/api/holidays?type=alarm&y=2026&m=4&d=20"
# Response: work
```
https://api.q3cc.top/reference/calendar/holidays
Fetch a random quote using GET /api/hitokoto
The /api/hitokoto endpoint returns a random quote from a built-in dataset (sourced from hitokoto-osc/sentences-bundle). It supports both JSON and plain text responses and allows filtering by category and length.
Request Details:
- Method: GET or HEAD
- Host: api.q3cc.top
Query Parameters:
- c: Category key (can be passed multiple times for multi-category randomization). Defaults to all categories if omitted.
- encode=text or type=text: Returns only the quote text instead of a JSON object.
- min_length: Minimum length of the quote (non-negative integer).
- max_length: Maximum length of the quote (non-negative integer).
Category Keys (c):
- a: Animation
- b: Manga
- c: Game
- d: Literature
- e: Original
- f: Internet
- g: Other
- h: Movie/TV
- i: Poetry
- j: NetEase CloudMusic
- k: Philosophy
- l: Wit/Humor
```
# Get a random quote from the Animation category
curl "https://api.q3cc.top/api/hitokoto?c=a"

# Get a random quote from Animation, Game, or Movie categories
curl "https://api.q3cc.top/api/hitokoto?c=a&c=c&c=h"

# Get a quote from Philosophy with length between 8 and 20 characters
curl "https://api.q3cc.top/api/hitokoto?c=k&min_length=8&max_length=20"
```
https://api.q3cc.top/reference/content/hitokoto
Get holiday status in JSON format
When the type parameter is omitted, the /api/holidays endpoint returns a detailed JSON response containing the date, status, and holiday name.
```
{
  "date": "2025-10-01",
  "year": 2025,
  "month": 10,
  "day": 1,
  "status": "ture",
  "isHoliday": true,
  "isWorkday": false,
  "name": "国庆节、中秋节"
}
```
https://api.q3cc.top/reference/calendar/holidays
Query holiday and work day status
The GET /api/holidays endpoint allows you to check if a specific date is a holiday, a normal day, or a makeup workday. The response is JSON by default, or plain text when using type=pithy.
```
# Example for pithy text response
curl "https://api.q3cc.top/api/holidays?type=pithy"
```
https://api.q3cc.top/reference/
Retrieve system and user usage statistics via GET /api/info
The GET /api/info endpoint returns global site statistics and statistics specific to the requesting user.
Key Statistics Logic:
- Only successful hits on implemented interfaces are counted.
- Requests to unimplemented /api/* endpoints return a 404 and are not counted.
- The response for /api/info includes the current request in its count.
- User identification priority: CF-Connecting-IP > first IP in X-Forwarded-For > unknown.
Response Fields:
- timezone: Fixed as UTC+8.
- date: Current date in YYYY-MM-DD format (UTC+8).
- requestUser: Identifier for the current user (typically IP).
- site.totalRequests: Total cumulative calls across the entire site.
- site.dailyRequests: Total calls for the current UTC+8 day across the site.
- requestUserStats.totalRequests: Total cumulative calls by the current user.
- requestUserStats.dailyRequests: Total calls by the current user for the current UTC+8 day.
```
curl https://api.q3cc.top/api/info
```
https://api.q3cc.top/reference/stats/info
Check if a date is a holiday using GET /api/holidays
The /api/holidays endpoint determines if a specific date is a holiday, a regular day, or a makeup workday based on UTC+8. If no date is provided, it defaults to today. The supported date range is from 2020-01-01 to 2026-12-31.
Query Parameters:
- y (Year), m (Month), d (Day): Must be provided together to query a specific date.
- type: Optional. Determines the response format. If omitted, the API returns a JSON object.
  pithy: Returns a short text status.
  alarm: Returns a work/vacation status.
Error Codes:
- 400 Bad Request: Occurs if y, m, and d are not all provided, if the date is invalid, or if the date is outside the supported range.
- 405 Method Not Allowed: Only GET and HEAD methods are supported.
```
# Query today's status
curl "https://api.q3cc.top/api/holidays"

# Query a specific date (e.g., 2025-10-01)
curl "https://api.q3cc.top/api/holidays?y=2025&m=10&d=1"
```
https://api.q3cc.top/reference/calendar/holidays