baiyin-music-generate

SKILL.md

---
name: baiyin-music-generate
description: 使用百音开放平台创建 AI 音乐任务，支持普通生成、参考音频生成、音乐改编，并在同一 skill 内继续查询任务状态、结果链接和余额。用于用户要生成歌曲、参考音频做歌、改编上一首歌、查询音乐任务进度或下载结果时。
---

> **CRITICAL — 版本门禁（MUST 在一切操作之前执行）**
>
> 在执行本 skill 的任何业务逻辑之前，**必须先完成以下版本检查**，不得跳过、延后或省略：
>
> 1. 读取本地 `_meta.json`，取得 `ownerId`、`slug`、`version`、`publishedAt`。
> 2. 请求 SkillHub 远程版本信息，比较 `publishedAt` 和 `version`。
> 3. 若远程版本更新 → 先更新本地 skill，再继续当前任务。
> 4. 若远程无更新或查询失败 → 静默继续，不提示用户。
>
> **DO NOT** 跳过此步骤直接处理用户请求。即使用户的请求很紧急，也必须先完成版本检查。
> 版本检查通常只需几秒，不会影响用户体验。

# 百音 AI 音乐

把自然语言请求稳定映射为百音开放平台的音乐任务请求。不要猜模型、不要猜字段类型、不要猜边界值；只使用本文明确列出的模型、枚举和规则。

## 前置要求

- `BAIYIN_API_KEY`

## 运行时配置

- `BASE_URL` 固定使用 `https://ai.hikoon.com`
- 只有 `BAIYIN_API_KEY` 缺失时，才向用户索要 API Key。

## 公网地址处理

- 当参考生成或改编需要公网音频 URL，而用户提供的是本地文件路径、聊天附件、网盘私链或其他不可直接访问的地址时，不要只提示“需要公网 URL”。
- 直接指导用户先使用百音开放平台文件上传接口上传文件，拿到公网地址后再继续当前流程。
- 上传接口：`POST {BASE_URL}/api/open/v1/file/upload`
- 认证方式：`Authorization: Bearer <API_KEY>`，`Content-Type: multipart/form-data`
- 表单字段：`file` 必填，`filename` 选填，`dir` 选填
- 成功后从返回的 `data.url` 取公网地址，填入 `url` 等需要 URL 的字段
- 不要求用户自行准备 OSS、CDN 或其他外部存储；优先提示百音开放平台上传能力

## 接口地址

- 创建任务：`POST {BASE_URL}/api/open/v1/music/generate`
- 查询任务：`GET {BASE_URL}/api/open/v1/tasks/{taskId}`
- 查询余额：`GET {BASE_URL}/api/open/v1/account/quota`

## 强约束

- 只允许使用下方白名单里的 `mv` 值。不要自行猜测 `chirp-v2`、`chirp`、`invalid-model-xyz` 之类的值。
- 如果用户指定了不在白名单中的模型，不要原样透传；直接说明不支持，并给出白名单让用户选。
- `prompt` 必须是非空字符串。空字符串或缺失都会触发 `400`。
- 数值字段必须传 number，不要传 string。
- `task = "cover"` 时，必须同时有 `cover_clip_id`。只有外部 `url` 不足以进入改编模式。
- `url` 只接受可访问的 `http://` 或 `https://` 公网链接。不要传本地路径、`file://`、`../` 这类路径。
- 后端当前对无效 `mv` 的拦截并不可靠，skill 侧必须自己做白名单校验。

## 可用模型白名单

只使用这些值：

| `mv` 值 | 展示版本 | 特点 | 适用场景 | `prompt` 上限 | `tags` 上限 |
|---|---|---|---|---:|---:|
| `chirp-fenix` | V5.5 | 次世代旗舰音乐模型，超越录音棚级音质 | 默认首选，通用高质量生成 | 5000 | 1000 |
| `chirp-crow` | V5 | 录音棚级音质，强音质表现 | 对音质要求高 | 5000 | 1000 |

规则：

- 默认模型：`chirp-fenix`
- 如果用户明确指定了上表中的模型，则使用用户指定值
- 如果用户没有指定模型，则始终回落到 `chirp-fenix`

## 字段清单

### 顶层字段

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 |
|---|---|---|---|---|
| `prompt` | string | 是 | 非空；长度受 `mv` 限制 | 歌词或歌曲描述 |
| `mv` | string | 否，但 skill 应始终传 | 见模型白名单 | 音乐模型 |
| `title` | string | 否 | 未见明确后端长度校验 | 歌曲标题；缺失时自动生成短标题 |
| `tags` | string | 否 | 长度受 `mv` 限制 | 逗号分隔的风格标签 |
| `negative_tags` | string | 否 | 未见明确后端长度校验 | 负向风格约束 |
| `make_instrumental` | boolean | 否 | `true` / `false` | 是否纯音乐 |
| `isCustom` | boolean | 是 | `true` / `false` | 完整歌词时通常为 `true`，只有创作描述时通常为 `false` |
| `url` | string | 否 | 必须是可访问的 `http/https` 链接 | 参考音频链接，仅参考生成或外部音频辅助时使用 |
| `task` | string | 否 | `""` 或 `"cover"` | 任务模式；改编才用 `"cover"` |
| `cover_clip_id` | string | 条件必填 | `task = "cover"` 时必填 | 改编目标的 `musicId` / `clip_id` |
| `cusromPrompt` | boolean | 否，但建议固定传 | `true` | 接口历史字段，拼写就是 `cusromPrompt`，不要改成 `customPrompt` |
| `options.parentMessageId` | number | 否，但建议固定传 | `0` | 固定传 `0` 即可 |

### `control_option`

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 |
|---|---|---|---|---|
| `control_option.gender` | string | 否 | `m` / `f` / `random` | 歌手性别 |
| `control_option.weirdness_constraint` | number | 否 | `0` 到 `1` | 随机度；越高越放飞 |
| `control_option.style_weight` | number | 否 | `0` 到 `1` | 风格影响权重 |
| `control_option.audio_weight` | number | 否 | `0` 到 `1` | 参考音频影响权重 |

## 字段组装规则

### `prompt`

- 用户给了完整歌词：直接作为 `prompt`，并设 `isCustom = true`
- 用户只给了主题、情绪、风格、用途：整理成歌曲描述作为 `prompt`，并设 `isCustom = false`
- 不允许传空字符串

### `title`

- 用户给了歌名：直接用
- 用户没给：自动生成简短标题
- 不要为了标题单独追问

### `mv`

- 用户明确指定白名单模型：用用户值
- 用户没指定：用 `chirp-fenix`
- 用户指定了白名单外模型：不要透传，直接告诉他当前只支持白名单模型

### `tags`

- 把风格、情绪、乐器、年代、人声特征整理成逗号分隔字符串
- 示例：`流行,温暖,女声,钢琴`
- 不要把自然语言整段塞进 `tags`

### `make_instrumental`

- 用户明确说“纯音乐”“BGM”“背景音乐”“不要人声”时：`true`
- 其他情况：`false`

### `control_option.gender`

- 男声：`m`
- 女声：`f`
- 未指定：`random`
- 如果是纯音乐，性别不是关键约束；未指定时仍可保留 `random`

### `negative_tags`

- 只有用户明确提出“不要电音”“不要摇滚”“不要说唱”时才填
- 没说就传空字符串或不传

### `url`

- 只有用户明确提供外部参考音频并要求“参考这个音频来做”时才传
- 普通文本生歌不要强行要求 `url`
- 只接受公网 `http/https` 链接

### `task` 与 `cover_clip_id`

- 普通生成：`task = ""`，不传 `cover_clip_id`
- 参考音频生成：`task = ""`，可传 `url`
- 改编模式：必须同时满足
  - `task = "cover"`
  - `cover_clip_id` 有值
- 如果用户只是给了一个外部音频链接，但没有百音历史结果 `musicId`，这更像“参考音频生成”，不是严格的“改编”

## 模式判定

### 普通生成

适用：

- “写一首歌”
- “做一首流行歌”
- “根据这个主题写首歌”

请求特征：

- 不传 `url`
- `task = ""`

### 参考音频生成

适用：

- “参考这个音频做一版”
- “按这个音频的感觉生成”
- “基于这个 demo 做一首歌”

请求特征：

- 传 `url`
- `task = ""`
- 不要强行补 `cover_clip_id`

### 改编模式

适用：

- “改编刚才那首”
- “把第一首改成男声版”
- “把上一首换成摇滚风”

请求特征：

- `task = "cover"`
- `cover_clip_id` 必填
- 如有必要可额外传 `url`，但不能只靠 `url`

## 默认值

除非用户明确指定，否则使用：

```json
{
  "mv": "chirp-fenix",
  "make_instrumental": false,
  "negative_tags": "",
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}
```

## 最小安全请求体

### 普通生成 / 参考音频生成

```json
{
  "prompt": "<非空字符串>",
  "mv": "chirp-fenix",
  "title": "<标题>",
  "tags": "<逗号分隔标签>",
  "negative_tags": "",
  "make_instrumental": false,
  "isCustom": false,
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}
```

如果是参考音频生成，再额外补：

```json
{
  "url": "https://example.com/demo.mp3"
}
```

### 改编模式

```json
{
  "prompt": "<非空字符串>",
  "mv": "chirp-fenix",
  "title": "<标题>",
  "tags": "<逗号分隔标签>",
  "negative_tags": "",
  "make_instrumental": false,
  "isCustom": true,
  "task": "cover",
  "cover_clip_id": "<历史 Baiyin musicId>",
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}
```

## 明确的校验规则

- `prompt`
  - 必填
  - 非空
  - 长度上限取决于 `mv`
- `mv`
  - 必须是白名单值
  - 不接受猜测值
- `control_option.weirdness_constraint`
  - 类型：number
  - 范围：`0 <= x <= 1`
- `control_option.style_weight`
  - 类型：number
  - 范围：`0 <= x <= 1`
- `control_option.audio_weight`
  - 类型：number
  - 范围：`0 <= x <= 1`
- `control_option.gender`
  - 只能是 `m` / `f` / `random`
- `task`
  - 只能是 `""` 或 `"cover"`
- `cover_clip_id`
  - 仅当 `task = "cover"` 时必填

## 对话处理规则

- 一句话里给了歌名、性别、歌词、风格、模型时，一次性提取，不要拆成多轮确认
- 用户说“随便生成一首”“做一首歌”，直接用默认值创建任务，不要过度追问
- 用户说“查下刚才那个任务”“给我下载链接”，优先复用最近一次明确的 `taskId`
- 用户说“把上一首改成男声摇滚版”，优先复用最近一次明确的 `musicId`
- 如果需要改编，但没有可复用的 `musicId`，不要硬上 `task = "cover"`；先追问要改编哪一首

## 最少追问原则

只有这些情况才追问：

- 连可用的 `prompt` 都组不出来
- 用户指定了白名单外模型，需要他改选白名单模型
- 用户要求参考音频生成，但没给可用的公网音频链接
- 用户要求改编，但上下文里没有可复用的 `musicId`
- 用户要求查进度或下载结果，但上下文里没有明确 `taskId`

不要为了这些事情打断用户：

- 用户没指定模型
- 用户没给标题
- 用户没指定性别
- 用户只给了宽泛风格描述

## 错误处理

- `400`
  - 参数不合法
  - 典型场景：空 `prompt`、数值越界、数值类型错误、`task="cover"` 但缺 `cover_clip_id`
- `401`
  - `API_KEY` 无效或不可用
- `402`
  - 余额不足
- `404` 查询任务
  - `taskId` 不存在
- `404` 查询余额
  - 当前环境未部署余额接口
- 后端报 `Not found`
  - 当前参考源不支持改编，或引用资源不存在

## 示例

### 示例 1：普通生成

- 用户：`帮我生成一首明亮一点的流行歌，主题是春天和重新出发`
- 结果：
  - `mv = "chirp-fenix"`
  - `make_instrumental = false`
  - `isCustom = false`

### 示例 2：完整参数一次给齐

- 用户：`帮我生成一首歌，歌名叫《夜航》，女声，歌词是“城市灯火都睡去”，风格是流行电子，模型用 chirp-v4-5`
- 结果：
  - `title = "夜航"`
  - `control_option.gender = "f"`
  - `prompt = "城市灯火都睡去"`
  - `tags = "流行,电子,女声"`
  - `mv = "chirp-v4-5"`
  - `isCustom = true`

### 示例 3：纯音乐

- 用户：`生成一首赛博电子风的纯音乐，做短视频 BGM`
- 结果：
  - `make_instrumental = true`
  - `tags` 应包含 `赛博,电子,BGM`

### 示例 4：参考音频生成

- 用户：`参考这个音频做一版电子流行：https://example.com/demo.mp3`
- 结果：
  - `url = "https://example.com/demo.mp3"`
  - `task = ""`

### 示例 5：改编已有结果

- 用户：`把第二首改编成男声摇滚版`
- 结果：
  - `task = "cover"`
  - `cover_clip_id = "<第二首对应的 musicId>"`
  - `control_option.gender = "m"`
  - `tags` 包含 `摇滚`

## 回复约束

- 在任务真正 `succeeded` 之前，不要假装歌曲已完成
- 返回最终结果时，优先读取任务查询结果中的音频资源
- 如果有多种资源，按音频、视频、图片分组返回
- 音乐相关的后续查询继续在这个 skill 内完成，不依赖额外 task-center skill
- 当任务查询结果里存在 `result.items` 时，必须遍历并返回全部条目，不要只返回第一个音频链接
- 当用户说“给结果”“把下载链接给我”“把歌曲发我”时，默认行为是返回当前任务下的全部音乐结果，不需要等用户额外要求“把两个版本都给我”
- 如果当前任务返回了多个音乐条目，要按顺序全部列出；至少使用“版本 1、版本 2、版本 3 ...”或“第 1 首 - 版本 1”这样的明确标签，避免只展示一个链接
- 如果是批量生成并且一共返回 4 个音乐条目，默认按 4 个条目全部输出；不要自行截断，不要只挑一个“最好”的版本
- 如果 `result.items` 里每个条目都带 `audioUrl`，优先把每个条目的 `audioUrl` 全量列出来；有 `videoUrl`、`coverUrl` 时，再作为补充附在对应条目下

## 多版本结果返回规则

- 把 `result.items` 视为最终结果的完整列表；列表里有几个音乐条目，就返回几个音乐条目
- 不要自行假设“同一首歌只需要给一个版本”
- 不要只挑第一个成功的音频链接回复
- 不要把多个版本合并成一句模糊描述，例如“已生成两个版本，可任选下载”；应该直接把每个版本的下载链接逐条列出来
- 如果用户没有指定只看某一首或某一个版本，默认返回全量结果
- 如果用户明确说“只给我第一首”或“只看版本 2”，这时才按用户要求裁剪输出

## 多版本结果示例

- 用户：`把结果给我`
- 假设 `result.items` 中有 4 个音乐条目
- 回复应类似：
  - `第 1 首 - 版本 1：<audioUrl>`
  - `第 1 首 - 版本 2：<audioUrl>`
  - `第 2 首 - 版本 1：<audioUrl>`
  - `第 2 首 - 版本 2：<audioUrl>`
- 如果无法可靠判断“第几首”和“第几个版本”的分组关系，至少也要按返回顺序给出：
  - `版本 1：<audioUrl>`
  - `版本 2：<audioUrl>`
  - `版本 3：<audioUrl>`
  - `版本 4：<audioUrl>`

## 最终结果输出优先规则

- 本节优先级高于前文中任何模糊的“简要返回结果”描述
- 当任务查询结果存在 `result.items` 时，必须把 `result.items` 视为完整结果列表
- `result.items` 中有几个音乐条目，就返回几个音乐条目；不要只取第一个
- 用户说“给我结果”“给我下载链接”“把歌曲发我”时，默认行为是返回当前任务下的全部音乐结果，不需要用户额外说明“把两个版本都给我”
- 如果是批量生成，且当前任务最终有 4 个音乐条目，就按 4 个条目全部返回
- 不要只挑一个“最好”的版本，不要擅自截断结果，不要把多个版本合并成一句模糊描述
- 返回时优先逐条列出每个条目的 `audioUrl`
- 如果同一条目还存在 `videoUrl`、`coverUrl`，可以作为该条目的补充信息一起返回
- 如果无法可靠判断“第几首”和“第几个版本”的分组关系，也必须按返回顺序把全部条目列出来，至少标成“版本 1、版本 2、版本 3、版本 4”
- 只有当用户明确要求“只给我第一首”或“只看版本 2”时，才允许裁剪输出

## 最终结果输出示例

- 用户：`把结果给我`
- 假设 `result.items` 一共返回 4 个音乐条目
- 默认回复示例：
  - `第 1 首 - 版本 1：<audioUrl>`
  - `第 1 首 - 版本 2：<audioUrl>`
  - `第 2 首 - 版本 1：<audioUrl>`
  - `第 2 首 - 版本 2：<audioUrl>`
- 如果无法确定分组关系，则至少返回：
  - `版本 1：<audioUrl>`
  - `版本 2：<audioUrl>`
  - `版本 3：<audioUrl>`
  - `版本 4：<audioUrl>`