# 昔枢 CyreneAPI

> 时间、天气、语录，加上几个随手能用的小工具，都收在同一个域名下。不用注册，地址写对就能调。

- 站点：https://api.cyrene.hk/
- baseUrl：https://api.cyrene.hk（路径以 /v1/ 开头，全部 GET，返回 JSON；自己部署时换成自己的地址，路径不变）
- 接口规范：https://api.cyrene.hk/v1/openapi.json —— 唯一的真相；站点所有页面与本文都从它来
- 接口总览：https://api.cyrene.hk/docs （每条接口另有自己的页面，如 https://api.cyrene.hk/docs/v1-weather）
- 使用说明：https://api.cyrene.hk/guide
- 健康与模块：https://api.cyrene.hk/v1/health （modules 字段说明哪些模块已启用）

## 接口要点（按类目）

- 时间 `/v1/time?tz=Asia/Shanghai`、`/v1/time/convert`、`/v1/almanac`（农历，暂未开放）
- 天气 `/v1/weather?place=nanan&days=5` —— 地名解析 + 小米天气，含 matched_by 与 confidence
- 语录 `/v1/quote?category=&count=&daily=` —— count=1 返回对象，count>1 返回数组
- 文本 `/v1/text/base64`、`/v1/text/hash`
- 转换 `/v1/convert/json`、`/v1/image/qrcode`
- 杂项 `/v1/health`、`/v1/openapi.json`、`/v1/misc/date-diff`、`/v1/misc/random`、`/v1/district`
- `/api/v1/*` 是与 `/v1/*` 等价的老地址，两个都能跑

## 约定

- 鉴权：不用注册，不用 API Key 或 Cookie，也没有要传的身份参数。
- 错误：`{"error":{"code","message","hint"}}`；code 取 bad_request / not_found / rate_limited / module_disabled / upstream_error / internal。
- 限流：按类目每分钟计数 —— 通用 30、时间 60、天气 20、语录 10、health 不限。超了回 429，带 Retry-After。
- 缓存头：no-store（时间、health）、public, max-age=300（天气）、public, max-age=60 或 600（语录）。

## 数据与许可

- 时间与时区由服务本机计算；天气来自小米公开接口，地名索引由脚本实抓生成，街道级查询用所在区县的气象站；行政区划取自公开的区划数据。
- 天气只覆盖中国大陆，街道微气候不一定和区县站一模一样。
- 上游不可用时返回 502 upstream_error，不会编造数据。
- 许可证 GPL-3.0-only。

## 源码

Source: https://github.com/Cyrene2008/CyreneAPI （GPL-3.0-only）