🎙️ 文本转播客 API 文档

POST /api/tts （同 /api/tasks）

功能：创建语音合成任务。

请求体示例：

{
  "title": "第 42 期节目",
  "text": "将这段文本转换为音频……",
  "lang": "zh",
  "voice": "zh_female_qingxin",
  "emotion": "happy",
  "is_public": false
}

响应示例：

{
  "task_id": "task_123456",
  "status": "queued",
  "message": "Task created successfully",
  "session_token": "8f9e...",
  "user_id": "user_abc" // 登录用户会包含该字段
}

响应头会包含 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 以便前端获知配额。

GET /api/tasks/:id （同 /api/status/:id）

功能：查询任务状态。

匿名访问：在请求 URL 中携带 ?session_token=<token>。

响应示例：

{
  "task": {
    "id": "task_123456",
    "title": "第 42 期节目",
    "status": "processing",
    "audio_url": null,
    "is_public": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:03:00Z"
  }
}

当任务完成且为私有任务时，接口会返回一个带有效期的签名音频链接。

GET /api/tasks/:id/audio

功能：下载生成完成的音频文件，支持 Range 请求头用于断点续传。

访问条件：携带 JWT 或在查询参数中附带 session_token。

GET /api/tasks/:id/audio/stream

功能：实时拉取 Durable Object 生成的音频分片，适合实时播放或进度展示。

说明：接口会返回一个 ReadableStream，每次轮询数据库的新分片并推送给客户端，直到任务状态变为 done 或 failed。

GET /api/tasks

功能：获取当前登录用户的任务列表。

查询参数：

• page - 页码，默认 1。
• limit - 每页数量，默认 20，最大 100。
• status - 任务状态过滤（queued / processing / done / failed）。

DELETE /api/tasks/:id

功能：删除指定任务及其音频，仅限登录用户操作自己的任务。

GET /api/quota

功能：查看当前身份（登录用户或 IP）的剩余配额与重置时间。

GET /api/feed/:user_id

功能：生成指定用户公开任务的播客 RSS，响应类型为 application/rss+xml。

POST /api/rss/subscribe

功能：为当前登录用户新增外部 RSS 订阅。

搭配 GET /api/rss/subscriptions、DELETE /api/rss/subscribe/:id 管理订阅列表。

GET /api/speakers

功能：返回完整的音色/情感配置表，可直接展示给前端选择。

响应包含 voices、emotion_labels 等字段，覆盖火山引擎豆包语音的全部音色。

GET /api/health

功能：检查 Worker 运行状态，返回时间戳与版本号。

GET /api/auth/oauth/{google|github}/start

功能：发起 OAuth 登录，必须提供 redirect_uri。

回调地址 /api/auth/oauth/{provider}/callback 会验证授权并重定向到原始回调地址，同时附带 JWT。