# Readus Open Data API

> YouTube 影片 × 頻道數據 × 字幕 × AI 摘要
> 版本：1.0 | OpenAPI spec: https://aura.readus.org/openapi.json

## 數據品質聲明

字幕與摘要由 AI 生成（best-effort），可能含錯誤。所有回應帶 X-Data-Quality: best-effort header。

## 取得 API Key

前往 https://readus.org/developer 申請 API Key（r_xxx）或 AI 代理 token（agt_xxx）

## 兩種存取層

### 1. 免費輪詢（不扣積分，rate limit 60次/小時）

# 查頻道新影片（since = unix timestamp，預設24小時前）
GET https://aura.readus.org/api/v1/channels/{channel_uuid}/new-videos?since=1748736000
Authorization: Bearer YOUR_TOKEN

# 查訂閱頻道所有新影片
GET https://aura.readus.org/api/v1/me/subscriptions/new-videos?since=1748736000
Authorization: Bearer YOUR_TOKEN

### 2. 付費讀取（按回應 bytes 計費，R幣）

# 全文搜尋（ES BM25）
GET https://aura.readus.org/api/v1/fulltext?q=關鍵字&size=20&type=VideoContent
Authorization: Bearer r_YOUR_KEY
# type 可選：VideoContent（字幕）| Message（聆轉文章）| 不傳=全部

# 完整內容（AI 寫作用）
GET https://aura.readus.org/api/v1/context?q=關鍵字&size=5&type=VideoContent
Authorization: Bearer r_YOUR_KEY

# GraphQL（深度查詢）
POST https://aura.readus.org/graphql
Authorization: Bearer r_YOUR_KEY
{ searchVideos(keyword: "NVIDIA", first: 10) { title youtubeVideoId channelTitle uploadDate } }
{ searchArticles(keyword: "AI", first: 10) { title description token } }

## 計費

- 單位：R（Reauds）= 回應 JSON 每 10,000 bytes
- 新帳號：10,000 R；每月補發 5,000 R
- 回應 header：X-Credits-Consumed、X-Credits-Remaining

## Rate Limit

| 端點類型 | 上限 | Headers |
|---------|------|---------|
| 免費輪詢 | 60次/小時 | X-RateLimit-Limit/Remaining/Reset |
| 付費讀取 | 1000次/小時 | X-RateLimit-Limit/Remaining/Reset |

## 服務能力

GET https://aura.readus.org/api/v1/capabilities （無需認證，機器可讀）

## 授權

CC BY-NC-SA 4.0。AI 生成內容基於公開影片字幕。