# Podcast API 文档

## 1. 服务信息
- 服务：Podcastfy API
- 框架：FastAPI
- 前端服务入口：window.PodcastApi
- 文档版本：v1.1（2026-03-19，已对齐当前前端调用实现）
- 主要基地址：/podcast-api

## 2. 当前前端调用总览（重要）
前端现在采用“按模式优先命中独立接口 + 自动回退通用接口”的策略。

### 2.1 模式到接口映射
| 前端 mode | 主调用接口 | 回退接口（仅 404/405 时） | 请求体类型 |
|---|---|---|---|
| text_image（UI 文案为 Text） | POST /podcast/generate-text | POST /podcast/generate | JSON |
| url | POST /podcast/generate-url | POST /podcast/generate | JSON |
| topic | POST /podcast/generate-topic-research | POST /podcast/generate | JSON |
| pdf | POST /podcast/generate-pdf | POST /podcast/generate-multipart | multipart/form-data |

### 2.2 回退触发条件
- 仅在主接口响应为 404 或 405 时触发回退。
- 其它响应（例如 400、401、422、500）不做接口回退，直接走错误提示。

### 2.3 多基座探测顺序
前端会在以下基座顺序尝试请求（去重后）：
1. 已锁定语音基座（lockedVoiceBase）
2. 上次成功基座（preferredBase）
3. 配置基座（APP_CONFIG.PODCAST_API_BASE 或 /podcast-api）
4. /podcast-api
5. https://linearmelody.com/podcast-api
6. http://100.119.117.121:9055
7. http://100.119.117.121:9060

## 3. 生成接口

### 3.1 模式化快捷接口（前端优先）
- POST /podcast/generate-text
- POST /podcast/generate-url
- POST /podcast/generate-topic-research
- POST /podcast/generate-pdf

### 3.2 通用接口（前端回退）
- POST /podcast/generate
- POST /podcast/generate-multipart

### 3.3 同步接口（后端可用，前端当前未直接调用）
- POST /generate

## 4. 前端请求字段规范

### 4.1 通用 JSON 字段（主要）
- mode: text_image / url / topic / pdf
- source_url
- source_text
- topic
- role_host_1
- role_host_2
- style
- language
- word_count
- tts_model
- question_voice
- answer_voice

### 4.2 兼容字段（别名）
为兼容不同后端版本，前端会同时发送别名字段：
- roles_person1 / roles_person2
- conversation_style
- output_language
- length_words
- wordCount
- tts / tts_engine
- voice_question / voice_answer
- voice_host_1 / voice_host_2
- voice_person1 / voice_person2
- voice
- voices（JSON 字符串）

### 4.3 multipart 附件字段
- pdf_file（当前前端仅上传该附件）

说明：Podcast Image 输入已从前端移除，不再上传 image_file。

## 5. 用户身份透传
当前前端会优先从 AuthClient 当前会话解析用户身份，并向播客服务透传以下身份字段：
- email
- user_email
- userEmail

说明：
- 当前主站登录态已经迁移到后端 Bearer token + refresh cookie，但播客微服务仍主要兼容 email 身份透传。
- 前端当前未主动发送 user_id / userId。若播客后端强依赖 user_id，需要在服务层补充映射或在后端兼容 email 身份。
- 对于 /podcast/download/{request_id} 这类下载地址，前端仍可能附加 email/userEmail 查询参数以兼容旧服务行为，移除前应先确认播客后端不再依赖这些字段。

## 6. 任务查询与下载

### 6.1 查询状态
- 方法：GET
- 路径：/podcast/status/{request_id}
- 常见状态：queued / processing / completed / error

### 6.2 下载音频
- 方法：GET
- 路径：/podcast/download/{request_id}
- 兼容说明：当前前端可能在下载 URL 上追加 email/userEmail 查询参数，作为旧播客服务的身份辅助信息。

### 6.3 前端完成态处理
若生成接口直接返回 completed 或可用音频地址，前端会跳过轮询并直接展示音频。

## 7. AI 辅助接口

### 7.1 播客 AI 辅助
- 方法：POST
- 路径：/ai-assist
- 前端固定 product=podcast

## 8. 语音能力接口

### 8.1 音色选项
- 方法：GET
- 路径：/podcast/voice-options

### 8.2 音色预览
- 方法：GET
- 路径：/podcast/voice-preview
- 参数：voice、text、model、refresh、language

### 8.3 语音基座锁定逻辑
voice-options 或 voice-preview 成功后，会锁定当前可用基座，后续优先走该基座，降低跨节点不一致问题。

## 9. 历史与清理接口（后端能力）
- GET /podcast/history
- POST /podcast/clear-history
- POST /podcast/backfill-user-ids

说明：历史聚合与清理主要由 StudioService 调用，不在 PodcastApi 文件内直接封装。

## 10. Music 代理接口（同服务暴露）
- GET /music
- GET /api/music
- GET /history
- GET /api/history
- GET /music/{music_id}
- GET /api/music/{music_id}
- GET /download-music/{music_id}
- GET /api/download-music/{music_id}
- GET /stream/{music_id}
- GET /api/stream/{music_id}

## 11. 错误处理与可用性策略

### 11.1 响应可接受条件（前端）
前端会拒绝以下响应并继续尝试下一基座：
- 404
- >=500
- 非 JSON 响应（例如网关 HTML 页面）

### 11.2 接口选择策略总结
1. 先选 mode 对应独立接口
2. 若返回 404/405，回退通用接口
3. 若基座不可用，继续探测下一基座
4. 成功后记录 preferredBase，后续优先使用

## 12. 联调建议
1. 后端若未完整部署四个快捷接口，至少保证 /podcast/generate 与 /podcast/generate-multipart 可用。
2. 若后端严格校验 user_id，需与前端统一身份透传策略（当前前端默认 email 三字段）。
3. 建议在网关层避免返回 HTML 错误页，确保 JSON 错误结构，便于前端准确提示。