后台接口参考（/api/*）
这份文档写的是运营后台自己用的接口，供运维/脚本调用。
给第三方对接请用 /v1/*（见 api.md）。/api/* 是内部接口：字段会随后台改版而变， 而且能改配置、能重启进程，权限比 /v1 大得多。
1. 约定
- 基础地址：
http://<服务器IP>:8010，公网是 https://szr.dzhan.cc
- 返回：
{"ok": true, ...} 或 {"ok": false, "error": "原因"}
- 配了
ADMIN_TOKEN 之后：写操作（POST/PUT/DELETE）和大部分读操作都要口令
curl -X POST http://127.0.0.1:8010/api/anchors/xiaozhi/open \
-H "X-Admin-Token: <ADMIN_TOKEN>"
# 读一个敏感接口也要口令（否则 401）
curl -H "X-Admin-Token: <ADMIN_TOKEN>" \
https://szr.dzhan.cc/api/anchors/xiaozhi/api
- 不需要口令的读接口只有四个（观众端/首页真正用到的）：
/api/health、/api/anchors（列表）、/api/token、/api/admin/auth
- 其余
/api/* 的 GET 一律要口令——因为这些会暴露配置、备份、知识库、Key 前缀与用量。
- 判断当前要不要口令：
GET /api/admin/auth → {"required": true/false, "ok": ...}。
公网入口除了普通 HTTP/SSE，还把 LiveKit 信令挂在同一个域名的 /rtc 上 （平台内部反代到 7880），所以第三方不需要第二个域名。
2. 总览
2.1 页面与静态资源
| 方法 | 路径 | 说明 |
|---|
| GET | / | 观众端首页（主播列表） |
| GET | /stage?anchor=<id> | 直播间页面 |
| GET | /admin | 运营后台页面 |
| GET | /docs · /docs/{name} | 文档站点（/docs/manual.md 等） |
| GET | /embed · /embed.js | 嵌入式直播间（重定向到 /stage?embed=1）与 SDK |
| GET | /favicon.ico | 空响应 |
2.2 健康与鉴权
| 方法 | 路径 | 说明 |
|---|
| GET | /api/health | 服务健康、版本、LiveKit 连通性、数据库状态 |
| GET | /api/admin/auth | 是否需要口令、当前口令是否正确 |
2.3 主播
| 方法 | 路径 | 说明 |
|---|
| GET | /api/anchors | 主播列表（含 live、api.enabled、api.keys 数） |
| GET | /api/anchors/{id} | 单个主播的完整配置 + 派生字段 + 运行态摘要 |
| GET | /api/anchors/{id}/config | 与上者相似，偏配置视图 |
| PUT | /api/anchors/{id}/config | 保存配置（校验 → 备份 → 原子写；?replace=1 全量替换） |
| GET | /api/anchors/{id}/backups | 配置历史备份列表 |
| POST | /api/anchors/{id}/restore | 从备份恢复（body: {"backup": "文件名"}） |
| POST | /api/anchors/{id}/restart | 重启该主播进程（不停播状态） |
| GET | /api/anchors/{id}/participants | 房间里的参与者（观众/值守号/agent） |
2.4 开播与运行态
| 方法 | 路径 | 说明 |
|---|
| POST | /api/anchors/{id}/open | 开播（建房 + 值守号入房 + 派单） |
| POST | /api/anchors/{id}/close | 停播（销毁房间） |
| GET | /api/anchors/{id}/state | 运行态：阶段/段落/句号/队列/判据/BGM/弹幕统计 |
| POST | /api/anchors/{id}/control | 运营指令：say / skip / pause / resume / reload / next_show / music |
| GET | /api/token?anchor=<id> | 观众端 LiveKit token（公开） |
control 的请求体：
{"cmd": "say", "text": "跟大家打个招呼"}
{"cmd": "music", "enabled": true, "gain_when_silent": 0.9, "gain_when_speaking": 0.3, "track": "builtin:synthwave"}
2.5 知识库
| 方法 | 路径 | 说明 |
|---|
| GET | /api/anchors/{id}/knowledge/health | 连通校验（向量库/应用/embedding 是否可用） |
| GET | /api/anchors/{id}/knowledge/preview?q=<问题> | 检索预览（返回命中片段与分数） |
| GET | /api/anchors/{id}/knowledge/documents | 该知识库的文档列表 |
| GET | /api/knowledge/datasets | FastGPT 里的数据集列表（配置时选） |
2.6 本场直播（节目单）
| 方法 | 路径 | 说明 |
|---|
| POST | /api/anchors/{id}/show/generate | 生成节目单（异步任务，body: theme/minutes/sections/style/auto_approve） |
| GET | /api/anchors/{id}/show/tasks/{task_id} | 生成进度 |
| GET | /api/shows?anchor=<id> | 节目单列表 |
| GET | /api/shows/{show_id} | 节目单详情（段落 + 脚本） |
| POST | /api/shows/{show_id}/approve | 审核通过（body 可传 segments 只通过部分） |
| PUT | /api/shows/{show_id}/segments/{seg_id} | 改某段的标题/脚本/状态 |
2.7 背景音乐
| 方法 | 路径 | 说明 |
|---|
| GET | /api/anchors/{id}/music/tracks | 可用曲目（内置 + assets/bgm/ 下的文件） |
2.8 每主播对外 API（新）
| 方法 | 路径 | 说明 |
|---|
| GET | /api/anchors/{id}/api | 接入信息：开关、Key 列表、弹幕源、24h 用量、可复制示例 |
| PUT | /api/anchors/{id}/api | 开/关该主播的对外 API（body: {"enabled": true}） |
| POST | /api/anchors/{id}/keys | 生成该主播专用 Key（明文只返回一次） |
| DELETE | /api/anchors/{id}/keys/{key_id} | 吊销该主播的某把 Key |
2.9 音色试听
| 方法 | 路径 | 说明 |
|---|
| GET | /api/tts/voices | 音色下拉清单（名称/性别/场景/默认试听文本/当前 TTS 模式） |
| POST | /api/tts/preview | 用指定音色合成一句样例，直接返回 audio/wav |
POST /api/tts/preview 请求体：
{"voice_type": "zh_female_vv_uranus_bigtts", "text": "可选，留空用默认，最多 60 字", "speed_ratio": 1.0, "pitch_ratio": 1.0}
- 返回：
audio/wav（16bit 单声道），带 X-Preview-Cached（1=命中本地缓存）、X-Preview-Ms、X-Preview-Seconds。
- 错误：400 参数不合法；401 需要运营口令；503 未配置豆包凭据 / 供应商不是 volcengine；502 供应商失败（音色未授权等，文案原样透出）；504 合成超时。
- 该接口是 POST：会消耗供应商合成配额，所以和写操作一样受
ADMIN_TOKEN 保护；结果缓存在 data/tts_preview/。
- 当前
bidir 模式下语速/音高不会发给供应商（只有 http 模式生效），试听听到的就是直播真实效果。
3. 关键示例
3.1 看某个主播能不能播
curl http://127.0.0.1:8010/api/anchors/xiaozhi/state
{"ok":true,"anchor_id":"xiaozhi","live":true,"room":"vtb-xiaozhi",
"stage":{"phase":"script","speaking":true,"segment_title":"开场","sentence_index":3,"total_sentences":34},
"music":{"on":true,"gain":0.22,"titles":["燃 · Synthwave 128"]},
"danmaku":{"accepted":6,"duplicate":0,"filtered":0,"dropped":0}}
3.2 让主播说一句（会打断当前内容）
curl -X POST http://127.0.0.1:8010/api/anchors/xiaozhi/control \
-H "X-Admin-Token: <token>" -H 'Content-Type: application/json' \
-d '{"cmd":"say","text":"休息一下，马上回来"}'
3.3 生成一份节目单并等待完成
# 1) 发起
TASK=$(curl -s -X POST http://127.0.0.1:8010/api/anchors/xiaozhi/show/generate \
-H "X-Admin-Token: <token>" -H 'Content-Type: application/json' \
-d '{"theme":"新人最常问的问题","minutes":20,"sections":4}' | jq -r .task_id)
# 2) 轮询
curl -s http://127.0.0.1:8010/api/anchors/xiaozhi/show/tasks/$TASK | jq '{status,progress,show_id}'
# 3) 审核通过并让主播用上
curl -s -X POST http://127.0.0.1:8010/api/shows/$SHOW_ID/approve -H "X-Admin-Token: <token>"
3.4 给某个主播开一个"第三方专用"入口
# 1) 打开该主播的对外 API
curl -X PUT http://127.0.0.1:8010/api/anchors/xiaozhi/api \
-H "X-Admin-Token: <token>" -H 'Content-Type: application/json' -d '{"enabled":true}'
# 2) 生成一把只能操作它的 Key（明文只出现一次）
curl -X POST http://127.0.0.1:8010/api/anchors/xiaozhi/keys \
-H "X-Admin-Token: <token>" -H 'Content-Type: application/json' \
-d '{"name":"某合作方"}'
# → {"ok":true,"key":{"id":"k_xxx","secret":"vt_live_xxx","anchor_id":"xiaozhi",...}}
4. /api/* 与 /v1/* 的区别
| /api/*（后台） | /v1/*（第三方） |
|---|
| 鉴权 | ADMIN_TOKEN（可选，配了才校验） | API Key（Authorization: Bearer vt_live_…），每主播可单独绑定 |
| 权限范围 | 全平台：所有租户、所有主播、能改配置、能重启 | 按租户隔离；每主播 Key 只能碰绑定的那个主播 |
| 稳定性 | 随后台改版可能变 | 版本化，字段变更会提前说明 |
| 用途 | 运营操作、运维脚本 | 第三方集成、对外交付 |
| 计量 | 不记调用日志 | 每个请求落 api_requests，可按主播统计 |