# 参考音频生音乐
> 以一段参考音频的风格为基础生成新音乐。

以一段参考音频的风格为基础生成新音乐。

## Agent 主路径

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

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

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/music-reference-audio-to-music.md

## 工具参数

```json
{
  "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。失败任务自动退款。

成功任务返回与[文生音乐](https://docs.beatra.ai/zh/docs/capabilities/music/text-to-music)相同的
`clips[]` 结构（`output.type` 为 `reference_audio_to_music`）。产物 URL 是
CDN 地址——请尽快转存到自己的存储。

## 通过 REST 调用

直连协议集成可使用 `POST /v1/music/reference-audio-to-music` 与共享任务
端点，参数见生成的[接口定义](https://docs.beatra.ai/zh/docs/api-reference/operations/music/ref_audio_to_music_v1_music_reference_audio_to_music_post)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。