# 灵机 · 开放平台 API 文档

Base URL：`https://feedhub.cc`

所有 `/api/v1/*` 接口需在请求头携带 API Key：

```
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API Key 在「我的 → 集成与订阅」中创建，**创建后仅显示一次完整密钥**，请妥善保存。

---

## 0. 语言与地域

列表类接口支持按语言投影文案（标题 / 摘要 / 分类展示名）。解析优先级：

1. 查询参数 `lang`（`zh` / `en`）
2. 查询参数 `locale`（如 `zh-CN`、`en-US`）
3. 请求头 `Accept-Language`
4. 默认 `zh`

筛选分类仍用稳定 id（`ai-models` 等）；展示名见响应字段 `category_label` 或 `GET /api/v1/categories`。

---

## 1. 获取分类目录

`GET /api/v1/categories`

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| lang | string | `zh` | `zh` / `en` |
| locale | string | - | 语言标签，可替代 `lang` |

响应：

```json
{
  "content_lang": "en",
  "count": 5,
  "items": [
    { "id": "ai-models", "label": "Models" },
    { "id": "ai-products", "label": "Products" },
    { "id": "industry", "label": "Industry" },
    { "id": "paper", "label": "Papers" },
    { "id": "tip", "label": "Tips" }
  ]
}
```

---

## 2. 获取资讯列表

`GET /api/v1/items`

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| mode | string | `selected` | `selected`（精选）/ `all`（全部） |
| category | string | - | 可选：`ai-models` `ai-products` `industry` `paper` `tip` |
| lang | string | `zh` | 内容语言 `zh` / `en` |
| locale | string | - | 如 `en-US`，可替代 `lang` |
| since | ISO8601 | - | 返回该时间之后的条目 |
| q | string | - | 关键词搜索（中英标题/摘要 + 来源） |
| take | int | 50 | 每页 1-100 |
| cursor | string | - | 分页游标（上一页返回的 `nextCursor`） |

响应：

```json
{
  "content_lang": "en",
  "items": [
    {
      "id": "...",
      "title": "English title when lang=en",
      "title_zh": "中文标题",
      "title_en": "English title",
      "summary": "...",
      "summary_zh": "...",
      "summary_en": "...",
      "category": "industry",
      "category_label": "Industry",
      "content_lang": "en",
      "url": "...",
      "source": "...",
      "score": 88,
      "imageUrl": "...",
      "publishedAt": "2026-07-03T08:00:00Z",
      "likeCount": 12,
      "readCount": 23140
    }
  ],
  "nextCursor": null,
  "hasNext": false,
  "count": 1
}
```

说明：

- `title` / `summary` 为按请求语言投影后的展示字段；英译缺失时回退中文。
- `title_zh` / `summary_zh` / `title_en` / `summary_en` 为双语存根，便于客户端离线切换。
- `category` 为稳定 id；`category_label` 为当前语言下的展示名。

支持 `If-None-Match` ETag 协商，命中返回 `304`（ETag 含语言维度）。

---

## 3. 获取最新日报

`GET /api/v1/daily`

返回当日 AI 日报（导读 + 板块 + 快讯）。

## 4. 获取指定日期日报

`GET /api/v1/daily/:date`

`date` 格式 `YYYY-MM-DD`。

## 5. 日报归档索引

`GET /api/v1/dailies?take=30`

返回最近 N 天日报索引（`take` 1-180）。

## 6. 健康检查

`GET /api/v1/health`

```json
{ "ok": true, "items": 1744, "dailies": 30, "apiVersion": "v1" }
```

---

## 错误格式

非 2xx 响应体：

```json
{ "error": "invalid take (must be integer 1-100)" }
```

常见状态码：`400`（参数错误）/ `401`（API Key 缺失或无效）/ `404`（无数据）/ `429`（限流）。

## 示例（curl）

```bash
curl -H "Authorization: Bearer sk_xxx" \
  "https://feedhub.cc/api/v1/items?mode=selected&take=10&lang=en"

curl -H "Authorization: Bearer sk_xxx" \
  "https://feedhub.cc/api/v1/categories?lang=zh"
```