文本自动生成播客 API 文档

这是基于 Cloudflare Workers、Durable Objects、D1、R2 和火山语音 API 的播客生成后端。用户提交文本后，系统会生成播客脚本、拆分节目段落、合成音频，并可发布到个人 RSS。

认证方式

POST /api/episodes

功能：创建播客节目生成任务。

请求体示例：

{
  "title": "AI 产品周报",
  "source_text": "粘贴需要生成播客的原始文本……",
  "language": "zh-CN",
  "style": "conversation",
  "long_text_mode": "compact",
  "group_id": "grp_existing",
  "speakers": [
    {
      "id": "host",
      "name": "主持人",
      "voice": "zh_female_shuangkuaisisi_uranus_bigtts"
    },
    {
      "id": "guest",
      "name": "嘉宾",
      "voice": "zh_male_m191_uranus_bigtts"
    }
  ],
  "is_public": false
}

如只传 voice，系统会按单人播客处理；传入 speakers 时会按角色分段并使用对应音色合成。

分组：登录用户可传 group_id 加入已有分组，或传 new_group_name 创建/复用同名分组；匿名用户分组由客户端本地保存。

长文本：source_text 最多 200,000 字符；超过 50,000 字符时，后台会按语义单元切成连续 chunk，带上邻接原文上下文辅助衔接，再按原文顺序拼接。long_text_mode 支持 compact 和 expanded，默认 compact；前者强压缩，后者保留更多细节。expanded 模式下，中等长度文本会提前拆成连续 section，以降低单次大模型请求超时风险。

响应示例：

{
  "episode_id": "ep_123456",
  "status": "queued",
  "session_token": "8f9e..."
}

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

GET /api/episodes/:id

功能：查询节目生成状态、脚本和音频入口。

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

响应示例：

{
  "episode": {
    "id": "ep_123456",
    "title": "AI 产品周报",
    "status": "synthesizing",
    "script_text": "欢迎收听……",
    "audio_url": null,
    "is_public": false,
    "created_at": "2026-04-30T00:00:00Z"
  }
}

POST /api/episodes/:id/retry

功能：将失败的节目重新扣减额度并重新加入生成队列。仅节目拥有者或携带匹配 session_token 的请求可操作。

GET /api/episodes/:id/audio

功能：播放或下载生成完成的 MP3 音频，支持 Range 请求头。

GET /api/episodes

功能：获取当前登录用户的节目库。

查询参数：

GET /api/episode-groups

功能：列出当前登录用户的节目分组和每组节目数。

POST /api/episode-groups

功能：创建分组；同名会返回已有分组。

PATCH /api/episode-groups/:id

功能：重命名分组。

DELETE /api/episode-groups/:id

功能：删除分组并将组内节目移为未分组，不删除节目。

PATCH /api/episodes/:id/group

功能：移动节目到已有分组、新建分组，或传 {"group_id": null} 移出分组。

DELETE /api/episodes/:id

功能：删除指定节目、节目段落和 R2 音频，仅限登录用户操作自己的节目。

GET /api/feeds/:feedId.xml

功能：生成公开节目的 Podcast RSS。登录用户默认使用自己的 user_id 作为 feedId。

GET /api/voices

功能：返回火山语音可用音色配置；/api/speakers 仍返回同一份数据，便于本地调试。

GET /api/quota

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

GET /api/health

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

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

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

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

节目状态枚举值：draft、queued、scripting、synthesizing、composing、done、failed。