文生音乐

Agent 主路径

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

1. 确定产出：带人声还是纯器乐、情绪风格、用户是否提供歌词。
2. 当模型、控制项、约束或价格有影响时，用 capability: "text_to_music" 调用 beatra.models.list；否则使用 model: "auto" 或省略 model。
3. 创建一个不透明的 client_request_id，把最终参数提交一次。
4. 用 beatra.tasks.get 轮询返回的任务直到终态。

AI 指南

工具参数

{
  "prompt": "Upbeat city pop for a summer evening drive",
  "instrumental": false,
  "lyrics": "Evening wind sweeps across the rooftop\nNeon lights flicker on one by one",
  "client_request_id": "music-text-opaque-1"
}

instrumental: true 生成纯器乐，且不允许携带 lyrics。

模型、控制项与成本

通用控制项：prompt、lyrics、instrumental、title、 model_options。每个控制项只按所选模型的元数据使用。

beatra.models.list 是可选模型、提示词与歌词长度上限、人声歌词要求、 模型族选项与单任务客户价格的当前事实来源。不要把模型目录或价格表复制进 agent 提示词。

model_options.* 下的模型族选项要求显式指定 model；不支持的组合会校验 失败，而不是被悄悄忽略。音乐预付费，按成功任务以所选模型的目录价格计费。

任务状态与恢复

queued 与 running 不是失败。持续轮询同一个 task_id；不要因为任务还在 运行就提交替代请求。创建响应丢失时，用同一个 client_request_id 原样重试； 任何输入变化都要换新 ID。失败任务自动退款。

成功任务返回一个或多个 clips[]，各含标题、可选歌词与音频产物。产物 URL 是 CDN 地址——请尽快转存到自己的存储。

通过 REST 调用

直连协议集成可使用 POST /v1/music/text-to-music 与共享任务端点，参数见 生成的接口定义。 推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。