AI 导演

先让 AI 导演读懂文字、安排演绎，再交给语音合成，让声音像真人在讲。

AI 导演会读懂原文和用户的要求，按目标声音能执行的写法，安排情绪、表演、音效、停顿和读音， 返回一份可以直接合成的配音稿。它只添加演绎，不改动原文的任何一个字。没有指定声音时， 它还会推荐一个合适的声音和模型，并说明理由。

Agent 主路径

通过 Universal Skill 使用 MCP 工具 beatra.speech.prepare_script。该工具计费，返回异步任务。

1. 把原文交给 input，用户对效果的要求（如有）交给 instructions。用户指定了声音或模型就一并传入； 没有就省略，让 AI 导演推荐。
2. 创建一个不透明的 client_request_id，只提交一次；用 beatra.tasks.get 轮询到终态。
3. 把结果里每一稿的 synthesis 原样作为 beatra.speech.synthesize 的参数，另加你自己的 client_request_id。synthesis 为 null 的稿子不能直接合成，原因见提示。
4. 用户想调整时（例如"第二段再紧张一点"），把这句话加进 instructions（保留之前的要求）再调用一次，然后重新合成。

AI 指南

工具参数

{
  "input": "夜深了，他推开门。“有人吗？”屋里没有回答。",
  "instructions": "悬疑一点，问话那句压低声音",
  "client_request_id": "script-opaque-1"
}

• input：原文，任何支持的语言，最多 50,000 字符。原文里已经写好的标记（如 {pause 0.5}）会原样保留， AI 导演只在此基础上添加。原文超出所指定声音或模型的单次上限时（ElevenLabs 为 10,000 字符）， 会直接返回与语音合成相同的 422 错误，不产生费用。
• instructions：可选，用户的要求，自然语言，任何语言，最多 2,000 字符。传了就以要求为准， 要求没提到的部分按文字本身的意思自然演绎；不传时整篇按文字的意思自然演绎。
• voice、model：可选，含义和默认规则与 beatra.speech.synthesize 相同。都不传时由 AI 导演推荐； 只传声音时在它支持的模型里选；只传模型时在这个模型可用的声音里推荐。
• language：可选，通常不传（默认 auto，自动识别）。只有用户指定了语言，或者文字本身看不出来的方言 （如粤语 yue）时才传。
• context：可选，进阶用法。分段导演长文时，传入这一段前后的文字 {"before": "…", "after": "…"}， 各最多 2,000 字符。只用来理解语气，不会被标注、朗读或返回；目标模型支持时，before 的结尾会作为建议的上文 放进 synthesis.previous_text，让前后语气接得上。

结果

任务成功后，output 里是一组配音稿：

{
  "type": "speech_script",
  "model": "ai-director",
  "directed": true,
  "scripts": [
    {
      "synthesis": {
        "input": "{emotion calm}夜深了，他推开门。{emotion fearful}{whisper}“有人吗？”屋里没有回答。",
        "voice": "voice_01JX...",
        "model": "elevenlabs-v4-turbo",
        "language": "zh"
      },
      "summary": "悬疑的开场，问话压低声音",
      "voice_selection": {
        "source": "recommended",
        "voice": "voice_01JX...",
        "model": "elevenlabs-v4-turbo",
        "name": "Wei",
        "preview_url": "https://cdn.beatra.cn/voices/previews/voice_01JX....mp3",
        "reason": "成熟男声，适合旁白，能逐句表演"
      },
      "alternatives": [
        {"voice": "voice_01JY...", "model": "minimax-speech-2.8-hd", "name": "念念",
         "preview_url": "https://cdn.beatra.cn/voices/previews/voice_01JY....mp3", "reason": "成熟女声，适合有声书"}
      ],
      "estimate": {"weighted_characters": 54, "price_credits": "13"},
      "warnings": []
    }
  ],
  "warnings": []
}

• scripts：每一稿对应一次合成调用。目前总是一稿；以后会有多稿（例如多人分配），请逐稿处理。
• synthesis：这一稿的合成参数，原样作为 beatra.speech.synthesize 的参数即可（另加 client_request_id）。 input 是写好标记的配音稿，另有 voice、model、language，以及目标声音确实执行的整段参数 emotion、direction、previous_text（不执行的不会出现）。这一稿不能直接合成时为 null： 没有可用的声音、声音读不了这份稿子，或这次没能完成预检（稍后重试即可），原因见提示。
• summary：一句话演绎说明，可以直接讲给用户听，不含参数名和标记。语言跟随 instructions； 没有要求时跟随原文。
• voice_selection：这一稿用的声音，包括 voice、model、声音名字 name 和试听链接 preview_url。 source 为 recommended 时由 AI 导演推荐，reason 是推荐理由；为 given 时是你指定的声音，reason 为 null。没有声音时整个字段为 null。
• alternatives：推荐声音时另给最多 3 个备选，字段与 voice_selection 相同（没有 source）； 指定了声音时为空列表。
• estimate：用这一稿合成的准确价格，与免费预检一致；synthesis 为 null 时它也为 null。
• directed：为 false 时 AI 导演这次没能完成演绎，稿子是原文，导演部分不收费；有 synthesis 时仍可以直接合成。
• 没有可推荐的声音时（提示 no_voice_available），synthesis、voice_selection 和 estimate 都为 null： 请用 beatra.voices.list 选一个声音，带上 voice 再调用一次。

想换成备选声音时，在 2 天内只改 voice（需要时连同 model），其余参数不变，用新的 client_request_id 再调用一次。AI 导演会复用上次的理解，同一份理解不会重复收费，只按新声音重新安排写法。这次调用同样要满足余额预估和 同时最多 2 个的限制，但复用的理解不会再收费。

不同模型上的演绎

AI 导演只写目标模型能执行的写法：

• ElevenLabs：逐句切换情绪，支持耳语、大喊等表演，以及笑声、叹气等音效。
• MiniMax：整段一种情绪，支持停顿、指定读音和音效。
• 豆包：整段一种情绪，支持停顿和指定读音；是否跟随情绪、表演指令和上文因音色而异。

用户明确要求的效果所选声音做不到时，AI 导演会完成其余部分，并在提示里说明做不到什么、用了什么代替。 需要逐句演绎时，可以换一个能逐句表演的声音。

提示

顶层 warnings 是 AI 导演给用户的说明，需要转告用户；每一稿的 warnings 是免费预检对这一稿的提示，通常为空。

计费与任务状态

AI 导演先推理再标注，按实际输入、输出和推理 token 后付费。价格和每千字的预估费用见 能力目录 GET /v1/catalog/capabilities/speech_script。提交时，余额需不低于这段文字的预估费用（不足 1,000 字按 1,000 字计）；如果本账号还有一个 AI 导演任务正在进行，还要加上它的预估费用。按每千字 146 积分计算，1 万字需要 1,460 积分。余额不足时返回 402 insufficient_balance，details.reason 为 director_estimate，不会创建任务。 最终按实际用量扣费，通常低于预估。directed 为 false，或复用了 2 天内的同一份理解时， 导演部分不收费。directed 为 true 时按实际 token 计费；AI 导演读完后判断原文已经合适、没有添加演绎时也是如此。 合成另按语音合成计费，价格见每一稿的 estimate。

每个账号同时最多 2 个 AI 导演任务在进行，全平台同时进行的数量也有上限。第 3 个请求返回 429 rate_limited， details.reason 为 director_inflight_limit（通过 MCP 调用时，套餐的同时进行上限可能先生效）；AI 导演当前繁忙时 返回 429，details.reason 为 director_busy。两种情况都不会开始任务，也不扣费。遇到 director_inflight_limit 时，请等本账号的一个 AI 导演任务结束后再提交；遇到 director_busy 时，请在 details.retry_after_seconds 秒后 重试（REST 的 Retry-After 响应头给出相同的秒数）。AI 导演暂时不可用时返回 503 model_unavailable；这项能力 不用选模型，请稍后重试。

queued 与 running 不是失败，请持续轮询同一个 task_id。创建响应丢失时，用同一个 client_request_id 原样重试；任何输入变化都要换新 ID。任务列表（GET /v1/tasks）里只显示结果的摘要：标有 truncated: true， 不含 synthesis；要拿到可以合成的配音稿，请按任务 ID 读取（beatra.tasks.get 或 GET /v1/tasks/{task_id}）。 AI 导演的结果是一份配音稿，不是作品，不会出现在作品墙；在控制台的动态和账单里显示为"AI 导演"。

通过 REST 调用

直连协议集成可使用 POST /v1/audio/speech/scripts 与共享任务端点：把每一稿的 synthesis 原样作为 POST /v1/audio/speech 的请求体。参数见生成的 接口定义。 推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。