节日/节气 API 服务

根据日期自动返回农历节日、公历节日或二十四节气信息

快速开始

最简单的使用方式，直接在 HTML 中引用：

<img src="https://festival.wifilu.com/festival.php" alt="今日节日">

默认返回 302 重定向到对应的节日/节气图片。

以上图片由 API 实时返回

API 参数

参数	类型	必填	默认值	说明
`format`	string	否	重定向到图片	返回格式：json, text, url
`date`	string	否	当天	指定日期，格式：YYYY-MM-DD
`region`	string	否	`s`	地区：n(北方), s(南方)，影响小年日期
`url`	string	否	配置值	自定义图片服务器地址
`type`	string	否	空	图片分类路径
`num`	string	否	随机	图片编号：1, 2, 或 month

返回格式

1. 默认格式（重定向到图片）

直接访问 API 地址，返回 302 重定向到对应的节日/节气图片。

GET https://festival.wifilu.com/festival.php

HTTP/1.1 302 Found
Location: https://festival.wifilu.com/images/大寒2.webp

2. format=json

返回 JSON 格式的完整节日信息。

GET https://festival.wifilu.com/festival.php?format=json

{
    "date": "2026-01-29",
    "year": 2026,
    "month": 1,
    "day": 29,
    "weekday": "四",
    "lunar_year": "2025",
    "lunar_month": "十二月",
    "lunar_day": "十一",
    "festival": "",
    "solar_term": "大寒",
    "display_name": "大寒",
    "region": "s"
}

3. format=text

返回纯文本格式，便于阅读。

GET https://festival.wifilu.com/festival.php?format=text

日期：2026-01-29
星期：四
农历：2025年十二月十一
节日：
节气：大寒
显示：大寒

4. format=url

仅返回图片 URL，便于前端自定义处理。

GET https://festival.wifilu.com/festival.php?format=url

https://festival.wifilu.com/images/大寒2.webp

使用示例

查询特定日期

GET https://festival.wifilu.com/festival.php?format=json&date=2025-01-29

北方小年

GET https://festival.wifilu.com/festival.php?format=json&date=2025-01-22&region=n

指定图片编号

GET https://festival.wifilu.com/festival.php?num=1

图片 URL 构造规则

所有图片均返回 WebP 格式，不可指定其他格式。

参数 `id` 值	图片路径格式	示例
`month`	`$url/$type/m_{$currentMonth}{$num}.$imgtype`	.../calendar/m_121.webp
`1` 或 `2`	`$url/$type/$festival{$id}.$imgtype`	.../calendar/春节1.webp
其他值	`$url/$type/$festival{$num}.$imgtype`	.../calendar/立春2.webp
`$type` 为空	`$url/$festival{$num}.$imgtype`	.../清明1.webp

变量解释：
$url：基础 URL (如 https://festival.wifilu.com/images/)
$type：URL 参数 type
$festival：计算出的节日或节气名称 (如 春节, 立春)
$num：代码内随机生成的 1 或 2
$id：URL 参数 num 或 type
$currentMonth：当前月份 (如 01, 12)

响应状态码

状态码	说明
`200 OK`	请求成功（json/text/url 格式）
`302 Found`	重定向到图片地址（redirect 格式）
`400 Bad Request`	参数错误（如日期格式不正确）
`500 Internal Server Error`	服务器内部错误

支持的节日

农历节日

春节、元宵节、二月二、端午节、七夕节、中秋节、重阳节、腊八、除夕、小年（南/北方）

公历节日

元旦、劳动节、青年节、教师节、九一八、国庆节、母亲节、父亲节

二十四节气

立春、雨水、惊蛰、春分、清明、谷雨、立夏、小满、芒种、夏至、小暑、大暑、立秋、处暑、白露、秋分、寒露、霜降、立冬、小雪、大雪、冬至、小寒、大寒

注意：本服务使用重定向模式返回图片，不会代理图片内容，服务器压力最小，推荐生产环境使用。

鸣谢： 感谢原开发者：Guangran (https://www.grbj.cn)