---
name: readcue-audiobook
description: Turn a novel or manuscript into a multi-role, emotion-directed audiobook on 读声 Readcue (readcue.top) on the user's behalf — create the project, cast voices, run the one-click pipeline, report the finished MP3, and apply the user's revision notes. Use when the user asks to make an audiobook / 有声书 / 配音 with Readcue or gives a readcue.top API token.
---

# 读声 Readcue：代用户制作有声书

你代表用户操作 https://readcue.top。用户只想听结果：尽量自己完成，只在需要用户做决定时才打扰（选角确认、额度不足、文本版权存疑）。

## 准备
- 向用户要一个 API 令牌（形如 `rc_...`）。用户在读声网页的「账号设置 → AI 助手接入」里创建。不要把令牌回显到对话里，也不要写进文件。
- 所有请求都用 `https://readcue.top/api` 作为基础地址，并带请求头 `Authorization: Bearer <令牌>`。
- 令牌只能访问签发账号拥有的项目及其片段、候选、音频和导出。管理员签发的个人令牌也不能访问其他账号的作品；管理功能、账号设置和令牌管理须由用户在网页登录后操作。
- 每次轮询至少间隔 10 秒。每个令牌每分钟最多 120 次请求。

```bash
RC="https://readcue.top/api"; AUTH="Authorization: Bearer $READCUE_TOKEN"
curl -s -H "$AUTH" "$RC/usage"          # 今日额度
```

## 标准流程

1. **确认文本**：用户提供的是正文（UTF-8，单个项目最多 50000 字符）。超过时按章节拆成多个项目，每章一个。文本必须是用户有权使用的。
2. **创建项目**：
   ```bash
   curl -s -H "$AUTH" -H 'content-type: application/json' -X POST "$RC/projects" \
     -d '{"text":"<正文>"}'
   ```
   `title` 可省略、null或空白，默认取正文首个可见非空行的前30个Unicode字符，过长加“…”；兜底“未命名作品”。已知书名或TXT文件名时可显式传入，非空标题最多200字符，不静默截断。命名不改原稿或生成输入，不调用模型或入队。创建后改名使用 `PATCH $RC/projects/$PID`，body `{"expected_title":"读取时的原书名","title":"新书名"}`；新名称须含可见字符且最多200字符。409表示原名已变化，先GET核对并保留用户草稿，不能盲目覆盖；个人令牌仍限本人项目。
3. **预检并启动一键成书，在选角处暂停**：先 `GET $RC/projects/$PID/autopilot/preflight`，核对 `start_fingerprint`、范围和准入。生成一次 UUID 并在 POST 前保存原键、完整 body、预检、范围与策略（不保存令牌）。以下为新版接口契约，实际目标服务须已支持这些字段：
   ```bash
   curl -s -H "$AUTH" "$RC/projects/$PID/autopilot/preflight"
   curl -s -H "$AUTH" -H 'content-type: application/json' -X POST "$RC/projects/$PID/autopilot" \
     -d '{"request_key":"<本次授权UUID>","fingerprint":"<预检start_fingerprint>","emotion":"standard","pause_for_voices":true}'
   ```
   - 按小说类型加 `"genre":"female"`（女频）或 `"genre":"male"`（男频），系统会先按题材预设给角色和旁白配好音色，你在下一步只需检查、替换不合适的。
   - 默认 `health_retry=false`：规则体检只检查已有音频，不追加 TTS。额外重做须先展示并取得用户对范围、次数、费用承担方及平台报价上限的明确授权，不能因“自动成书”自行开启。
   - 启用时先读取 `GET $RC/projects/$PID` 的完整片段 ID/修订和 preflight 的 `own_key`，随同启动请求提交 `{"health_retry":true,"health_retry_scope":[{"segment_id":"<本书片段UUID>","revision":1}],"health_retry_credential":"platform","health_retry_max_takes":1,"health_retry_max_usd":"0.100000"}`；scope 必须列出刚核对的本书全部片段，凭据类别为 `platform` 或自有 Key 的 `owner`。范围/修订/类别不匹配返回409，须重新读取并确认，不能自动用新范围替换旧授权。
   - 每个原授权片段最多额外生成一个整段候选，只执行一轮已知报价可负担的顺序前缀。上限是额外候选数量与平台六位 USD 报价，不包括初次生成，也不是供应商实账；自有 Key 平台零报价不表示免费，其外部账单不受该 USD 上限约束。失败、持续异常或额度阻断均不自动追加付费轮次；历史只有 `health_retry=true` 而无冻结授权的流程也只检查。
4. **核对人物**：`GET $RC/projects/$PID/autopilot/$RUN`，固定原run ID。`waiting_voices` 或 `resume_requires:"voices"` 时读取实时 `speaker_review`，同时读取 `GET $RC/projects/$PID/roles`，核对 `roles.version == speaker_review.roles_version`。按角色 ID 查看 `role_examples` 和最多50条 `unassigned`，并报告全部未指派总量；日志不能代替当前人物表。识别只补未指派，仅非空高置信建议自动采用。低置信、未知、范围遗漏或识别失败，即使 `pause_for_voices=false` 也会停在确认，失败不能当作正常跳过。识别写明原因判为「不是对白」的引号内容（绰号、拟声、信件等，计入 `narration_count`）由旁白读，不单独停下；超过对白 30% 时仍会停下确认。
5. **选角**：为旁白和每个角色搜索音色：
   `GET $RC/voices?q=<关键词，如 少年 / 温柔女声 / old man>&language=zh|en|ja`
   - 按角色的性别、年龄、性格挑选，主要角色之间的音色要区分开；
   - 优先选 `task_count` 高（被用得多）的音色；
   - 不要选模仿真实名人的音色（服务端已过滤大部分）；
   - 把你的选角表（角色 → 音色名）用一句话告诉用户。用户要求先确认时，等用户回复。
   - 保留本次核对的 `speaker_review.fingerprint`。人物或对白发生变化时保留音色草稿，重新读取并明确核对后再确认，不能把轮询得到的新指纹自动配给旧确认。
   - `unassigned_count > 0` 时先处理可采用建议或手工指派；若用户明确允许本次当前全部未指派对白使用旁白，才设置 `allow_narrator_for_unassigned=true`。未知不代表没有人物，没选独立音色的角色也须说明旁白兜底。

   然后继续：
   ```bash
   curl -s -H "$AUTH" -H 'content-type: application/json' -X POST "$RC/projects/$PID/autopilot/$RUN/resume" \
     -d '{"request_key":"<本次继续命令UUID>","expected_dialogue_fingerprint":"<本次核对的fingerprint>","allow_narrator_for_unassigned":false,"voices":{"narrator":{"voice_id":"..","voice_title":".."},"roles":{"林渊":{"voice_id":"..","voice_title":".."}}}}'
   ```
   `waiting_voices` 或 `resume_requires:"voices"` 必须携带本次确认指纹、明确旁白同意与音色；在人物阶段手动暂停也保留此要求。不匹配返回409，且不会先写音色；进入生成前再核依据。只有没有人物确认要求的 `paused_quota` 或 `paused_user` 才提交 `{"request_key":"<本次继续命令UUID>"}`，不混入未经确认的新选角。命令发出前保存完整原 body。
6. **等待与控制**：每10–20秒只读轮询原 run ID：`GET $RC/projects/$PID/autopilot/$RUN`。本次进度只使用 `progress`：`generation` 分列 queued/running/ready/failed/uncertain/cancelled/not_submitted/reused_ready，另列 `adopted_segments` 与 `export.ready/status/id`；`rows` 给出固定范围、修订、原候选、复用/采用和实际块进度。`scope_known=false` 或 null 是未知，不按当前项目补零。`quota` 仅为项目当前准入，不是本次完成数；`daily_capacity` 不是完成或预算承诺。保留全部七步及 `reason`，不把未完成或取消步骤说成完成。
   - 仅按 `allowed_actions` 显示/执行 pause/resume/cancel。`paused_quota` 根据结构化 blockers 和 reset_at 核对；`paused_user` 需要用户明确恢复。`running` 仅受 concurrency 阻断时只等待空位，不重提。不承诺预算、报价或配置限制次日恢复。
   - 暂停或取消使用 `POST $RC/projects/$PID/autopilot/$RUN/pause` 或 `/cancel`，body `{"request_key":"<本次命令UUID>"}`。说明未发送的本流程任务停止并释放未发送预算，已占日额度不退；已发送请求可能完成并计费，不强行撤回。停止后不自动采用/导出，不影响独立手工任务。`control.unsent_cancelled/in_flight/unsettled_count/released_usd` 是实际控制事实。
   - 即使父流程 done/failed/cancelled，只要 `control.unsettled_count` 或 `in_flight` 仍大于0，继续只读核对原流程和子任务。不自动重放取消的子任务。
7. **交付**：
   - 把 `result.audio_url` 交给用户。这个链接需要带令牌才能下载，所以由你下载后发给用户，或者让用户登录网页在「导出」里下载。
   - 同时报告实际段数、人物、情绪和 `health` 中的重做事实：`candidate_submissions` 是额外受理候选，`completed_candidates` 才是已就绪数量；`provider_chunks` / `provider_chunks_completed` 分别是计划与已成功的供应商块数，`tts_input_utf8_bytes` 和 `quoted_usd` 是额外计划字节与平台报价。不能把已提交说成已生成或已试听。
   - 提醒用户可以在网页「跟读校对」里边听边看。



## 质量事实与人工判断

- 候选 `status` 表示生成；`review.rule_check.status` 为 `not_ready/unjudgeable/clear/partial/flagged`，并列出块覆盖和无法判断的原因。规则只用文本/时长筛语速，短文、缺时长或块证据不全不能说检查通过；不验证逐字内容、读音或听感。
- `asr.status` 是独立识别参考；失败仍可保留 ready 音频，不重跑 TTS。ASR须另行估价和明确提交，不因启用体检重做而自动开启。
- `review.human_status` 区分 `pending/confirmed/retake/unknown`；`approval_source` 区分 `manual/automatic/unknown`；`delivery_approved` 是交付依据，`segment.accepted_take_id` 是实际采用。自动采用可使交付有效，但仍是待人工听，不写人工判断历史；旧确认来源未知不能称用户听过。
- 仅根据用户实际听后的明确判断提交整段 `review` 确认；不因模型、规则或 agent 自己判断而冒充人工完整试听。明确选用已有交付依据的版本使用 `accept`，不额外制造听过记录。人工返修、未确认的 ASR 内容差异、新的采用/重开审核/重读意图会保护用户决定，旧自动任务不得覆盖。
- 重做后仍异常或生成失败会停下来待人工处理，即使关闭自动采用；先说明真实结果和费用，不新开流程偷偷补做。原候选请求、判断历史和已冻结 Export 保留。

## 独立识别与人工核对

- `GET $RC/projects/$PID/dialogue/scan` 读取全量 `dialogue_count`、`unassigned_count`、本次 `planned_count`、`omitted_count`、`output_tokens`、`reserve_usd`、独立分析次数及 `fingerprint`。1500句硬上限与输出预算共同限制本次容量；范围外不会自动补扫。
- 确认范围与预留费用后，向同一路径POST `{"request_key":"<新UUID>","fingerprint":"<上述fingerprint>"}`，只提交一次。预留不等于实际账单，AI分析次数与朗读候选提交次数分开。
- 原扫描响应明确返回后可只读轮询该已知扫描；丢失响应的恢复只用下面统一的原键 GET，不用 unrelated latest 证明原请求。`ready` 中每个请求对白都有结果，`speaker=null` 是未知；`reason/confidence` 是模型建议。`failed/uncertain/cancelled` 保留真实状态与费用事实，不自动重试。
- 采用或人工订正使用 `POST $RC/projects/$PID/dialogue/scan/apply`：`{"run_id":"<扫描UUID>","expected_roles_version":1,"accept":[{"segment_id":"<段UUID>","quote_index":0,"speaker":"<确认的人物名>"}]}`。只提交用户确认的条目，低置信不默认采纳；人工订正可使用已有姓名或明确的新名字。接口只写仍未指派、且原文/修订/上下文一致的目标，核对旧角色名与ID，返回真实 `applied/skipped/created_roles`。跳过项保留选择并人工核查，不把零采用当作完成。
- 保存成功但刷新失败不表示回滚。扫描或继续响应不确定时使用下方统一原键恢复，保留草稿；采用这类免费修改仍先只读核对实际人物/对白，不盲重发。
- 历史结果缺少完整原条件时不猜测是否可采用；到角色面板核对原文并手工处理。

## 用户提出修改时
- 先读逐句数据：`GET $RC/projects/$PID/listen`，找到用户说的那句（按文本匹配）。
- **单句说话人、情绪和停顿一起保存**：`PUT $RC/segments/$SID/sentence`，body 为 `{"index":1,"expected_revision":1,"expected_text":"<原句原样文本>","expected_tag":null,"expected_pause":"none","tag":"happy","pause":"short"}`。原修订、句子 `index/text/tag/pause` 取自刚读取的 `listen`；不要 trim 原句。只修改目标句的情绪，不会清空其他句子的手工标注。
- 同时指派对话说话人时，增加 `expected_role_id`（原 role_id，未指派为 null）和 `role_id`（新 ID 或 null）；新角色改用 `new_role_name` 加 `expected_role_id`，不要同时传非空 role_id。角色创建、指派、情绪和停顿在同一事务里成功或回滚；说话人归属作用于该句所在的整条对话行。只改情绪或旁白时省略全部说话人字段。
- 单句保存 `409` 表示原句、修订或手工标注已变化；保留草稿、读取当前内容，核对后重新编辑，不用新的原始条件自动覆盖。保存成功后的影响刷新失败不代表保存回滚；保存响应丢失时先 GET 核对，不盲目重放。
- 需要批量指派时，`GET $RC/projects/$PID/dialogue` 取 `quote_index`，再 `PUT $RC/projects/$PID/speakers`；整段情绪替换仍使用 `PUT $RC/projects/$PID/emotion/segments/$SID/cues` 并提供全部句子标注。单句返修使用上述原子接口。修改整体角色配置使用 `PUT $RC/projects/$PID/roles`，带 `expected_version` 并保留原有角色与旁白。
- 换音色：改角色表里该角色的 `voice_id` 和 `voice_title`。
- 检查修改影响：`GET $RC/projects/$PID/rework/preview`。`segments` 按段合并返修原因和参照候选，`initial_segments` 单列无 ready 音频引用的段；无音频不代表没有历史费用。
- 预览中的 `input_changed` 为 true / false / null（无法确定）；false 时仍可能有修订或明确重读要求。查看 `reasons[].code/message`、`warnings`、逐段的 `can_generate` 和 `blocked_reasons`；预览只读，生成前仍需重新估价确认整批费用。
- **只提交选定返修段**：`POST $RC/projects/$PID/batch-takes/estimate`，body 为 `{"segment_ids":["<段 UUID>"],"auto_adopt":false}`。显式列表必须非空、不重复且全部属于当前作品；当前修订在途的段会被拒绝。省略或传 null 表示默认待生成范围，它与显式列表是不同的确认范围。
- 核对 `segment_count`、`total_tts_requests`、`total_tts_input_utf8_bytes`、逐段和整批金额、`policy` 中的报价来源/有效期、`remaining_usd` 及 `reasons`。供应商多块请求数与平台按受理候选计次的额度不同；金额 null 表示未知，不能当零。`credential: "owner"` 的零金额仅表示平台不承担该笔 TTS，供应商账单由用户账户承担，须展示 `billing_note`。
- 获得费用与采用策略的授权后，用新 UUID 作为 `request_key`，向 `POST $RC/projects/$PID/batch-takes` 提交同一 `segment_ids`、同一 `auto_adopt` 和估价的 `fingerprint`。提交前改稿、音色、报价或费用来源变化会使确认失效；需要重新估价。自动采用只表示采用动作，不表示用户已听过。
- `202` 返回 `queued`、`skipped_count`、`stop_reason`；queued 是已受理候选，不代表已生成。整批受限时可能只受理前面若干段，必须报告实际数量和停止原因；零受理的公网请求返回错误。
- 响应丢失时先按下方统一恢复接口 GET 原键。只有用户明确授权重放后才用**原键和完整原内容** POST；此前未收到时可能首次受理并产生费用，查无记录不代表已拒绝。同键不能换范围、策略或指纹；重放原回执不会扩充批次。剩余段须核对历史、重新估价并明确授权新键，不能以补齐旧回执为由扩大原范围。
- 新候选的 `request_snapshot.rework_reference_take_id` 指向本次受理时有依据的旧采用候选；核对同段、ready 与音频引用后再比较。`parent_take_id` 只表示重录关系。最新候选失败或待确认时保留旧音频，不能用更早 ready 候选冒充本次成功。
- 影响原因 `adoption` 表示已有就绪返修候选等待采用决定，不表示应再次付费生成。用户实际完整试听并确认后，才对当前修订候选调用 `PUT $RC/takes/<take_id>/review`，提供 `expected_revision`、当前 `expected_version`、`item_id:null`、`decision:"confirmed"`。仅选版本时，已有 `review.delivery_approved:true` 可 `POST $RC/takes/<take_id>/accept`，不会写人工听过；保留较早的当前有效采用版本也须保存明确决定。采用响应不确定时先读取核对，不直接重发。
- 已知实际生成输入漂移会使采用或新导出返回 `409`，应核对当前设置；历史输入未知不等于与最新设置一致，也不因此强制付费重做。导出前在 POST 之前保存 `{"request_key":"<本次导出UUID>","expected_take_ids":["<按片段position顺序的当前采用候选UUID>"]}`，再 `POST $RC/projects/$PID/exports`。必须列全原采用集合；响应丢失按原键恢复，不用当前新采用集合替换。旧 Export 的清单、文件和下载地址保留。
- 若原免费导出已明确失败或取消，核对同一采用集合及本次确认的原Export ID后，可取得明确授权、保存新UUID再尝试一次；未知、排队、运行或ready收据不能据此新建。另一客户端已有较新回执时先恢复它，旧确认不再创建第二次替代导出。此例外不适用于付费TTS/AI/ASR。
- 另行明确授权重新运行成书时，重新读取 preflight，使用 `{"request_key":"<新授权UUID>","fingerprint":"<新start_fingerprint>","speakers":false,"emotion":"off"}` 启动。这不是显式选段批次的重试，也不能用来恢复不确定请求。

## 统一原请求恢复

- 所有计费提交（autopilot、单段/批量 TTS、ASR、文章解读、说话人/读音/情绪扫描），以及导出和父命令，在 POST 前持久保存账号、项目、kind、UUID、原 endpoint、完整 body、原报价、范围与策略；不存令牌或 Key。未确认授权不换 UUID，不以重新估价或新请求猜测结果。
- 刷新、重启或响应丢失后的自动操作只允许 `GET $RC/projects/$PID/operations/$KEY?kind=autopilot`，kind 按原操作为 `autopilot|take|batch|asr|interpretation|speaker_scan|lexicon_scan|emotion_scan|export|autopilot_resume|autopilot_pause|autopilot_cancel`。
- 恢复仅限项目所属账号；管理员Cookie的跨账号巡查权限不授予恢复授权。必须使用原账号，不能凭知道UUID或切换管理路径查询他人的原请求。
- 返回 `{kind,request_key,resource_id,submitted,result}`。核对原 kind/key、目标资源及所有原提交字段；只容许服务端补齐省略的默认值，不接受改变原字段或数组范围。batch 的 resource_id 是原前缀首个候选，result.queued 保留原受理顺序；扫描 result 是将该原扫描放在 latest 的状态。submitted:null 是历史证据未知，不声称已验证原语义。
- 404、读取失败或网络错误都不表示原 POST 被拒绝；保留原键与内容，向用户解释只有明确重放才会再次 POST，且原请求从未到达时可能首次提交并计费。重放仍必须使用原 endpoint/body/key/quote/scope/strategy，不生成新键。新启动的 start_fingerprint 防止另一标签页用过期启动确认再次受理。

## 出错时
- `401`：令牌失效，请用户重新创建。
- `403`：令牌不能执行管理或账号操作，请用户在网页中操作。
- `404`：资源不存在或不属于签发账号；不要通过换 ID 或换路径尝试访问其他账号的作品。
- `409`：状态变化或已有任务在跑，重新读取后再决定下一步。
- `429`：等待 `Retry-After` 秒。
- `failed`：转述真实原因。`quota.blockers`区分`daily_bytes/daily_requests/daily_asr/concurrency/account/service/budget/pricing/configuration/request/unknown`；不要从中文文案猜类别，不把未知归为日额度。预算、配置、报价或服务问题需修正后再核对；已提交失败或不确定候选先核对候选与费用，不自动重复付费。
- AI错误按文章解读、说话人识别、读音扫描、情绪导演标明功能及HTTP/连接/超时/截断/拒答/JSON/领域校验原因。完整裸JSON或一个独占完整JSON围栏可以解析；额外解释、多份文档、重复字段、漏项或截断不猜补。坏返回不保存或应用，已知请求标识、usage和费用预留保留待核对。
- 原因写在`detail`、`error`或结构化`blockers[].message`中，是中文，可直接转述。自有Fish Key不豁免并发、账户、服务、配置及独立内容校对限制，也不代表供应商免费。