参考音频生音乐

Agent 主路径

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

用 beatra.assets.upload 上传本地参考音频并使用其 artifact ID；任何 Beatra 音乐任务成功产出的 artifact 也可以直接使用。
当模型、参考约束或价格有影响时，用 capability: "reference_audio_to_music" 调用 beatra.models.list；否则使用 model: "auto" 或省略 model。
创建一个不透明的 client_request_id，把最终参数提交一次。
用 beatra.tasks.get 轮询返回的任务直到终态。

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

工具参数

{
  "prompt": "Keep the groove of the reference track, shift it to a festive mood",
  "reference_audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "client_request_id": "music-cover-opaque-1"
}

reference_audio 接受 artifact、HTTPS URL 或 data URI。

模型、控制项与成本

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

beatra.models.list 是可选模型、参考音频的时长/大小/格式约束（constraints.reference_audio）、提示词与歌词上限、单任务客户价格的当前事实来源。不要把模型目录或价格表复制进 agent 提示词。

并非所有模型都支持全部控制项——例如纯器乐的参考音频请求需要所选模型支持。不支持的组合会校验失败，而不是被悄悄忽略。音乐预付费，按成功任务以所选模型的目录价格计费。

任务状态与恢复

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

成功任务返回与文生音乐相同的 clips[] 结构（output.type 为 reference_audio_to_music）。产物 URL 是 CDN 地址——请尽快转存到自己的存储。

通过 REST 调用

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