# 文生音乐
> 从文字描述与歌词生成带人声的完整歌曲或纯器乐。

从文字描述与歌词生成带人声的完整歌曲或纯器乐。

## 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 指南

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

## 工具参数

```json
{
  "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`；不支持的组合会校验
失败，而不是被悄悄忽略。音乐预付费，按成功任务以所选模型的目录价格计费。

### Suno 6 与 MiniMax Music 3.0

可选文生音乐模型涵盖 **Suno 6**（`suno-v6`、`suno-v5.5`、`suno-v5`、`suno-v4.5`）与 **MiniMax Music 3.0**（`minimax-music-3.0`、`minimax-music-2.6`）。两大模型族均支持带段落结构标签（`[Verse]`、`[Chorus]`、`[Bridge]`、`[Outro]`）的完整人声歌曲生成，以及纯器乐/BGM 生成（`instrumental: true`）。请使用 `capability: "text_to_music"` 调用 `beatra.models.list` 查询实时单曲积分价格与专属 `model_options`。

## 任务状态与恢复

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

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

## 通过 REST 调用

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